Publiq

Emails

Envía, consulta, lista y cancela correos transaccionales (`publiq.emails`).

El recurso emails cubre el ciclo de vida de un mensaje transaccional: enviar (cuerpo inline o por plantilla), seguir el estado, listar el historial y cancelar antes del despacho.

Referencia de métodos

emails.send

emails.send(params, { idempotencyKey? }) → Promise<Email>

Acepta y encola un correo para su entrega. El cuerpo puede ser inline (html/text) o venir de una plantilla (templateId o templateKey). Devuelve de inmediato con 202 — la entrega es asíncrona; síguela con emails.get o webhooks.

Parámetros
ParámetroTipoDescripción
fromObligatoriostringCorreo remitente. El dominio debe estar verificado. Ver Dominios & DNS.
toObligatoriostring | string[]Destinatario(s). Acepta un correo único o una lista (hasta 50 destinatarios en el sobre).
ccOpcionalstring | string[]Copia (Cc). Un correo o lista.
bccOpcionalstring | string[]Copia oculta (Bcc). Un correo o lista.
subjectOpcionalstringAsunto (máx. 998 caracteres). Obligatorio cuando el cuerpo no viene de una plantilla con asunto.
htmlOpcionalstringCuerpo HTML inline.
textOpcionalstringCuerpo texto-plano inline (fallback y mejor entregabilidad).
templateIdOpcionalstringID de una plantilla versionada. Alternativa a html/text.
templateKeyOpcionalstringKey legible de la plantilla (ej.: welcome-email) — alternativa amigable a templateId. Ver Plantillas.
variablesOpcionalobjectVariables de interpolación ({ first_name: "Ana" } → {{ first_name }}). Ver Variables.
tagsOpcionalobjectTags libres para búsqueda e informes (ej.: { campaign: "q3" }).
externalIdOpcionalstringCorrelación de tu lado (ej.: id del pedido).
idempotencyKeyOpcionalstring (opção)Clave de idempotencia (2º argumento, fuera del cuerpo). Si se omite, el SDK genera una automáticamente por llamada. Reintentos con la misma clave no duplican el correo. Ver Errores & idempotencia.

Devuelve: El correo creado — { object: "email", id, status: "queued", ... }. Guarda el id para consultar luego.

const email = await publiq.emails.send({
from: 'you@yourdomain.com',
to: ['ana@example.com', 'bob@example.com'],
cc: 'boss@example.com',
templateKey: 'welcome-email',
variables: { first_name: 'Ana', plan: 'Pro' },
tags: { campaign: 'onboarding' },
});
console.log(email.id, email.status); // "em_...", "queued"
Debes proveer algún cuerpo: html, text o una plantilla (templateId/templateKey). Ninguno → 400 validation_error. Un destinatario suprimido nunca recibe (filtro por destinatario). Ver Supresiones.
Buena práctica: pasa tu propio idempotencyKey (ej.: order-42-receipt) cuando el envío nace de un evento tuyo — así un retry tuyo nunca duplica el correo.

emails.get

emails.get(id) → Promise<Email>

Obtiene los detalles de un correo por id: estado actual, destinatarios (to/cc/bcc), provider, tags y timestamps de eventos (entregado, abierto, etc.).

Parámetros
ParámetroTipoDescripción
idObligatoriostringID del correo (devuelto por emails.send).

Devuelve: El correo con su estado e historial de eventos. 404 si no existe en la organización.

const email = await publiq.emails.get('em_123');
console.log(email.status); // "delivered"

emails.list

emails.list({ status?, limit?, after? }) → Promise<EmailList>

Lista los correos de la organización, del más reciente al más antiguo, paginado por cursor. Filtra por status para reconciliar entregas.

Parámetros
ParámetroTipoDescripción
statusOpcionalstringFiltra por estado: queued, processing, delivered, bounced, failed, canceled.
limitOpcionalnumberÍtems por página (por defecto 20, máx. 100).
afterOpcionalstringCursor: id del último ítem de la página anterior.

Devuelve: Envoltura de lista { object: "list", data: Email[] }. Usa el id del último ítem como after en la próxima llamada.

const { data } = await publiq.emails.list({ status: 'delivered', limit: 50 });
// next page:
const next = await publiq.emails.list({ after: data[data.length - 1].id });
El listado se pagina por cursor: itera pasando el id del último ítem en after hasta que data venga vacío. Ver Errores & paginación.

emails.cancel

emails.cancel(id) → Promise<Email>

Cancela un correo que aún está en la cola (queued), evitando el despacho. Útil para envíos programados o disparados por error.

Parámetros
ParámetroTipoDescripción
idObligatoriostringID del correo a cancelar.

Devuelve: El correo con status: "canceled". Devuelve 409 (conflict) si ya salió de la cola (processing/delivered).

await publiq.emails.cancel('em_123'); // only while queued
Trata el 409 como “demasiado tarde”: captura el error y sigue — el correo ya fue despachado. Ver Errores.

Los ejemplos muestran Node, Python y PHP. En Python los métodos son snake_case (ej.: cancel_run, from_spec) y reciben un dict; en PHP son camelCase y reciben un array asociativo. Las claves del cuerpo siempre son camelCase (templateKey, firstName, scheduledAt) — las respuestas de la API vienen en snake_case.

Emails — Publiq Docs