Documentation

Referencia de la API

API v1

CoffeeMail expone una API REST pública para integración vía API Key. Esta referencia cubre solo las rutas de Producto (/v1/product/*) consumidas por el SDK de Node y por clientes externos. Las rutas internas (Plataforma e Infraestructura) no forman parte de este contrato público.

Alcance de esta referencia

Esta página documenta solo las rutas públicas de Producto (/v1/product/*) consumidas por clientes externos vía API Key. Las rutas internas de Plataforma (/v1/platform/*, usadas por el dashboard vía cookie HttpOnly) y de Infraestructura (/v1/internal/*) son reservadas y no forman parte de este contrato público.

URL base

bashbash

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

Autenticación

Todas las solicitudes requieren un Bearer Token en el header Authorization. Puedes crear y revocar API Keys en Dashboard → Claves 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"

Las claves de Producto (prefijo cm_live_) y las claves de prueba (prefijo cm_test_) están aisladas usa claves cm_test_ en desarrollo para no consumir tu cuota.

Idioma

La API detecta el idioma por el header Accept-Language. Valores soportados: pt-BR (por defecto), en, es. Los mensajes de validación y los códigos de error están localizados.

Formato de error

Todas las respuestas de error siguen el mismo sobre JSON:

JSONjson

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

Rate limit

Los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset se devuelven en cada solicitud. Los límites se aplican por clave de API y por IP. Consulta la tabla completa en Códigos de error.

Endpoints de la API

Emails

POST/emails202 Accepted

Enviar emails

Pone en cola un email transaccional. Acepta HTML puro, texto plano, o un templateId + variables. Soporta adjuntos (cadena base64 o Uint8Array), encabezados personalizados, programación (scheduledAt) e idempotencia (idempotencyKey).

Request body

Campo	Tipo	Descripción
from*	string \| { email, name? }	Remitente (debe ser un dominio verificado).
to*	string \| string[] \| { email, name? }[]	Un destinatario o lista.
subject*	string	Asunto.
html	string	Contenido HTML.
text	string	Fallback en texto plano.
templateId	string	Renderiza una plantilla existente.
variables	Record<string, unknown>	Variables para la plantilla.
cc / bcc / replyTo	EmailAddressInput	Cc, Cco y reply-to.
attachments	EmailAttachment[]	Adjuntos. content acepta cadena base64 o Uint8Array.
scheduledAt	ISO 8601 \| Date	Envio programado.
idempotencyKey	string	Evita duplicacion en reintentos.
tags	EmailTag[]	Tags para metricas.
isSandbox	boolean	No envia de hecho (simulacion).

Reglas y límites de archivos adjuntos

Soporta hasta 10 archivos por correo electrónico con un límite acumulado de 25 MB. El contenido debe estar codificado en Base64 en la API REST (el SDK de Node acepta Buffer directamente). El campo cid es obligatorio para adjuntos con disposition 'inline'.

Estructura del objeto EmailAttachment

Campo	Tipo	Descripción
filename*	string (1-255)	Nombre del archivo con extensión (ej: factura.pdf). Límite de 255 caracteres.
content*	string (Base64)	Contenido binario del archivo codificado en Base64.
contentType*	string (MIME)	MIME type (ej: application/pdf, image/png). Predeterminado en el SDK: application/octet-stream.
disposition*	'attachment' \| 'inline'	Modo de entrega: 'attachment' (descarga tradicional) o 'inline' (incrustado en el cuerpo HTML).
cid	string (opcional)	Content-ID único utilizado para referenciar imágenes inline en el cuerpo HTML (ej: cid:logo referenciado en img).

Ejemplo de petición

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	Descripción
id	string	Identificador unico del email.
status	'queued' \| 'scheduled'	Estado inicial despues del envio.
queuedAt	string (ISO 8601)	Marca de tiempo de entrada en cola.

Ejemplo de respuesta

JSONjson

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

GET/emails200 OK

Listar correos

Lista los correos de la organización con paginación por cursor. Admite filtros por estado, destinatario, remitente, asunto, etiqueta, API key y período.

Request body

Campo	Tipo	Descripción
status	'queued' \| 'processing' \| 'sent' \| 'delivered' \| 'bounced' \| 'complained' \| 'failed' \| 'skipped' \| 'scheduled' \| 'cancelled'	Filtra correos por estado de envío.
recipient	string	Búsqueda parcial por destinatario en to/cc/bcc.
fromEmail	string	Filtra correos por dirección del remitente.
subjectContains	string	Búsqueda parcial en el asunto del correo.
apiKeyId	string (uuid)	Filtra correos enviados por una API key específica.
tag	string	Filtra correos que tienen esta etiqueta.
from	string (ISO 8601)	Fecha/hora inicial del período de búsqueda.
to	string (ISO 8601)	Fecha/hora final del período de búsqueda.
after	string (ISO 8601)	Cursor de paginación para obtener los siguientes registros.
limit	number	Cantidad máxima de correos devueltos (por defecto 50, máximo 100).

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
emails	EmailResponse[]	Lista de correos devueltos.
nextCursor	string \| null	Cursor para obtener la siguiente página, o null si no hay más registros.

Ejemplo de respuesta

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 correos en lote

Envía hasta 100 correos en una sola llamada. Cada elemento sigue el mismo formato que el envío individual (from, to, subject/html/text o templateId, etc). Los fallos de elementos individuales no anulan todo el lote.

Request body

Campo	Tipo	Descripción
(array)*	SendEmailRequest[]	Array de 1 a 100 payloads de envío, en el mismo formato que POST /emails.

Ejemplo de petición

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	Descripción
[].ok	boolean	Indica si el elemento fue aceptado con éxito.
[].data.id	string	Identificador único del correo creado (cuando ok es true).
[].data.status	'queued' \| 'scheduled'	Estado inicial del correo después del envío (cuando ok es true).
[].data.queuedAt	string (ISO 8601)	Timestamp de entrada en la cola (cuando ok es true).
[].error	string	Mensaje de error del elemento que falló (cuando ok es false).

Ejemplo de respuesta

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 etiquetas usadas

Devuelve las etiquetas distintas ya usadas en los correos enviados por la organización, junto con los valores registrados para cada una. Útil para poblar filtros en la interfaz.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
tags	{ name, values }[]	Etiquetas distintas usadas en correos, cada una con sus valores ya registrados.

Ejemplo de respuesta

JSONjson

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

GET/emails/:id200 OK

Obtener correo por ID

Devuelve los detalles completos de un correo: estado, intentos, timestamps del ciclo de vida, etiquetas, cuerpo (html/text) y la API key usada en el envío.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string (uuid)	ID único del correo.
from	string	Dirección del remitente.
to	string[]	Lista de destinatarios.
cc / bcc	string[] \| null	Lista de destinatarios en copia y en copia oculta.
subject	string \| null	Asunto del correo.
status	'queued' \| 'processing' \| 'sent' \| 'delivered' \| 'bounced' \| 'failed' \| 'skipped' \| 'scheduled' \| 'cancelled'	Estado actual del envío.
attempts	number	Número de intentos de envío realizados.
lastError	string \| null	Último mensaje de error registrado en el envío.
messageId	string \| null	ID del mensaje devuelto por el proveedor de envío.
createdAt / scheduledAt / sentAt	string (ISO 8601) \| null	Fecha/hora de creación, programación y envío del correo.
deliveredAt / bouncedAt / failedAt / complainedAt / suppressedAt	string (ISO 8601) \| null	Fecha/hora de entrega, bounce, fallo o queja de spam, si ocurrió.
openedAt / firstClickedAt	string (ISO 8601) \| null	Fecha/hora de la primera apertura y del primer clic en un enlace.
openCount / clickCount	number	Cantidad de aperturas y clics registrados.
tags	{ name, value }[] \| null	Etiquetas asociadas al correo.
html / text	string \| null	Cuerpo del correo en HTML y en texto plano.
apiKey	{ id, name } \| null	API key usada para enviar el correo.

Ejemplo de respuesta

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

Línea de tiempo de eventos

Devuelve el historial de eventos de un correo (en cola, procesando, enviado, entregado, abierto, clic, bounce, queja, fallo), en orden cronológico.

Ejemplo de petición

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	Descripción
id	string (uuid)	ID único del correo.
events	{ type, timestamp, metadata? }[]	Línea de tiempo de eventos del correo, cada uno con tipo, timestamp y metadata opcional.

Ejemplo de respuesta

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 correo programado

Cancela un correo que aún está en estado scheduled. No tiene efecto sobre correos que ya entraron en procesamiento o fueron enviados. No devuelve cuerpo en la respuesta.

Ejemplo de petición

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 correo

Vuelve a encolar un correo que falló o fue cancelado, creando un nuevo ciclo de envío.

Ejemplo de petición

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	Descripción
id	string	Identificador único del nuevo envío.
status	'queued' \| 'scheduled'	Estado inicial del correo después del reenvío.
queuedAt	string (ISO 8601)	Timestamp de entrada en la cola.

Ejemplo de respuesta

JSONjson

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

Dominios

POST/domains201 Created

Agregar dominio

Registra un dominio en la organizacion y devuelve los registros DNS (SPF, DKIM, DMARC y ownership) que deben configurarse en el proveedor.

Request body

Campo	Tipo	Descripción
name*	string	FQDN a registrar (ej: empresa.com).

Ejemplo de petición

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	Descripción
id	string	ID del dominio.
name	string	Nombre del dominio.
status	'verified' \| 'pending' \| 'failed'	Estado de validacion.
records	DomainDnsRecord[]	SPF/DKIM/DMARC/ownership.

POST/domains/:id/verify202 Accepted

Verificar dominio

Ejecuta la verificacion bajo demanda de los registros DNS. Devuelve checks detallados (spf, dkim, dmarc, ownership).

Ejemplo de petición

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

Salud del dominio

Diagnostico de reputacion, presencia en listas negras y recomendaciones de mejora.

Ejemplo de petición

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 dominios

Lista todos los dominios registrados en la organización, con estado de verificación y datos de DKIM.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
domains	DomainListItem[]	Lista de dominios registrados en la organización.
domains[].id	string (uuid)	ID único del dominio.
domains[].name	string	Nombre del dominio registrado.
domains[].status	'pending' \| 'verified' \| 'failed'	Estado actual de la verificación del dominio.
domains[].dkimSelector	string	Selector usado en el registro DKIM del dominio.
domains[].dkimPublicKey	string \| null	Clave pública DKIM generada para el dominio.
domains[].verifiedAt	string (ISO 8601) \| null	Fecha y hora en que el dominio fue verificado.
domains[].lastCheckAt	string (ISO 8601) \| null	Fecha y hora de la última verificación de DNS realizada.
domains[].createdAt	string (ISO 8601)	Fecha y hora en que el dominio fue registrado.

Ejemplo de respuesta

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

Obtener dominio

Devuelve el detalle de un dominio, incluyendo los registros DNS (TXT/CNAME) pendientes de publicación.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string (uuid)	ID único del dominio.
name	string	Nombre del dominio registrado.
status	'pending' \| 'verified' \| 'failed'	Estado actual de la verificación del dominio.
dkimSelector	string	Selector usado en el registro DKIM del dominio.
dkimPublicKey	string \| null	Clave pública DKIM generada para el dominio.
verifiedAt	string (ISO 8601) \| null	Fecha y hora en que el dominio fue verificado.
lastCheckAt	string (ISO 8601) \| null	Fecha y hora de la última verificación de DNS realizada.
createdAt	string (ISO 8601)	Fecha y hora en que el dominio fue registrado.
dnsRecordsToPublish	DnsRecord[]	Registros DNS pendientes que el cliente debe publicar.
dnsRecordsToPublish[].type	'TXT' \| 'CNAME'	Tipo de registro DNS a publicar (TXT o CNAME).
dnsRecordsToPublish[].host	string	Nombre del host/subdominio donde debe crearse el registro.
dnsRecordsToPublish[].value	string	Valor que debe publicarse en el registro DNS.
dnsRecordsToPublish[].ttl	number	TTL sugerido en segundos para el registro.

Ejemplo de respuesta

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

Eliminar dominio

Elimina (soft-delete) un dominio de la organización. Si la cuenta tiene reautenticación configurada, se deben enviar method + credential; límite de 5 solicitudes por minuto.

Request body

Campo	Tipo	Descripción
method	'totp' \| 'password'	Método de reautenticación, 'totp' o 'password'. Obligatorio solo si la cuenta tiene reauth configurado.
credential	string	Código TOTP o contraseña usada para confirmar la eliminación.

Ejemplo de petición

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	Descripción
ok	boolean	Confirma que el dominio fue eliminado.

Ejemplo de respuesta

JSONjson

{  "ok": true}

GET/domains/:id/warmup200 OK

Estado de warmup

Consulta el progreso del calentamiento (warmup) de IP/dominio. Devuelve null cuando el dominio aún no ha iniciado el warmup.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
domainId	string (uuid)	ID único del dominio.
currentDay	number	Día actual del período de calentamiento (warmup).
dailyQuota	number	Límite diario de envíos permitido para el día actual.
sentToday	number	Cantidad de emails ya enviados hoy.
remainingToday	number	Cantidad de envíos restantes en la cuota diaria.
quotaUsedPercent	number (0-100)	Porcentaje de la cuota diaria ya utilizado.
lastSendDate	string \| null	Fecha del último envío registrado para el dominio.

Ejemplo de respuesta

JSONjson

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

Plantillas

POST/templates201 Created

Crear plantilla

Registra una plantilla. Soporta HTML con Handlebars (format: handlebars) o TSX con React Email (format: react_email).

Request body

Campo	Tipo	Descripción
name*	string	Nombre de la plantilla.
subject	string	Asunto por defecto.
html	string	Contenido (Handlebars).
text	string	Version en texto plano.
format	'handlebars' \| 'react_email'	Motor de plantilla.
variables	{ name, defaultValue? }[]	Variables esperadas.

Ejemplo de petición

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 un preview sin enviar util para el playground y validacion de variables.

Ejemplo de petición

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 plantillas

Devuelve todas las plantillas registradas en la organización, con el código fuente completo de cada una.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
data	TemplateDetail[]	Lista de plantillas de correo registradas.
data[].id	string (uuid)	Identificador único de la plantilla.
data[].name	string	Nombre de la plantilla.
data[].subject	string \| null	Asunto por defecto del correo.
data[].html	string	Código fuente HTML o JSX de la plantilla.
data[].textPayload	string \| null	Versión en texto plano de la plantilla.
data[].variables	{ name, description? }[]	Variables disponibles para interpolación en la plantilla.
data[].isActive	boolean	Indica si la plantilla está activa para su uso.
data[].format	'html' \| 'react'	Formato del código fuente de la plantilla.
data[].sourceLocale	string	Idioma de origen del contenido de la plantilla.
data[].starterSlug	string \| null	Slug de la plantilla inicial usada como base, si existe.
data[].createdAt	string (ISO 8601)	Fecha de creación de la plantilla.
data[].updatedAt	string (ISO 8601)	Fecha de la última actualización de la plantilla.

Ejemplo de respuesta

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

Obtener plantilla

Devuelve una plantilla específica por id, con el código fuente completo y las variables disponibles.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string (uuid)	Identificador único de la plantilla.
name	string	Nombre de la plantilla.
subject	string \| null	Asunto por defecto del correo.
html	string	Código fuente HTML o JSX de la plantilla.
textPayload	string \| null	Versión en texto plano de la plantilla.
variables	{ name, description? }[]	Variables disponibles para interpolación en la plantilla.
isActive	boolean	Indica si la plantilla está activa para su uso.
format	'html' \| 'react'	Formato del código fuente de la plantilla.
sourceLocale	string	Idioma de origen del contenido de la plantilla.
starterSlug	string \| null	Slug de la plantilla inicial usada como base, si existe.
createdAt	string (ISO 8601)	Fecha de creación de la plantilla.
updatedAt	string (ISO 8601)	Fecha de la última actualización de la plantilla.

Ejemplo de respuesta

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

Actualizar plantilla

Actualiza parcialmente una plantilla existente. Envía solo los campos que quieras cambiar.

Request body

Campo	Tipo	Descripción
name	string	Nuevo nombre de la plantilla.
subject	string \| null	Nuevo asunto por defecto del correo.
html	string	Nuevo código fuente HTML o JSX.
textPayload	string \| null	Nueva versión en texto plano.
variables	{ name, description? }[]	Nueva lista de variables disponibles para interpolación.
format	'html' \| 'react'	Nuevo formato del código fuente.
isActive	boolean	Activa o desactiva la plantilla.
sourceLocale	string	Nuevo idioma de origen del contenido.
starterSlug	string \| null	Slug de la plantilla inicial usada como base.

Ejemplo de petición

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	Descripción
id	string (uuid)	Identificador único de la plantilla.
name	string	Nombre de la plantilla.
isActive	boolean	Indica si la plantilla está activa para su uso.
updatedAt	string (ISO 8601)	Fecha de la última actualización de la plantilla.

Ejemplo de respuesta

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

Eliminar plantilla

Elimina una plantilla de forma definitiva. Esta acción no se puede deshacer.

Ejemplo de petición

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

Formatear plantilla

Formatea el código fuente de una plantilla (HTML o JSX) mediante Prettier, sin persistir nada.

Request body

Campo	Tipo	Descripción
html*	string	Código fuente HTML o JSX a formatear.
format	'html' \| 'react'	Formato del código de origen.

Ejemplo de petición

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	Descripción
html	string	Código fuente formateado.

Ejemplo de respuesta

JSONjson

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

POST/templates/test-render200 OK

Render de prueba sanitizado

Renderiza una plantilla con variables y sanitiza el HTML resultante (elimina scripts, iframes, enlaces javascript: y manejadores de eventos inline). A diferencia de /templates/preview, que no sanitiza usa este endpoint para probar contenido no confiable.

Request body

Campo	Tipo	Descripción
html*	string	Código fuente HTML o JSX de la plantilla a renderizar.
format	'html' \| 'react'	Formato de la plantilla de origen.
variables	Record<string, unknown>	Valores de las variables usadas para completar la plantilla.

Ejemplo de petición

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	Descripción
html	string	HTML final renderizado y sanitizado.
text	string	Versión en texto plano del correo renderizado.
sanitizeReport	{ scripts, iframes, javascriptHrefs, eventHandlers }	Informe con la cantidad de elementos eliminados por la sanitización (scripts, iframes, enlaces javascript: y manejadores de eventos).

Ejemplo de respuesta

JSONjson

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

Audiencias y contactos

POST/audiences201 Created

Crear audiencia

Crea una lista segmentada de contactos.

Ejemplo de petición

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

Agregar contacto

Inserta un contacto en una audiencia. Acepta firstName, lastName y metadata arbitraria.

Ejemplo de petición

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 audiencias

Lista las audiencias de la organización, con paginación.

Request body

Campo	Tipo	Descripción
limit	number	Cantidad máxima de elementos por página (por defecto 50, máximo 200).
offset	number	Cantidad de elementos a omitir desde el inicio (por defecto 0).

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
audiences	Audience[]	Lista de audiencias encontradas.
total	number	Total de audiencias de la organización.

Ejemplo de respuesta

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

Obtener audiencia

Devuelve los datos de una audiencia específica.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string	Identificador único de la audiencia.
name	string	Nombre de la audiencia.
description	string \| null	Descripción de la audiencia.
active	boolean	Si la audiencia está activa.
contactsCount	number	Cantidad de contactos en la audiencia.
createdAt	string (ISO 8601)	Fecha de creación de la audiencia.
updatedAt	string (ISO 8601)	Fecha de la última actualización de la audiencia.

Ejemplo de respuesta

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

Actualizar audiencia

Actualiza el nombre, la descripción y/o el estado de una audiencia. Se debe enviar al menos un campo.

Request body

Campo	Tipo	Descripción
name	string	Nuevo nombre de la audiencia.
description	string \| null	Nueva descripción de la audiencia. Envía null para borrarla.
active	boolean	Si la audiencia está activa.

Ejemplo de petición

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	Descripción
id	string	Identificador único de la audiencia actualizada.

Ejemplo de respuesta

JSONjson

{  "id": "aud_123"}

DELETE/audiences/:id204 No Content

Eliminar audiencia

Elimina permanentemente una audiencia y sus contactos. No devuelve cuerpo en la respuesta.

Ejemplo de petición

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 contactos de la audiencia

Lista los contactos de una audiencia, con paginación.

Request body

Campo	Tipo	Descripción
limit	number	Cantidad máxima de elementos por página (por defecto 100, máximo 500).
offset	number	Cantidad de elementos a omitir desde el inicio (por defecto 0).

Ejemplo de petición

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	Descripción
contacts	Contact[]	Lista de contactos encontrados.
total	number	Total de contactos en la audiencia.

Ejemplo de respuesta

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

Agregar contactos en lote

Agrega hasta 10.000 contactos de una vez a una audiencia.

Request body

Campo	Tipo	Descripción
contacts*	{ email, firstName?, lastName?, metadata? }[]	Lista de contactos a agregar (email obligatorio; firstName, lastName y metadata opcionales).

Ejemplo de petición

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	Descripción
inserted	number	Cantidad de contactos insertados con éxito.
skipped	number	Cantidad de contactos omitidos (por ejemplo, emails duplicados dentro de la audiencia).
errors	{ email, reason }[]	Lista de errores por email, con el motivo de cada falla.

Ejemplo de respuesta

JSONjson

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

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

Actualizar contacto

Actualiza firstName, lastName y/o metadata de un contacto. Se debe enviar al menos un campo.

Request body

Campo	Tipo	Descripción
firstName	string \| null	Nuevo primer nombre del contacto. Envía null para borrarlo.
lastName	string \| null	Nuevo apellido del contacto. Envía null para borrarlo.
metadata	Record<string, unknown>	Datos adicionales del contacto en formato libre.

Ejemplo de petición

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	Descripción
id	string	Identificador único del contacto actualizado.

Ejemplo de respuesta

JSONjson

{  "id": "cnt_123"}

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

Eliminar contacto

Elimina un contacto de una audiencia. No devuelve cuerpo en la respuesta.

Ejemplo de petición

curl

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

Campañas (broadcasts)

POST/broadcasts201 Created

Crear campana

Crea una campana para una audiencia. Puede usar una plantilla existente (templateId) o HTML propio. Acepta programacion via scheduledAt.

Ejemplo de petición

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 campana

Pone la campana en estado de envio. Los encabezados RFC 8058 (List-Unsubscribe y List-Unsubscribe-Post) se inyectan automaticamente.

Ejemplo de petición

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 campañas

Lista las campañas de broadcast de la organización. Filtra por estado y período, con paginación por cursor.

Request body

Campo	Tipo	Descripción
status	'draft' \| 'scheduled' \| 'sending' \| 'sent' \| 'failed' \| 'cancelled'	Filtra por el estado del broadcast.
from	string (ISO 8601)	Fecha inicial del período de búsqueda.
to	string (ISO 8601)	Fecha final del período de búsqueda.
after	string	Cursor de paginación devuelto por una llamada anterior.
limit	number (max 200)	Cantidad máxima de broadcasts devueltos por página.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
broadcasts	Broadcast[]	Lista de broadcasts de la página actual.
nextCursor	string \| null	Cursor para obtener la próxima página, o null si no hay más resultados.

Ejemplo de respuesta

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

Obtener campaña

Devuelve los datos completos de una campaña específica, incluyendo estado y contadores de destinatarios.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string	Identificador único del broadcast.
audienceId	string	Identificador de la audiencia destinataria.
audienceName	string \| null	Nombre de la audiencia destinataria.
templateId	string \| null	Identificador del template usado en el envío, si existe.
subject	string	Asunto del correo.
fromEmail	string	Dirección de correo del remitente.
replyTo	string \| null	Dirección de correo para respuestas.
status	'draft' \| 'scheduled' \| 'sending' \| 'sent' \| 'failed' \| 'cancelled'	Estado actual del broadcast.
scheduledAt	string (ISO 8601) \| null	Fecha y hora programadas para el envío.
sentAt	string (ISO 8601) \| null	Fecha y hora en que se completó el envío.
cancelledAt	string (ISO 8601) \| null	Fecha y hora en que se canceló el broadcast.
recipientsTotal	number	Total de destinatarios del broadcast.
recipientsQueued	number	Cantidad de destinatarios encolados para el envío.
recipientsFailed	number	Cantidad de destinatarios con fallo en el envío.
createdAt	string (ISO 8601)	Fecha de creación del broadcast.
updatedAt	string (ISO 8601)	Fecha de la última actualización del broadcast.

Ejemplo de respuesta

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 campaña

Cancela un broadcast programado o en curso de envío. Los correos ya entregados no se ven afectados.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string	Identificador único del broadcast.
status	'cancelled'	Estado del broadcast después de la cancelación.
cancelledAt	string (ISO 8601) \| null	Fecha y hora en que se canceló el broadcast.

Ejemplo de respuesta

JSONjson

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

Supresiones

GET/suppressions200 OK

Listar supresiones

Lista bloqueos activos (bounces, complaints, unsubscribes y manuales).

Ejemplo de petición

curl

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

POST/suppressions201 Created

Agregar supresión

Agrega manualmente un email a la lista de supresión.

Request body

Campo	Tipo	Descripción
email*	string (email)	Dirección de email a suprimir.
reason	'manual' \| 'bounce' \| 'complaint'	Motivo de la supresión. Solo acepta 'manual', 'bounce' o 'complaint'.
expiresAt	string (ISO 8601)	Fecha en la que la supresión expira y el email vuelve a recibir envíos.

Ejemplo de petición

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	Descripción
id	string (uuid)	Identificador único de la supresión.
email	string	Dirección de email suprimida.
reason	'manual' \| 'bounce' \| 'isp_block' \| 'mailbox_not_found' \| 'complaint' \| 'unsubscribe'	Motivo que originó la supresión.
source	'manual' \| 'auto'	Origen de la supresión: manual o automática.
category	string	Categoría de clasificación de la supresión.
status	'active' \| 'expired' \| 'inactive'	Estado actual de la supresión.
expiresAt	string (ISO 8601) \| null	Fecha en la que la supresión expira y el email vuelve a recibir envíos.
createdAt	string (ISO 8601)	Fecha de creación de la supresión.

Ejemplo de respuesta

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

Obtener supresión

Devuelve los detalles de una supresión específica por id.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string (uuid)	Identificador único de la supresión.
email	string	Dirección de email suprimida.
reason	'manual' \| 'bounce' \| 'isp_block' \| 'mailbox_not_found' \| 'complaint' \| 'unsubscribe'	Motivo que originó la supresión.
source	'manual' \| 'auto'	Origen de la supresión: manual o automática.
category	string	Categoría de clasificación de la supresión.
status	'active' \| 'expired' \| 'inactive'	Estado actual de la supresión.
expiresAt	string (ISO 8601) \| null	Fecha en la que la supresión expira y el email vuelve a recibir envíos.
createdAt	string (ISO 8601)	Fecha de creación de la supresión.

Ejemplo de respuesta

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

Eliminar supresión

Elimina definitivamente una supresión de la lista.

Ejemplo de petición

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

Reactivar supresión

Deshace una supresión, permitiendo que el email vuelva a recibir envíos.

Ejemplo de petición

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

Registrar webhook

Registra un endpoint HTTPS para recibir eventos. Recomendamos proporcionar un secret para validacion HMAC SHA-256.

Request body

Campo	Tipo	Descripción
url*	string (HTTPS)	URL de destino.
events*	WebhookEventType[]	Eventos a suscribirse (ej: email.delivered).
secret	string	Clave secreta para HMAC.

Ejemplo de petición

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

Probar webhook

Dispara un evento simulado para validar el endpoint y la configuracion.

Ejemplo de petición

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 los webhooks registrados en la organización, con filtro opcional por status.

Request body

Campo	Tipo	Descripción
status	'active' \| 'paused' \| 'disabled'	Filtra webhooks por su status actual (active, paused o disabled).

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
webhooks	WebhookListItem[]	Lista de webhooks registrados en la organización.
webhooks[].id	string (uuid)	Identificador del webhook.
webhooks[].url	string	URL de destino que recibe los eventos.
webhooks[].events	string[]	Eventos a los que el webhook está suscrito.
webhooks[].status	'active' \| 'paused' \| 'disabled'	Status actual del webhook.
webhooks[].description	string \| null	Descripción proporcionada por el usuario para el webhook.
webhooks[].hasSecret	boolean	Indica si el webhook tiene un secreto de firma configurado.
webhooks[].createdAt	string (ISO 8601)	Fecha y hora de creación del webhook.

Ejemplo de respuesta

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

Obtener webhook

Devuelve los detalles de un webhook específico, incluyendo una vista previa truncada del secreto de firma.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
id	string (uuid)	Identificador del webhook.
url	string	URL de destino que recibe los eventos.
events	string[]	Eventos a los que el webhook está suscrito.
status	'active' \| 'paused' \| 'disabled'	Status actual del webhook.
description	string \| null	Descripción proporcionada por el usuario para el webhook.
createdAt	string (ISO 8601)	Fecha y hora de creación del webhook.
secret	null	Siempre null en esta ruta el secreto completo no se vuelve a mostrar después de la creación.
secretPreview	string \| null	Vista previa truncada del secreto, para exhibición segura.

Ejemplo de respuesta

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

Actualizar webhook

Actualiza url, events y/o description de un webhook existente. Debe enviarse al menos uno de los campos.

Request body

Campo	Tipo	Descripción
url	string (URL)	Nueva URL de destino que recibirá los eventos.
events	WebhookEventType[]	Nuevos eventos a los que el webhook debe suscribirse.
description	string \| null	Nueva descripción del webhook (envía null para eliminarla).

Ejemplo de petición

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	Descripción
id	string (uuid)	Identificador del webhook.
url	string	URL de destino que recibe los eventos.
events	string[]	Eventos a los que el webhook está suscrito.
status	'active' \| 'paused' \| 'disabled'	Status actual del webhook.
description	string \| null	Descripción proporcionada por el usuario para el webhook.
createdAt	string (ISO 8601)	Fecha y hora de creación del webhook.
secret	null	Siempre null en esta ruta el secreto completo no se vuelve a mostrar después de la creación.
secretPreview	string \| null	Vista previa truncada del secreto, para exhibición segura.

Ejemplo de respuesta

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

Activar o pausar webhook

Cambia únicamente el status del webhook (active o paused), sin afectar url, events ni description.

Request body

Campo	Tipo	Descripción
status*	'active' \| 'paused'	Nuevo status del webhook (active o paused).

Ejemplo de petición

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	Descripción
id	string (uuid)	Identificador del webhook.
status	'active' \| 'paused'	Nuevo status aplicado al webhook.

Ejemplo de respuesta

JSONjson

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

DELETE/webhooks/:id204 No Content

Eliminar webhook

Elimina definitivamente el webhook de la organización. No devuelve cuerpo en la respuesta.

Ejemplo de petición

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 del webhook

Lista los intentos de entrega de eventos de un webhook, con filtros por tipo de evento, status y período.

Request body

Campo	Tipo	Descripción
eventType	string	Filtra entregas por tipo de evento.
status	'pending' \| 'success' \| 'failed' \| 'exhausted'	Filtra entregas por su status actual.
from	string (ISO 8601)	Fecha inicial del período de búsqueda.
to	string (ISO 8601)	Fecha final del período de búsqueda.
limit	number (max 200)	Cantidad máxima de entregas devueltas (hasta 200).

Ejemplo de petición

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	Descripción
deliveries	WebhookDelivery[]	Lista de intentos de entrega del webhook.
deliveries[].id	string (uuid)	Identificador del intento de entrega.
deliveries[].webhookId	string (uuid)	Identificador del webhook asociado.
deliveries[].emailEventId	string (uuid) \| null	Evento de correo que originó la entrega.
deliveries[].eventType	string	Tipo de evento disparado (ej: email.delivered).
deliveries[].responseStatus	number \| null	Status HTTP devuelto por el endpoint de destino.
deliveries[].responseBody	string \| null	Cuerpo de la respuesta devuelta por el endpoint de destino.
deliveries[].attempts	number	Cantidad de intentos de envío ya realizados.
deliveries[].lastError	string \| null	Mensaje del último error ocurrido en el envío.
deliveries[].status	'pending' \| 'success' \| 'failed' \| 'exhausted'	Status actual de la entrega.
deliveries[].nextRunAt	string (ISO 8601)	Fecha y hora del próximo intento de reenvío.
deliveries[].createdAt	string (ISO 8601)	Fecha y hora en que se creó la entrega.

Ejemplo de respuesta

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

Rotar secreto

Genera un nuevo secreto de firma HMAC para el webhook, invalidando el anterior. El valor completo se devuelve solo en esta respuesta.

Ejemplo de petición

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	Descripción
webhookId	string (uuid)	Identificador del webhook.
secret	string	Nuevo secreto completo, usado para firmar los payloads enviados se muestra una única vez.

Ejemplo de respuesta

JSONjson

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

Estadísticas

GET/stats200 OK

Metricas generales

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

Ejemplo de petición

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"

Remitentes

POST/senders201 Created

Crear remitente

Registra una identidad de remitente de correo individual y envía un email de verificación. La respuesta incluye un verificationToken, pero la identidad no puede usarse para enviar hasta que POST /senders/verify confirme la verificación.

Request body

Campo	Tipo	Descripción
email*	string (email)	Dirección de correo del remitente a verificar.
displayName	string (max 200)	Nombre para mostrar del remitente.

Ejemplo de petición

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	Descripción
id	string (uuid)	Identificador único del remitente.
email	string	Dirección de correo del remitente.
displayName	string \| null	Nombre para mostrar del remitente.
verificationToken	string	Token enviado al correo para confirmar la verificación.
verifiedAt	string (ISO 8601) \| null	Fecha/hora en que se verificó el remitente.
active	boolean	Si el remitente está activo para el envío.
createdAt	string (ISO 8601)	Fecha/hora de creación del remitente.

Ejemplo de respuesta

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 remitentes

Lista las identidades de remitente individual registradas en la organización.

Ejemplo de petición

curl

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

Response

Campo	Tipo	Descripción
senders	Sender[]	Lista de remitentes de la organización.

Ejemplo de respuesta

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 remitente

Confirma la verificación de un remitente individual usando el token recibido por correo. Una vez verificado, la dirección puede usarse en el campo "from" de los envíos.

Request body

Campo	Tipo	Descripción
token*	string (uuid)	Token de verificación recibido por correo.

Ejemplo de petición

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	Descripción
id	string (uuid)	Identificador único del remitente.
email	string	Dirección de correo del remitente.

Ejemplo de respuesta

JSONjson

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

DELETE/senders/:id204 No Content

Eliminar remitente

Elimina una identidad de remitente individual de la organización. La eliminación es definitiva y el correo deberá verificarse nuevamente si se vuelve a registrar.

Ejemplo de petición

curl

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