Emails

Envie, consulte, liste e cancele e-mails transacionais (`publiq.emails`).

O recurso emails cobre o ciclo de vida de uma mensagem transacional: enviar (corpo inline ou por template), acompanhar o status, listar o histórico e cancelar antes do despacho.

Referência de métodos

`emails.send`

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

Aceita e enfileira um e-mail para entrega. O corpo pode ser inline (html/text) ou vir de um template (templateId ou templateKey). Retorna imediatamente com 202 — a entrega é assíncrona; acompanhe por emails.get ou por webhooks.

Parâmetros

Parâmetro	Tipo	Descrição
`from`Obrigatório	`string`	E-mail remetente. O domínio precisa estar verificado. Veja Domínios & DNS.
`to`Obrigatório	`string \| string[]`	Destinatário(s). Aceita um e-mail único ou uma lista (até 50 destinatários no envelope).
`cc`Opcional	`string \| string[]`	Cópia (Cc). Um e-mail ou lista.
`bcc`Opcional	`string \| string[]`	Cópia oculta (Bcc). Um e-mail ou lista.
`subject`Opcional	`string`	Assunto (máx. 998 caracteres). Obrigatório quando o corpo não vem de um template com assunto.
`html`Opcional	`string`	Corpo HTML inline.
`text`Opcional	`string`	Corpo texto-plano inline (fallback e melhor entregabilidade).
`templateId`Opcional	`string`	ID de um template versionado. Alternativa a `html`/`text`.
`templateKey`Opcional	`string`	Key legível do template (ex.: `welcome-email`) — alternativa amigável ao `templateId`. Veja Templates.
`variables`Opcional	`object`	Variáveis de interpolação (`{ first_name: "Ana" }` → `{{ first_name }}`). Veja Variáveis.
`tags`Opcional	`object`	Tags livres para busca e relatórios (ex.: `{ campaign: "q3" }`).
`externalId`Opcional	`string`	Correlação do seu lado (ex.: id do pedido).
`idempotencyKey`Opcional	`string (opção)`	Chave de idempotência (2º argumento, fora do corpo). Se omitida, o SDK gera uma automaticamente por chamada. Reenvios com a mesma chave não duplicam o e-mail. Veja Erros & idempotência.

Retorna: O e-mail criado — { object: "email", id, status: "queued", ... }. Guarde o id para consultar depois.

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"

É preciso algum corpo: html, text ou um template (templateId/templateKey). Sem nenhum → 400 validation_error. Um destinatário suprimido nunca recebe (filtro por destinatário). Veja Supressões.

Boa prática: passe seu próprio idempotencyKey (ex.: order-42-receipt) quando o envio nasce de um evento do seu sistema — assim, um retry seu nunca duplica o e-mail.

`emails.get`

emails.get(id) → Promise<Email>

Busca os detalhes de um e-mail pelo id: status atual, destinatários (to/cc/bcc), provider, tags e timestamps de eventos (entregue, aberto, etc.).

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do e-mail (retornado por `emails.send`).

Retorna: O e-mail com o status e o histórico de eventos. 404 se não existir na organização.

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

`emails.list`

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

Lista os e-mails da organização, do mais recente ao mais antigo, com paginação por cursor. Filtre por status para reconciliar entregas.

Parâmetros

Parâmetro	Tipo	Descrição
`status`Opcional	`string`	Filtra por status: `queued`, `processing`, `delivered`, `bounced`, `failed`, `canceled`.
`limit`Opcional	`number`	Itens por página (padrão 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` do último item da página anterior.

Retorna: Envelope de lista { object: "list", data: Email[] }. Use o id do último item como after na próxima chamada.

const { data } = await publiq.emails.list({ status: 'delivered', limit: 50 });
// next page:
const next = await publiq.emails.list({ after: data[data.length - 1].id });

A listagem é paginada por cursor: itere passando o id do último item em after até data vir vazio. Veja Erros & paginação.

`emails.cancel`

emails.cancel(id) → Promise<Email>

Cancela um e-mail que ainda está na fila (queued), impedindo o despacho. Útil para agendamentos ou envios disparados por engano.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do e-mail a cancelar.

Retorna: O e-mail com status: "canceled". Retorna 409 (conflict) se já saiu da fila (processing/delivered).

await publiq.emails.cancel('em_123'); // only while queued

Trate o 409 como “tarde demais”: capture o erro e siga — o e-mail já foi despachado. Veja Erros.

Os exemplos mostram Node, Python e PHP. No Python os métodos são snake_case (ex.: cancel_run, from_spec) e recebem um dict; no PHP são camelCase e recebem um array associativo. As chaves do corpo são sempre camelCase (templateKey, firstName, scheduledAt) — o retorno da API vem em snake_case.