Skip to main content
API reference · Emails

Send email

Queues an email. The response comes back in milliseconds with the id; follow it in the dashboard, with Get email or through webhooks.

POSThttps://api.coffeemail.com.br/v1/product/emails
Scope: sending_access202 AcceptedSDK: emails.send()
import { CoffeeMail } from '@coffeemail/node'; const coffeemail = new CoffeeMail(process.env.COFFEEMAIL_API_KEY); const { data, error } = await coffeemail.emails.send({  from: 'Acme <pedidos@acme.com.br>',  to: 'ana@exemplo.com.br',  subject: 'Seu pedido #4821 foi enviado',  html: '<p>Chega amanhã.</p>',  idempotencyKey: 'pedido-4821-enviado',});

Headers

x-idempotency-key
Optional. The same key within 24 h returns the same email instead of sending again.
x-coffeemail-sandbox
Optional. With true, the email goes through validation and becomes events, but is not delivered to the recipient.

Request body

Request body

fromobjectrequired
Remetente do e-mail
from.emailstring (email)required
Endereço de e-mail
from.namestring≤ 200
Nome de exibição do contato
toarray<object>1+ itensaté 50 itensrequired
Lista de destinatários do e-mail
ccarray<object>até 50 itens
Lista de destinatários em cópia
bccarray<object>até 50 itens
Lista de destinatários em cópia oculta
replyToobject
Endereço para onde respostas devem ser enviadas
replyTo.emailstring (email)required
Endereço de e-mail
replyTo.namestring≤ 200
Nome de exibição do contato
subjectstring≥ 1≤ 998
Assunto do e-mail
htmlstring≤ 102400
Corpo do e-mail em HTML
textstring≤ 102400
Corpo do e-mail em texto puro
headersobject
Cabeçalhos SMTP customizados a incluir no envio
attachmentsarray<object>até 10 itens
Arquivos anexados ao e-mail
templateIdstring≥ 1≤ 100
Id ou alias do template usado para montar o e-mail
variablesobject
Variáveis para preencher o template
emailType"transactional" | "broadcast"
Categoria do envio para fins de rastreio e supressão
suppressionCategorystring≥ 1≤ 100
Categoria usada para checar a lista de supressão
tagsarray<object>até 10 itens
Tags para categorizar e filtrar o e-mail depois
scheduledAtstring (date-time)
Data/hora futura para o envio agendado do e-mail
metadataobject
Metadados customizados para rastreio ou webhook

Response

202 Accepted with the email id, the initial status (queued or scheduled) and when it entered the queue.

202 Accepted
{  "id": "8f3a2c1b-4d5e-4f60-9a7b-1c2d3e4f5a6b",  "status": "queued",  "queuedAt": "2026-11-10T17:02:11.204Z"}

Response 202

idstring (uuid)required
ID único do e-mail criado
status"queued" | "scheduled"required
Status inicial do e-mail após o envio
queuedAtstring (date-time)required
Data/hora em que o e-mail entrou na fila

Errors

HTTPcodeWhen it happens
400VALIDATION_FAILEDA body or query field is invalid; meta says which.
400INVALID_RECIPIENTThe recipient is not a valid address.
401UNAUTHORIZEDMissing, invalid or revoked key.
409DOMAIN_NOT_VERIFIEDThe sender domain has not passed DNS verification yet.
422INVALID_FROM_DOMAINThe from address uses a domain that does not belong to the organization.
422SENDER_NOT_VERIFIEDThe single sender has not confirmed the email yet.
429PLAN_QUOTA_EXCEEDEDThe plan quota ran out in the cycle; enable overage or change plans.
429RATE_LIMIT_EXCEEDEDToo many requests; wait the retry-after time.
500TEMPLATE_RENDER_ERRORThe template did not render with the variables sent.