Documentation

Referência da API

API v1

A CoffeeMail expõe uma API REST pública para integração via API Key. Esta referência cobre apenas as rotas de Produto (/v1/product/*) consumidas pelo SDK Node e por clientes externos. Rotas internas (Plataforma e Infraestrutura) não fazem parte deste contrato público.

Escopo desta referência

Esta página documenta apenas as rotas públicas de Produto (/v1/product/*) consumidas por clientes externos via API Key. As rotas internas de Plataforma (/v1/platform/*, usadas pelo dashboard via cookie HttpOnly) e de Infraestrutura (/v1/internal/*) são reservadas e não fazem parte deste contrato público.

URL base

bashbash

https://api.coffeemail.com.br/v1/product

Autenticação

Todas as requisições exigem um Bearer Token no header Authorization. Você pode criar e revogar API Keys em Dashboard → Chaves de API.

bashbash

curl https://api.coffeemail.com.br/v1/product/emails \  -H "Authorization: Bearer cm_live_sua_chave" \  -H "Content-Type: application/json" \  -H "Accept-Language: pt-BR"

Chaves de Produto (prefixo cm_live_) e chaves de teste (prefixo cm_test_) são isoladas use chaves cm_test_ em desenvolvimento para não consumir quota.

Idioma

A API detecta o idioma pelo header Accept-Language. Valores suportados: pt-BR (padrão), en, es. Mensagens de validação e códigos de erro são localizados.

Formato de erro

Todas as respostas de erro seguem o mesmo envelope JSON:

JSONjson

{  "error": {    "code": "VALIDATION_ERROR",    "message": "O campo 'from' deve ser um e-mail válido.",    "details": { "field": "from" }  }}

Rate limit

Headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset são retornados em todas as requisições. Limites aplicados por chave de API e por IP. Veja a tabela completa em Códigos de erro.

Endpoints da API

Emails

POST/emails202 Accepted

Enviar emails

Enfileira um email transacional. Aceita HTML puro, texto puro, ou um templateId + variáveis. Suporta anexos (string base64 ou Uint8Array), headers customizados, agendamento (scheduledAt) e idempotência (idempotencyKey).

Request body

Campo	Tipo	Descrição
from*	string \| { email, name? }	Remetente (deve ser domínio verificado).
to*	string \| string[] \| { email, name? }[]	Um destinatário ou lista.
subject*	string	Assunto.
html	string	Conteúdo HTML.
text	string	Fallback em texto puro.
templateId	string	Renderiza um template existente.
variables	Record<string, unknown>	Variáveis para o template.
cc / bcc / replyTo	EmailAddressInput	Cópia, cópia oculta e reply-to.
attachments	EmailAttachment[]	Anexos. content aceita string base64 ou Uint8Array.
scheduledAt	ISO 8601 \| Date	Envio programado.
idempotencyKey	string	Evita duplicação em retries.
tags	EmailTag[]	Tags para métricas.
isSandbox	boolean	Não envia de fato (simulação).

Regras e limites de anexos

Suporta até 10 arquivos por e-mail com limite total acumulado de 25 MB. O conteúdo deve ser codificado em Base64 na API REST (o SDK Node aceita Buffer diretamente). O campo cid é obrigatório para anexos com disposition 'inline'.

Estrutura do objeto EmailAttachment

Campo	Tipo	Descrição
filename*	string (1-255)	Nome do arquivo com extensão (ex: fatura.pdf). Limite de 255 caracteres.
content*	string (Base64)	Conteúdo binário do arquivo codificado em Base64.
contentType*	string (MIME)	MIME type (ex: application/pdf, image/png). Padrão no SDK: application/octet-stream.
disposition*	'attachment' \| 'inline'	Modo de entrega: 'attachment' (download tradicional) ou 'inline' (embutido no corpo HTML).
cid	string (opcional)	Content-ID único usado para referenciar imagens inline no corpo HTML (ex: cid:logo referenciado em img).

Exemplo de requisição

curl (básico)

curl -X POST https://api.coffeemail.com.br/v1/product/emails \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "from": "noreply@seudominio.com.br",    "to": ["cliente@example.com"],    "subject": "Confirmação do pedido #123",    "html": "<h1>Obrigado!</h1><p>Seu pedido está em processamento.</p>"  }'

Response

Campo	Tipo	Descrição
id	string	Identificador único do email.
status	'queued' \| 'scheduled'	Status inicial após o envio.
queuedAt	string (ISO 8601)	Timestamp de entrada na fila.

Exemplo de resposta

JSONjson

{  "id": "eml_8f3a2c1b",  "status": "queued",  "queuedAt": "2026-09-10T18:21:14.000Z"}

GET/emails200 OK

Listar e-mails

Lista os e-mails da organização com paginação por cursor. Aceita filtros por status, destinatário, remetente, assunto, tag, API key e período.

Request body

Campo	Tipo	Descrição
status	'queued' \| 'processing' \| 'sent' \| 'delivered' \| 'bounced' \| 'complained' \| 'failed' \| 'skipped' \| 'scheduled' \| 'cancelled'	Filtra e-mails por status de envio.
recipient	string	Busca parcial por destinatário em to/cc/bcc.
fromEmail	string	Filtra e-mails por endereço do remetente.
subjectContains	string	Busca parcial no assunto do e-mail.
apiKeyId	string (uuid)	Filtra e-mails enviados por uma API key específica.
tag	string	Filtra e-mails que possuem esta tag.
from	string (ISO 8601)	Data/hora inicial do período de busca.
to	string (ISO 8601)	Data/hora final do período de busca.
after	string (ISO 8601)	Cursor de paginação para buscar registros seguintes.
limit	number	Quantidade máxima de e-mails retornados (padrão 50, máximo 100).

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/emails?status=delivered&limit=20" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
emails	EmailResponse[]	Lista de e-mails retornados.
nextCursor	string \| null	Cursor para buscar a próxima página, ou null se não houver mais registros.

Exemplo de resposta

JSONjson

{  "emails": [    {      "id": "5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a",      "from": "noreply@seudominio.com.br",      "to": ["cliente@example.com"],      "cc": null,      "bcc": null,      "subject": "Confirmação do pedido #123",      "status": "delivered",      "attempts": 1,      "lastError": null,      "messageId": "<abc123@coffeemail.com.br>",      "apiKey": { "id": "9c1a2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "name": "chave-producao" },      "createdAt": "2026-09-10T18:21:14.000Z",      "scheduledAt": null,      "sentAt": "2026-09-10T18:21:16.000Z",      "deliveredAt": "2026-09-10T18:21:20.000Z",      "bouncedAt": null,      "failedAt": null,      "complainedAt": null,      "suppressedAt": null,      "openedAt": null,      "firstClickedAt": null,      "openCount": 0,      "clickCount": 0,      "tags": [{ "name": "order_id", "value": "123" }],      "html": "<h1>Obrigado!</h1>",      "text": null    }  ],  "nextCursor": null}

POST/emails/batch202 Accepted

Enviar e-mails em lote

Envia até 100 e-mails em uma única chamada. Cada item segue o mesmo formato do envio individual (from, to, subject/html/text ou templateId, etc). Falhas em itens individuais não derrubam o lote inteiro.

Request body

Campo	Tipo	Descrição
(array)*	SendEmailRequest[]	Array com de 1 a 100 payloads de envio, no mesmo formato de POST /emails.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/emails/batch \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '[    {      "from": "noreply@seudominio.com.br",      "to": ["cliente1@example.com"],      "subject": "Pedido #123 confirmado",      "html": "<p>Seu pedido foi confirmado.</p>"    },    {      "from": "noreply@seudominio.com.br",      "to": ["cliente2@example.com"],      "subject": "Pedido #124 confirmado",      "html": "<p>Seu pedido foi confirmado.</p>"    }  ]'

Response

Campo	Tipo	Descrição
[].ok	boolean	Indica se o item foi aceito com sucesso.
[].data.id	string	Identificador único do e-mail criado (quando ok é true).
[].data.status	'queued' \| 'scheduled'	Status inicial do e-mail após o envio (quando ok é true).
[].data.queuedAt	string (ISO 8601)	Timestamp de entrada na fila (quando ok é true).
[].error	string	Mensagem de erro do item que falhou (quando ok é false).

Exemplo de resposta

JSONjson

[  {    "ok": true,    "data": {      "id": "5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a",      "status": "queued",      "queuedAt": "2026-09-10T18:21:14.000Z"    }  },  {    "ok": false,    "error": "domain not verified"  }]

GET/emails/tags200 OK

Listar tags usadas

Retorna as tags distintas já usadas em e-mails enviados pela organização, junto com os valores registrados para cada uma. Útil para popular filtros na UI.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/emails/tags \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
tags	{ name, values }[]	Tags distintas usadas em e-mails, cada uma com seus valores já registrados.

Exemplo de resposta

JSONjson

{  "tags": [    { "name": "order_id", "values": ["123", "124"] },    { "name": "campaign", "values": ["black-friday"] }  ]}

GET/emails/:id200 OK

Buscar e-mail por ID

Retorna os detalhes completos de um e-mail: status, tentativas, timestamps do ciclo de vida, tags, corpo (html/text) e a API key usada no envio.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/emails/5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string (uuid)	ID único do e-mail.
from	string	Endereço do remetente.
to	string[]	Lista de destinatários.
cc / bcc	string[] \| null	Lista de destinatários em cópia e em cópia oculta.
subject	string \| null	Assunto do e-mail.
status	'queued' \| 'processing' \| 'sent' \| 'delivered' \| 'bounced' \| 'failed' \| 'skipped' \| 'scheduled' \| 'cancelled'	Status atual do envio.
attempts	number	Número de tentativas de envio realizadas.
lastError	string \| null	Última mensagem de erro registrada no envio.
messageId	string \| null	ID da mensagem retornado pelo provedor de envio.
createdAt / scheduledAt / sentAt	string (ISO 8601) \| null	Data/hora de criação, agendamento e envio do e-mail.
deliveredAt / bouncedAt / failedAt / complainedAt / suppressedAt	string (ISO 8601) \| null	Data/hora de entrega, bounce, falha ou reclamação de spam, se houve.
openedAt / firstClickedAt	string (ISO 8601) \| null	Data/hora da primeira abertura e do primeiro clique em um link.
openCount / clickCount	number	Quantidade de aberturas e cliques registrados.
tags	{ name, value }[] \| null	Tags associadas ao e-mail.
html / text	string \| null	Corpo do e-mail em HTML e em texto puro.
apiKey	{ id, name } \| null	API key usada para enviar o e-mail.

Exemplo de resposta

JSONjson

{  "id": "5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a",  "from": "noreply@seudominio.com.br",  "to": ["cliente@example.com"],  "cc": null,  "bcc": null,  "subject": "Confirmação do pedido #123",  "status": "delivered",  "attempts": 1,  "lastError": null,  "messageId": "<abc123@coffeemail.com.br>",  "createdAt": "2026-09-10T18:21:14.000Z",  "scheduledAt": null,  "sentAt": "2026-09-10T18:21:16.000Z",  "deliveredAt": "2026-09-10T18:21:20.000Z",  "bouncedAt": null,  "failedAt": null,  "complainedAt": null,  "suppressedAt": null,  "openedAt": null,  "firstClickedAt": null,  "openCount": 0,  "clickCount": 0,  "tags": [{ "name": "order_id", "value": "123" }],  "html": "<h1>Obrigado!</h1>",  "text": null,  "apiKey": { "id": "9c1a2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "name": "chave-producao" }}

GET/emails/:id/events200 OK

Linha do tempo de eventos

Retorna o histórico de eventos de um e-mail (fila, processamento, envio, entrega, abertura, clique, bounce, reclamação, falha), em ordem cronológica.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/emails/5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a/events \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string (uuid)	ID único do e-mail.
events	{ type, timestamp, metadata? }[]	Linha do tempo de eventos do e-mail, cada um com tipo, timestamp e metadata opcional.

Exemplo de resposta

JSONjson

{  "id": "5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a",  "events": [    { "type": "queued", "timestamp": "2026-09-10T18:21:14.000Z" },    { "type": "sent", "timestamp": "2026-09-10T18:21:16.000Z" },    { "type": "delivered", "timestamp": "2026-09-10T18:21:20.000Z" },    { "type": "opened", "timestamp": "2026-09-10T18:25:02.000Z", "metadata": { "userAgent": "Mozilla/5.0" } }  ]}

POST/emails/:id/cancel204 No Content

Cancelar e-mail agendado

Cancela um e-mail que ainda está no status scheduled. Não tem efeito sobre e-mails que já entraram em processamento ou foram enviados. Não retorna corpo na resposta.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/emails/5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a/cancel \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

POST/emails/:id/resend202 Accepted

Reenviar e-mail

Reenfileira um e-mail que falhou ou foi cancelado, criando um novo ciclo de envio.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/emails/5b3f9e2a-6c1d-4e8a-9f0b-2a1c3d4e5f6a/resend \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string	Identificador único do novo envio.
status	'queued' \| 'scheduled'	Status inicial do e-mail após o reenvio.
queuedAt	string (ISO 8601)	Timestamp de entrada na fila.

Exemplo de resposta

JSONjson

{  "id": "7d4a1e2b-8c3f-4a5b-9c6d-1e2f3a4b5c6d",  "status": "queued",  "queuedAt": "2026-09-10T19:02:31.000Z"}

Domínios

POST/domains201 Created

Adicionar domínio

Registra um domínio na organização e retorna os registros DNS (SPF, DKIM, DMARC e ownership) que precisam ser configurados no provedor.

Request body

Campo	Tipo	Descrição
name*	string	FQDN a ser cadastrado (ex: empresa.com.br).

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/domains \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "empresa.com.br" }'

Response

Campo	Tipo	Descrição
id	string	ID do domínio.
name	string	Nome do domínio.
status	'verified' \| 'pending' \| 'failed'	Status de validação.
records	DomainDnsRecord[]	SPF/DKIM/DMARC/ownership.

POST/domains/:id/verify202 Accepted

Verificar domínio

Executa a verificação sob demanda dos registros DNS. Retorna checks detalhados (spf, dkim, dmarc, ownership).

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/domains/dom_123/verify \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

POST/domains/:id/health200 OK

Saúde do domínio

Diagnóstico de reputação, presença em blacklists e recomendações de melhoria.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/domains/dom_123/health \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

GET/domains200 OK

Listar domínios

Lista todos os domínios cadastrados na organização, com status de verificação e dados de DKIM.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/domains \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
domains	DomainListItem[]	Lista de domínios cadastrados na organização.
domains[].id	string (uuid)	ID do domínio.
domains[].name	string	Nome do domínio.
domains[].status	'pending' \| 'verified' \| 'failed'	Situação atual da verificação do domínio.
domains[].dkimSelector	string	Seletor usado no registro DKIM do domínio.
domains[].dkimPublicKey	string \| null	Chave pública DKIM gerada para o domínio.
domains[].verifiedAt	string (ISO 8601) \| null	Data e hora em que o domínio foi verificado.
domains[].lastCheckAt	string (ISO 8601) \| null	Data e hora da última verificação de DNS realizada.
domains[].createdAt	string (ISO 8601)	Data e hora em que o domínio foi cadastrado.

Exemplo de resposta

JSONjson

{  "domains": [    {      "id": "5e2f1a3c-9b7d-4e6a-8c1f-2d3b4a5e6f7a",      "name": "empresa.com.br",      "status": "verified",      "dkimSelector": "cm2026",      "dkimPublicKey": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...",      "verifiedAt": "2026-08-20T14:03:11.000Z",      "lastCheckAt": "2026-09-09T09:12:00.000Z",      "createdAt": "2026-08-19T10:00:00.000Z"    }  ]}

GET/domains/:id200 OK

Obter domínio

Retorna o detalhe de um domínio, incluindo os registros DNS (TXT/CNAME) pendentes de publicação.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/domains/dom_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string (uuid)	ID do domínio.
name	string	Nome do domínio.
status	'pending' \| 'verified' \| 'failed'	Situação atual da verificação do domínio.
dkimSelector	string	Seletor usado no registro DKIM do domínio.
dkimPublicKey	string \| null	Chave pública DKIM gerada para o domínio.
verifiedAt	string (ISO 8601) \| null	Data e hora em que o domínio foi verificado.
lastCheckAt	string (ISO 8601) \| null	Data e hora da última verificação de DNS realizada.
createdAt	string (ISO 8601)	Data e hora em que o domínio foi cadastrado.
dnsRecordsToPublish	DnsRecord[]	Registros DNS pendentes que o cliente precisa publicar.
dnsRecordsToPublish[].type	'TXT' \| 'CNAME'	Tipo do registro DNS a ser publicado (TXT ou CNAME).
dnsRecordsToPublish[].host	string	Nome do host/subdomínio onde o registro deve ser criado.
dnsRecordsToPublish[].value	string	Valor que deve ser publicado no registro DNS.
dnsRecordsToPublish[].ttl	number	TTL em segundos sugerido para o registro.

Exemplo de resposta

JSONjson

{  "id": "5e2f1a3c-9b7d-4e6a-8c1f-2d3b4a5e6f7a",  "name": "empresa.com.br",  "status": "pending",  "dkimSelector": "cm2026",  "dkimPublicKey": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC...",  "verifiedAt": null,  "lastCheckAt": "2026-09-09T09:12:00.000Z",  "createdAt": "2026-08-19T10:00:00.000Z",  "dnsRecordsToPublish": [    {      "type": "TXT",      "host": "_coffeemail.empresa.com.br",      "value": "coffeemail-site-verification=abc123",      "ttl": 3600    },    {      "type": "CNAME",      "host": "cm2026._domainkey.empresa.com.br",      "value": "cm2026.dkim.coffeemail.com.br"    }  ]}

DELETE/domains/:id200 OK

Remover domínio

Remove (soft-delete) um domínio da organização. Se a conta tiver reautenticação configurada, é necessário enviar method + credential; limite de 5 requisições por minuto.

Request body

Campo	Tipo	Descrição
method	'totp' \| 'password'	Método de reautenticação, 'totp' ou 'password'. Obrigatório apenas se a conta tiver reauth configurado.
credential	string	Código TOTP ou senha usada para confirmar a exclusão.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/domains/dom_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "method": "totp", "credential": "123456" }'

Response

Campo	Tipo	Descrição
ok	boolean	Confirma que o domínio foi removido.

Exemplo de resposta

JSONjson

{  "ok": true}

GET/domains/:id/warmup200 OK

Status de warmup

Consulta o progresso do aquecimento (warmup) de IP/domínio. Retorna null quando o domínio ainda não iniciou o warmup.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/domains/dom_123/warmup \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
domainId	string (uuid)	ID do domínio.
currentDay	number	Dia atual do período de aquecimento (warmup).
dailyQuota	number	Limite diário de envios permitido para o dia atual.
sentToday	number	Quantidade de emails já enviados hoje.
remainingToday	number	Quantidade de envios restantes na cota diária.
quotaUsedPercent	number (0-100)	Percentual da cota diária já utilizado.
lastSendDate	string \| null	Data do último envio registrado para o domínio.

Exemplo de resposta

JSONjson

{  "domainId": "5e2f1a3c-9b7d-4e6a-8c1f-2d3b4a5e6f7a",  "currentDay": 4,  "dailyQuota": 500,  "sentToday": 120,  "remainingToday": 380,  "quotaUsedPercent": 24,  "lastSendDate": "2026-09-10"}

Modelos

POST/templates201 Created

Criar modelo

Cadastra um template. Suporta HTML com Handlebars (format: handlebars) ou TSX com React Email (format: react_email).

Request body

Campo	Tipo	Descrição
name*	string	Nome do modelo.
subject	string	Assunto padrão.
html	string	Conteúdo (Handlebars).
text	string	Versão em texto puro.
format	'handlebars' \| 'react_email'	Engine do template.
variables	{ name, defaultValue? }[]	Variáveis esperadas.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/templates \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Boas-vindas",    "subject": "Bem-vindo, {{ name }}!",    "html": "<h1>Oi {{ name }}</h1>",    "format": "handlebars",    "variables": [{ "name": "name", "defaultValue": "" }]  }'

POST/templates/preview200 OK

Renderizar preview

Renderiza um preview sem precisar enviar útil para o playground e validação de variáveis.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/templates/preview \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "html": "<h1>Oi {{ name }}</h1>", "format": "html", "variables": { "name": "Maria" } }'

GET/templates200 OK

Listar templates

Retorna todos os templates cadastrados na organização, com o código-fonte completo de cada um.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/templates \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
data	TemplateDetail[]	Lista de templates de e-mail cadastrados.
data[].id	string (uuid)	Identificador único do template.
data[].name	string	Nome do template.
data[].subject	string \| null	Assunto padrão do e-mail.
data[].html	string	Código-fonte HTML ou JSX do template.
data[].textPayload	string \| null	Versão em texto simples do template.
data[].variables	{ name, description? }[]	Variáveis disponíveis para interpolação no template.
data[].isActive	boolean	Indica se o template está ativo para uso.
data[].format	'html' \| 'react'	Formato do código-fonte do template.
data[].sourceLocale	string	Idioma de origem do conteúdo do template.
data[].starterSlug	string \| null	Slug do template inicial usado como base, se houver.
data[].createdAt	string (ISO 8601)	Data de criação do template.
data[].updatedAt	string (ISO 8601)	Data da última atualização do template.

Exemplo de resposta

JSONjson

{  "data": [    {      "id": "3f9a2c1b-6e2d-4b3a-9c5f-1a2b3c4d5e6f",      "name": "Boas-vindas",      "subject": "Bem-vindo, {{ name }}!",      "html": "<h1>Oi {{ name }}</h1>",      "textPayload": null,      "variables": [{ "name": "name", "description": "Nome do destinatário" }],      "isActive": true,      "format": "html",      "sourceLocale": "pt-BR",      "starterSlug": null,      "createdAt": "2026-08-01T12:00:00.000Z",      "updatedAt": "2026-08-01T12:00:00.000Z"    }  ]}

GET/templates/:id200 OK

Buscar template

Retorna um template específico pelo id, com o código-fonte completo e as variáveis disponíveis.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/templates/3f9a2c1b-6e2d-4b3a-9c5f-1a2b3c4d5e6f \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador único do template.
name	string	Nome do template.
subject	string \| null	Assunto padrão do e-mail.
html	string	Código-fonte HTML ou JSX do template.
textPayload	string \| null	Versão em texto simples do template.
variables	{ name, description? }[]	Variáveis disponíveis para interpolação no template.
isActive	boolean	Indica se o template está ativo para uso.
format	'html' \| 'react'	Formato do código-fonte do template.
sourceLocale	string	Idioma de origem do conteúdo do template.
starterSlug	string \| null	Slug do template inicial usado como base, se houver.
createdAt	string (ISO 8601)	Data de criação do template.
updatedAt	string (ISO 8601)	Data da última atualização do template.

Exemplo de resposta

JSONjson

{  "id": "3f9a2c1b-6e2d-4b3a-9c5f-1a2b3c4d5e6f",  "name": "Boas-vindas",  "subject": "Bem-vindo, {{ name }}!",  "html": "<h1>Oi {{ name }}</h1>",  "textPayload": null,  "variables": [{ "name": "name", "description": "Nome do destinatário" }],  "isActive": true,  "format": "html",  "sourceLocale": "pt-BR",  "starterSlug": null,  "createdAt": "2026-08-01T12:00:00.000Z",  "updatedAt": "2026-08-01T12:00:00.000Z"}

PATCH/templates/:id200 OK

Atualizar template

Atualiza parcialmente um template existente. Envie somente os campos que quer alterar.

Request body

Campo	Tipo	Descrição
name	string	Novo nome do template.
subject	string \| null	Novo assunto padrão do e-mail.
html	string	Novo código-fonte HTML ou JSX.
textPayload	string \| null	Nova versão em texto simples.
variables	{ name, description? }[]	Nova lista de variáveis disponíveis para interpolação.
format	'html' \| 'react'	Novo formato do código-fonte.
isActive	boolean	Ativa ou desativa o template.
sourceLocale	string	Novo idioma de origem do conteúdo.
starterSlug	string \| null	Slug do template inicial usado como base.

Exemplo de requisição

curl

curl -X PATCH https://api.coffeemail.com.br/v1/product/templates/3f9a2c1b-6e2d-4b3a-9c5f-1a2b3c4d5e6f \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "isActive": false }'

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador único do template.
name	string	Nome do template.
isActive	boolean	Indica se o template está ativo para uso.
updatedAt	string (ISO 8601)	Data da última atualização do template.

Exemplo de resposta

JSONjson

{  "id": "3f9a2c1b-6e2d-4b3a-9c5f-1a2b3c4d5e6f",  "name": "Boas-vindas",  "subject": "Bem-vindo, {{ name }}!",  "html": "<h1>Oi {{ name }}</h1>",  "textPayload": null,  "variables": [{ "name": "name", "description": "Nome do destinatário" }],  "isActive": false,  "format": "html",  "sourceLocale": "pt-BR",  "starterSlug": null,  "createdAt": "2026-08-01T12:00:00.000Z",  "updatedAt": "2026-09-10T09:30:00.000Z"}

DELETE/templates/:id204 No Content

Excluir template

Remove um template definitivamente. A ação não pode ser desfeita.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/templates/3f9a2c1b-6e2d-4b3a-9c5f-1a2b3c4d5e6f \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

POST/templates/format200 OK

Formatar template

Formata o código-fonte de um template (HTML ou JSX) via Prettier, sem persistir nada.

Request body

Campo	Tipo	Descrição
html*	string	Código-fonte HTML ou JSX a ser formatado.
format	'html' \| 'react'	Formato do código de origem.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/templates/format \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "html": "<h1>Oi   {{name}}</h1>", "format": "html" }'

Response

Campo	Tipo	Descrição
html	string	Código-fonte formatado.

Exemplo de resposta

JSONjson

{  "html": "<h1>Oi {{ name }}</h1>\n"}

POST/templates/test-render200 OK

Renderizar teste sanitizado

Renderiza um template com variáveis e sanitiza o HTML resultante (remove scripts, iframes, links javascript: e handlers de evento inline). Diferente de /templates/preview, que não sanitiza use este endpoint para testar conteúdo não confiável.

Request body

Campo	Tipo	Descrição
html*	string	Código-fonte HTML ou JSX do template a renderizar.
format	'html' \| 'react'	Formato do template de origem.
variables	Record<string, unknown>	Valores das variáveis usadas para popular o template.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/templates/test-render \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "html": "<h1>Oi {{ name }}</h1><script>alert(1)</script>", "format": "html", "variables": { "name": "Maria" } }'

Response

Campo	Tipo	Descrição
html	string	HTML final renderizado e sanitizado.
text	string	Versão em texto simples do e-mail renderizado.
sanitizeReport	{ scripts, iframes, javascriptHrefs, eventHandlers }	Relatório com a quantidade de elementos removidos pela sanitização (scripts, iframes, links javascript: e handlers de evento).

Exemplo de resposta

JSONjson

{  "html": "<h1>Oi Maria</h1>",  "text": "Oi Maria",  "sanitizeReport": {    "scripts": 1,    "iframes": 0,    "javascriptHrefs": 0,    "eventHandlers": 0  }}

Audiências e contatos

POST/audiences201 Created

Criar audiência

Cria uma lista segmentada de contatos.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/audiences \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "Newsletter PT", "description": "Leads do blog BR" }'

POST/audiences/:id/contacts201 Created

Adicionar contato

Insere um contato em uma audiência. Aceita firstName, lastName e metadata arbitrária.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/audiences/aud_123/contacts \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "email": "maria@example.com", "firstName": "Maria", "metadata": { "plan": "pro" } }'

GET/audiences200 OK

Listar audiências

Lista as audiências da organização, com paginação.

Request body

Campo	Tipo	Descrição
limit	number	Quantidade máxima de itens por página (padrão 50, máximo 200).
offset	number	Quantidade de itens a pular a partir do início (padrão 0).

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/audiences?limit=50&offset=0" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
audiences	Audience[]	Lista de audiências encontradas.
total	number	Total de audiências da organização.

Exemplo de resposta

JSONjson

{  "audiences": [    {      "id": "aud_123",      "name": "Newsletter PT",      "description": "Leads do blog BR",      "active": true,      "contactsCount": 0,      "createdAt": "2026-09-01T12:00:00.000Z",      "updatedAt": "2026-09-01T12:00:00.000Z"    }  ],  "total": 1}

GET/audiences/:id200 OK

Obter audiência

Retorna os dados de uma audiência específica.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/audiences/aud_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string	Identificador único da audiência.
name	string	Nome da audiência.
description	string \| null	Descrição da audiência.
active	boolean	Se a audiência está ativa.
contactsCount	number	Quantidade de contatos na audiência.
createdAt	string (ISO 8601)	Data de criação da audiência.
updatedAt	string (ISO 8601)	Data da última atualização da audiência.

Exemplo de resposta

JSONjson

{  "id": "aud_123",  "name": "Newsletter PT",  "description": "Leads do blog BR",  "active": true,  "contactsCount": 42,  "createdAt": "2026-09-01T12:00:00.000Z",  "updatedAt": "2026-09-05T09:30:00.000Z"}

PUT/audiences/:id200 OK

Atualizar audiência

Atualiza nome, descrição e/ou status de uma audiência. Pelo menos um campo deve ser enviado.

Request body

Campo	Tipo	Descrição
name	string	Novo nome da audiência.
description	string \| null	Nova descrição da audiência. Envie null para limpar.
active	boolean	Se a audiência está ativa.

Exemplo de requisição

curl

curl -X PUT https://api.coffeemail.com.br/v1/product/audiences/aud_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "Newsletter PT-BR", "active": false }'

Response

Campo	Tipo	Descrição
id	string	Identificador único da audiência atualizada.

Exemplo de resposta

JSONjson

{  "id": "aud_123"}

DELETE/audiences/:id204 No Content

Excluir audiência

Remove permanentemente uma audiência e seus contatos. Não retorna corpo na resposta.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/audiences/aud_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

GET/audiences/:id/contacts200 OK

Listar contatos da audiência

Lista os contatos de uma audiência, com paginação.

Request body

Campo	Tipo	Descrição
limit	number	Quantidade máxima de itens por página (padrão 100, máximo 500).
offset	number	Quantidade de itens a pular a partir do início (padrão 0).

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/audiences/aud_123/contacts?limit=100&offset=0" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
contacts	Contact[]	Lista de contatos encontrados.
total	number	Total de contatos na audiência.

Exemplo de resposta

JSONjson

{  "contacts": [    {      "id": "cnt_123",      "email": "maria@example.com",      "firstName": "Maria",      "lastName": null,      "metadata": { "plan": "pro" },      "createdAt": "2026-09-01T12:00:00.000Z"    }  ],  "total": 1}

POST/audiences/:id/contacts/bulk200 OK

Adicionar contatos em lote

Adiciona até 10.000 contatos de uma vez a uma audiência.

Request body

Campo	Tipo	Descrição
contacts*	{ email, firstName?, lastName?, metadata? }[]	Lista de contatos a adicionar (email obrigatório; firstName, lastName e metadata opcionais).

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/audiences/aud_123/contacts/bulk \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "contacts": [      { "email": "maria@example.com", "firstName": "Maria" },      { "email": "joao@example.com", "firstName": "João", "metadata": { "plan": "free" } }    ]  }'

Response

Campo	Tipo	Descrição
inserted	number	Quantidade de contatos inseridos com sucesso.
skipped	number	Quantidade de contatos ignorados (ex.: e-mails duplicados na audiência).
errors	{ email, reason }[]	Lista de erros por e-mail, com o motivo de cada falha.

Exemplo de resposta

JSONjson

{  "inserted": 1,  "skipped": 1,  "errors": [    { "email": "joao@example.com", "reason": "duplicate email in audience" }  ]}

PUT/audiences/:id/contacts/:contactId200 OK

Atualizar contato

Atualiza firstName, lastName e/ou metadata de um contato. Pelo menos um campo deve ser enviado.

Request body

Campo	Tipo	Descrição
firstName	string \| null	Novo primeiro nome do contato. Envie null para limpar.
lastName	string \| null	Novo sobrenome do contato. Envie null para limpar.
metadata	Record<string, unknown>	Dados extras do contato em formato livre.

Exemplo de requisição

curl

curl -X PUT https://api.coffeemail.com.br/v1/product/audiences/aud_123/contacts/cnt_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "firstName": "Maria", "metadata": { "plan": "enterprise" } }'

Response

Campo	Tipo	Descrição
id	string	Identificador único do contato atualizado.

Exemplo de resposta

JSONjson

{  "id": "cnt_123"}

DELETE/audiences/:id/contacts/:contactId204 No Content

Remover contato

Remove um contato de uma audiência. Não retorna corpo na resposta.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/audiences/aud_123/contacts/cnt_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Campanhas (broadcasts)

POST/broadcasts201 Created

Criar campanha

Cria uma campanha para uma audiência. Pode usar um template existente (templateId) ou HTML próprio. Aceita agendamento via scheduledAt.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/broadcasts \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "audienceId": "aud_123",    "fromEmail": "news@seudominio.com.br",    "subject": "Novidades da semana",    "templateId": "tpl_123"  }'

POST/broadcasts/:id/send202 Accepted

Disparar campanha

Coloca a campanha em estado de envio. Os cabeçalhos RFC 8058 (List-Unsubscribe e List-Unsubscribe-Post) são injetados automaticamente.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/broadcasts/bc_123/send \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

GET/broadcasts200 OK

Listar campanhas

Lista as campanhas de broadcast da organização. Filtra por status e período, com paginação por cursor.

Request body

Campo	Tipo	Descrição
status	'draft' \| 'scheduled' \| 'sending' \| 'sent' \| 'failed' \| 'cancelled'	Filtra pelo status do broadcast.
from	string (ISO 8601)	Data inicial do período de busca.
to	string (ISO 8601)	Data final do período de busca.
after	string	Cursor de paginação retornado por uma chamada anterior.
limit	number (max 200)	Quantidade máxima de broadcasts retornados por página.

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/broadcasts?status=sent&limit=20" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
broadcasts	Broadcast[]	Lista de broadcasts da página atual.
nextCursor	string \| null	Cursor para buscar a próxima página, ou null se não houver mais resultados.

Exemplo de resposta

JSONjson

{  "broadcasts": [    {      "id": "bc_123",      "audienceId": "aud_123",      "audienceName": "Newsletter PT",      "templateId": "tpl_123",      "subject": "Novidades da semana",      "fromEmail": "news@seudominio.com.br",      "replyTo": null,      "status": "sent",      "scheduledAt": null,      "sentAt": "2026-09-09T13:00:00.000Z",      "cancelledAt": null,      "recipientsTotal": 4820,      "recipientsQueued": 4820,      "recipientsFailed": 12,      "createdAt": "2026-09-08T18:21:14.000Z",      "updatedAt": "2026-09-09T13:00:00.000Z"    }  ],  "nextCursor": null}

GET/broadcasts/:id200 OK

Detalhar campanha

Retorna os dados completos de uma campanha específica, incluindo status e contadores de destinatários.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/broadcasts/bc_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string	Identificador único do broadcast.
audienceId	string	Identificador da audiência destinatária.
audienceName	string \| null	Nome da audiência destinatária.
templateId	string \| null	Identificador do template usado no envio, se houver.
subject	string	Assunto do e-mail.
fromEmail	string	Endereço de e-mail do remetente.
replyTo	string \| null	Endereço de e-mail para respostas.
status	'draft' \| 'scheduled' \| 'sending' \| 'sent' \| 'failed' \| 'cancelled'	Status atual do broadcast.
scheduledAt	string (ISO 8601) \| null	Data e hora agendadas para o envio.
sentAt	string (ISO 8601) \| null	Data e hora em que o envio foi concluído.
cancelledAt	string (ISO 8601) \| null	Data e hora em que o broadcast foi cancelado.
recipientsTotal	number	Total de destinatários do broadcast.
recipientsQueued	number	Quantidade de destinatários enfileirados para envio.
recipientsFailed	number	Quantidade de destinatários com falha no envio.
createdAt	string (ISO 8601)	Data de criação do broadcast.
updatedAt	string (ISO 8601)	Data da última atualização do broadcast.

Exemplo de resposta

JSONjson

{  "id": "bc_123",  "audienceId": "aud_123",  "audienceName": "Newsletter PT",  "templateId": "tpl_123",  "subject": "Novidades da semana",  "fromEmail": "news@seudominio.com.br",  "replyTo": null,  "status": "sending",  "scheduledAt": null,  "sentAt": null,  "cancelledAt": null,  "recipientsTotal": 4820,  "recipientsQueued": 3110,  "recipientsFailed": 4,  "createdAt": "2026-09-08T18:21:14.000Z",  "updatedAt": "2026-09-10T12:05:41.000Z"}

POST/broadcasts/:id/cancel200 OK

Cancelar campanha

Cancela um broadcast agendado ou em envio. Emails já entregues não são afetados.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/broadcasts/bc_123/cancel \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string	Identificador único do broadcast.
status	'cancelled'	Status do broadcast após o cancelamento.
cancelledAt	string (ISO 8601) \| null	Data e hora em que o broadcast foi cancelado.

Exemplo de resposta

JSONjson

{  "id": "bc_123",  "status": "cancelled",  "cancelledAt": "2026-09-10T12:06:02.000Z"}

Supressões

GET/suppressions200 OK

Listar supressões

Lista bloqueios ativos (bounces, complaints, unsubscribes e manuais).

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/suppressions \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

POST/suppressions201 Created

Adicionar supressão

Adiciona manualmente um email à lista de supressão.

Request body

Campo	Tipo	Descrição
email*	string (email)	Endereço de email a ser suprimido.
reason	'manual' \| 'bounce' \| 'complaint'	Motivo da supressão. Aceita apenas 'manual', 'bounce' ou 'complaint'.
expiresAt	string (ISO 8601)	Data em que a supressão expira e o email volta a receber envios.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/suppressions \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "email": "cliente@example.com",    "reason": "manual"  }'

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador único da supressão.
email	string	Endereço de email suprimido.
reason	'manual' \| 'bounce' \| 'isp_block' \| 'mailbox_not_found' \| 'complaint' \| 'unsubscribe'	Motivo que originou a supressão.
source	'manual' \| 'auto'	Origem da supressão: manual ou automática.
category	string	Categoria de classificação da supressão.
status	'active' \| 'expired' \| 'inactive'	Situação atual da supressão.
expiresAt	string (ISO 8601) \| null	Data em que a supressão expira e o email volta a receber envios.
createdAt	string (ISO 8601)	Data de criação da supressão.

Exemplo de resposta

JSONjson

{  "id": "6f1a2b3c-4d5e-4f60-8a9b-0c1d2e3f4a5b",  "email": "cliente@example.com",  "reason": "manual",  "source": "manual",  "category": "manual",  "status": "active",  "expiresAt": null,  "createdAt": "2026-09-10T18:21:14.000Z"}

GET/suppressions/:id200 OK

Detalhar supressão

Retorna os detalhes de uma supressão específica pelo id.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/suppressions/6f1a2b3c-4d5e-4f60-8a9b-0c1d2e3f4a5b \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador único da supressão.
email	string	Endereço de email suprimido.
reason	'manual' \| 'bounce' \| 'isp_block' \| 'mailbox_not_found' \| 'complaint' \| 'unsubscribe'	Motivo que originou a supressão.
source	'manual' \| 'auto'	Origem da supressão: manual ou automática.
category	string	Categoria de classificação da supressão.
status	'active' \| 'expired' \| 'inactive'	Situação atual da supressão.
expiresAt	string (ISO 8601) \| null	Data em que a supressão expira e o email volta a receber envios.
createdAt	string (ISO 8601)	Data de criação da supressão.

Exemplo de resposta

JSONjson

{  "id": "6f1a2b3c-4d5e-4f60-8a9b-0c1d2e3f4a5b",  "email": "cliente@example.com",  "reason": "bounce",  "source": "auto",  "category": "bounce",  "status": "active",  "expiresAt": null,  "createdAt": "2026-09-10T18:21:14.000Z"}

DELETE/suppressions/:id204 No Content

Remover supressão

Remove definitivamente uma supressão da lista.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/suppressions/6f1a2b3c-4d5e-4f60-8a9b-0c1d2e3f4a5b \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

POST/suppressions/:id/reactivate204 No Content

Reativar supressão

Desfaz uma supressão, permitindo que o email volte a receber envios.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/suppressions/6f1a2b3c-4d5e-4f60-8a9b-0c1d2e3f4a5b/reactivate \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Webhooks

POST/webhooks201 Created

Cadastrar webhook

Registra um endpoint HTTPS para receber eventos. Recomendamos fornecer um secret para validação HMAC SHA-256.

Request body

Campo	Tipo	Descrição
url*	string (HTTPS)	URL de destino.
events*	WebhookEventType[]	Eventos a assinar (ex: email.delivered).
secret	string	Chave secreta para HMAC.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/webhooks \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://api.seusite.com.br/webhooks/coffeemail",    "events": ["email.delivered", "email.bounced", "email.complained"],    "secret": "whsec_meu_segredo"  }'

POST/webhooks/:id/test202 Accepted

Testar webhook

Dispara um evento simulado para validar o endpoint e a configuração.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/webhooks/wh_123/test \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

GET/webhooks200 OK

Listar webhooks

Lista os webhooks cadastrados na organização, com filtro opcional por status.

Request body

Campo	Tipo	Descrição
status	'active' \| 'paused' \| 'disabled'	Filtra webhooks pelo status atual (active, paused ou disabled).

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/webhooks?status=active" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
webhooks	WebhookListItem[]	Lista de webhooks cadastrados na organização.
webhooks[].id	string (uuid)	Identificador do webhook.
webhooks[].url	string	URL de destino que recebe os eventos.
webhooks[].events	string[]	Eventos aos quais o webhook está inscrito.
webhooks[].status	'active' \| 'paused' \| 'disabled'	Status atual do webhook.
webhooks[].description	string \| null	Descrição informada pelo usuário para o webhook.
webhooks[].hasSecret	boolean	Indica se o webhook possui um segredo de assinatura configurado.
webhooks[].createdAt	string (ISO 8601)	Data e hora de criação do webhook.

Exemplo de resposta

JSONjson

{  "webhooks": [    {      "id": "3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d",      "url": "https://api.seusite.com.br/webhooks/coffeemail",      "events": ["email.delivered", "email.bounced"],      "status": "active",      "description": "Webhook de produção",      "hasSecret": true,      "createdAt": "2026-08-01T12:00:00.000Z"    }  ]}

GET/webhooks/:id200 OK

Obter webhook

Retorna os detalhes de um webhook específico, incluindo uma prévia truncada do segredo de assinatura.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/webhooks/3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador do webhook.
url	string	URL de destino que recebe os eventos.
events	string[]	Eventos aos quais o webhook está inscrito.
status	'active' \| 'paused' \| 'disabled'	Status atual do webhook.
description	string \| null	Descrição informada pelo usuário para o webhook.
createdAt	string (ISO 8601)	Data e hora de criação do webhook.
secret	null	Sempre null nesta rota o segredo completo não é reexibido depois da criação.
secretPreview	string \| null	Prévia truncada do segredo, para exibição segura.

Exemplo de resposta

JSONjson

{  "id": "3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d",  "url": "https://api.seusite.com.br/webhooks/coffeemail",  "events": ["email.delivered", "email.bounced"],  "status": "active",  "description": "Webhook de produção",  "createdAt": "2026-08-01T12:00:00.000Z",  "secret": null,  "secretPreview": "whsec_****3f2a"}

PUT/webhooks/:id200 OK

Atualizar webhook

Atualiza url, events e/ou description de um webhook existente. Pelo menos um dos campos deve ser enviado.

Request body

Campo	Tipo	Descrição
url	string (URL)	Nova URL de destino que receberá os eventos.
events	WebhookEventType[]	Novos eventos aos quais o webhook deve se inscrever.
description	string \| null	Nova descrição do webhook (envie null para remover).

Exemplo de requisição

curl

curl -X PUT https://api.coffeemail.com.br/v1/product/webhooks/3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://api.seusite.com.br/webhooks/coffeemail-v2",    "events": ["email.delivered", "email.bounced", "email.complained"]  }'

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador do webhook.
url	string	URL de destino que recebe os eventos.
events	string[]	Eventos aos quais o webhook está inscrito.
status	'active' \| 'paused' \| 'disabled'	Status atual do webhook.
description	string \| null	Descrição informada pelo usuário para o webhook.
createdAt	string (ISO 8601)	Data e hora de criação do webhook.
secret	null	Sempre null nesta rota o segredo completo não é reexibido depois da criação.
secretPreview	string \| null	Prévia truncada do segredo, para exibição segura.

Exemplo de resposta

JSONjson

{  "id": "3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d",  "url": "https://api.seusite.com.br/webhooks/coffeemail-v2",  "events": ["email.delivered", "email.bounced", "email.complained"],  "status": "active",  "description": "Webhook de produção",  "createdAt": "2026-08-01T12:00:00.000Z",  "secret": null,  "secretPreview": "whsec_****3f2a"}

PATCH/webhooks/:id200 OK

Ativar ou pausar webhook

Altera apenas o status do webhook (active ou paused), sem afetar url, events ou description.

Request body

Campo	Tipo	Descrição
status*	'active' \| 'paused'	Novo status do webhook (active ou paused).

Exemplo de requisição

curl

curl -X PATCH https://api.coffeemail.com.br/v1/product/webhooks/3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "status": "paused" }'

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador do webhook.
status	'active' \| 'paused'	Novo status aplicado ao webhook.

Exemplo de resposta

JSONjson

{  "id": "3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d",  "status": "paused"}

DELETE/webhooks/:id204 No Content

Remover webhook

Remove definitivamente o webhook da organização. Não retorna corpo na resposta.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/webhooks/3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

GET/webhooks/:id/deliveries200 OK

Listar entregas do webhook

Lista as tentativas de entrega de eventos para um webhook, com filtros por tipo de evento, status e período.

Request body

Campo	Tipo	Descrição
eventType	string	Filtra entregas por tipo de evento.
status	'pending' \| 'success' \| 'failed' \| 'exhausted'	Filtra entregas pelo status atual.
from	string (ISO 8601)	Data inicial do período de busca.
to	string (ISO 8601)	Data final do período de busca.
limit	number (max 200)	Quantidade máxima de entregas retornadas (até 200).

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/webhooks/3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d/deliveries?status=failed&limit=50" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
deliveries	WebhookDelivery[]	Lista de tentativas de entrega do webhook.
deliveries[].id	string (uuid)	Identificador da tentativa de entrega.
deliveries[].webhookId	string (uuid)	Identificador do webhook associado.
deliveries[].emailEventId	string (uuid) \| null	Evento de e-mail que originou a entrega.
deliveries[].eventType	string	Tipo de evento disparado (ex: email.delivered).
deliveries[].responseStatus	number \| null	Status HTTP retornado pelo endpoint de destino.
deliveries[].responseBody	string \| null	Corpo da resposta retornada pelo endpoint de destino.
deliveries[].attempts	number	Quantidade de tentativas de envio já realizadas.
deliveries[].lastError	string \| null	Mensagem do último erro ocorrido no envio.
deliveries[].status	'pending' \| 'success' \| 'failed' \| 'exhausted'	Status atual da entrega.
deliveries[].nextRunAt	string (ISO 8601)	Data e hora da próxima tentativa de reenvio.
deliveries[].createdAt	string (ISO 8601)	Data e hora em que a entrega foi criada.

Exemplo de resposta

JSONjson

{  "deliveries": [    {      "id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",      "webhookId": "3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d",      "emailEventId": "1f2e3d4c-5b6a-7c8d-9e0f-1a2b3c4d5e6f",      "eventType": "email.bounced",      "responseStatus": 500,      "responseBody": "Internal Server Error",      "attempts": 3,      "lastError": "connect ETIMEDOUT",      "status": "failed",      "nextRunAt": "2026-09-10T19:00:00.000Z",      "createdAt": "2026-09-10T18:00:00.000Z"    }  ]}

POST/webhooks/:id/rotate-secret200 OK

Rotacionar segredo

Gera um novo segredo de assinatura HMAC para o webhook, invalidando o anterior. O valor completo é retornado apenas nesta resposta.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/webhooks/3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d/rotate-secret \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
webhookId	string (uuid)	Identificador do webhook.
secret	string	Novo segredo completo, usado para assinar os payloads enviados exibido uma única vez.

Exemplo de resposta

JSONjson

{  "webhookId": "3d2f6a10-8b5e-4a2b-9c1d-7e6f5a4b3c2d",  "secret": "9f8e7d6c5b4a3928f1e0d9c8b7a6958473625140f3e2d1c0b9a8f7e6d5c4b3a"}

Estatísticas

GET/stats200 OK

Métricas gerais

Retorna contadores agregados (sent, delivered, failed, bounced, complained, opened?, clicked?).

Exemplo de requisição

curl

curl "https://api.coffeemail.com.br/v1/product/stats?startDate=2026-09-01T00:00:00.000Z&endDate=2026-09-30T23:59:59.000Z&granularity=day" \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Remetentes avulsos

POST/senders201 Created

Cadastrar remetente avulso

Registra uma identidade de remetente de e-mail avulso e dispara um email de verificação. A resposta traz um verificationToken, mas o remetente só pode ser usado para envio depois que POST /senders/verify confirmar a verificação.

Request body

Campo	Tipo	Descrição
email*	string (email)	Endereço de e-mail do remetente a ser verificado.
displayName	string (max 200)	Nome de exibição do remetente.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/senders \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "email": "vendas@seudominio.com.br",    "displayName": "Equipe de Vendas"  }'

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador único do remetente.
email	string	Endereço de e-mail do remetente.
displayName	string \| null	Nome de exibição do remetente.
verificationToken	string	Token enviado ao email para confirmar a verificação.
verifiedAt	string (ISO 8601) \| null	Data/hora em que o remetente foi verificado.
active	boolean	Se o remetente está ativo para envio.
createdAt	string (ISO 8601)	Data/hora de criação do remetente.

Exemplo de resposta

JSONjson

{  "id": "b3f2a1c4-1234-4a5b-9c8d-1234567890ab",  "email": "vendas@seudominio.com.br",  "displayName": "Equipe de Vendas",  "verificationToken": "8e2f6a90-4b3c-4d5e-9f10-abcdef123456",  "verifiedAt": null,  "active": true,  "createdAt": "2026-09-10T18:21:14.000Z"}

GET/senders200 OK

Listar remetentes avulsos

Lista as identidades de remetente avulso cadastradas na organização.

Exemplo de requisição

curl

curl https://api.coffeemail.com.br/v1/product/senders \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"

Response

Campo	Tipo	Descrição
senders	Sender[]	Lista de remetentes da organização.

Exemplo de resposta

JSONjson

{  "senders": [    {      "id": "b3f2a1c4-1234-4a5b-9c8d-1234567890ab",      "email": "vendas@seudominio.com.br",      "displayName": "Equipe de Vendas",      "verifiedAt": "2026-09-10T18:25:02.000Z",      "active": true,      "createdAt": "2026-09-10T18:21:14.000Z"    }  ]}

POST/senders/verify200 OK

Verificar remetente avulso

Confirma a verificação de um remetente avulso a partir do token enviado por e-mail. Depois de verificado, o endereço pode ser usado no campo "from" dos envios.

Request body

Campo	Tipo	Descrição
token*	string (uuid)	Token de verificação recebido por e-mail.

Exemplo de requisição

curl

curl -X POST https://api.coffeemail.com.br/v1/product/senders/verify \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "token": "8e2f6a90-4b3c-4d5e-9f10-abcdef123456" }'

Response

Campo	Tipo	Descrição
id	string (uuid)	Identificador único do remetente.
email	string	Endereço de e-mail do remetente.

Exemplo de resposta

JSONjson

{  "id": "b3f2a1c4-1234-4a5b-9c8d-1234567890ab",  "email": "vendas@seudominio.com.br"}

DELETE/senders/:id204 No Content

Excluir remetente avulso

Remove uma identidade de remetente avulso da organização. A exclusão é definitiva e o e-mail precisa ser verificado novamente caso seja recadastrado.

Exemplo de requisição

curl

curl -X DELETE https://api.coffeemail.com.br/v1/product/senders/send_123 \  -H "Authorization: Bearer $COFFEEMAIL_API_KEY"