E-mail API

Envio de e-mails transacionais (redefinição de senha, avisos, confirmações) pela Sendeasy, a partir da sua aplicação, autenticado pelo token do próprio e-mail — cada e-mail configurado no projeto tem o seu.

O envio sai pelo e-mail dono do token e consome 1 crédito de e-mail do projeto. Você não informa o remetente: ele é o e-mail do token. Tem mais de um e-mail? Use o token daquele pelo qual quer enviar.

Pré-requisitos

  1. Token do e-mail — em Canais → E-mail (ou no card do e-mail em Canais) → Configurações → seção API de envio. Cada e-mail tem o próprio token; ali também dá para gerar um novo (o anterior deixa de valer na hora).
  2. O e-mail com status Verificado (mesmo lugar). Sem isso a rota responde 503 ERR_EMAIL_SENDER_NOT_CONFIGURED e nada sai, mesmo com crédito.
  3. Créditos de e-mail disponíveis no plano do projeto.

Use GET /api/v1/email/health para conferir os itens 1 e 2 sem gastar crédito.

Autenticação

Header obrigatório, com o token do e-mail remetente:

Authorization: Bearer <token_do_email>

O token identifica o e-mail remetente e, por ele, o projeto — não existe whatsappId/emailId na URL.

Endpoints

MétodoEndpointFinalidadeCrédito
POST/api/v1/email/sendEnviar e-mail transacional1 por envio
GET/api/v1/email/healthDiagnóstico: o e-mail do token está verificado?não consome
GET/api/v1/email/sends/:idStatus de um envionão consome
GET/api/v1/email/sendsEnvios recentesnão consome

Limite: 20 envios por minuto por origem (429 ERR_PUBLIC_EMAIL_RATE_LIMIT). As consultas de status têm limite próprio, de 120 por minuto.

Envio de e-mail

POST /api/v1/email/send

Payload

CampoTipoObrigatórioObservações
tostring ou string[]Simaté 10 destinatários por envio
subjectstringSimaté 200 caracteres
htmlstringUm dos doiscorpo HTML, até 200.000 caracteres
textstringUm dos doiscorpo em texto puro, até 20.000 caracteres
fromNamestringNãonome de exibição do remetente (até 80 caracteres). O endereço é sempre o e-mail dono do token

Exemplo

curl --location 'https://backend.sendeasy.app/api/v1/email/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer TOKEN_DO_EMAIL' \
  --data '{
    "to": "cliente@exemplo.com",
    "subject": "Redefinição de senha",
    "fromName": "Minha Plataforma",
    "html": "<p>Olá! Clique no link abaixo para criar uma nova senha.</p>"
  }'

Resposta de sucesso:

{
  "success": true,
  "id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61"
}

Guarde o id: é por ele que você acompanha a entrega em GET /api/v1/email/sends/:id. A resposta confirma que o e-mail foi aceito para entrega; a entrega final depende do servidor do destinatário.

Diagnóstico da integração

GET /api/v1/email/health

Não consome crédito. Diz se o e-mail do token já está verificado — a causa mais comum de envio falhar mesmo com crédito disponível.

curl --location 'https://backend.sendeasy.app/api/v1/email/health' \
  --header 'Authorization: Bearer TOKEN_DO_EMAIL'
{
  "ok": true,
  "senderConfigured": true,
  "sender": "no-reply@suaempresa.com.br",
  "domain": "suaempresa.com.br",
  "channelId": 12
}

Com senderConfigured: false, conclua a verificação do e-mail em Canais → E-mail antes de enviar. (Com API Token do projeto, a resposta vem sem channelId e diz se o projeto tem algum e-mail verificado.)

Status dos envios

Cada envio aceito fica registrado com o status atual e a linha do tempo dos eventos de entrega. Consulte pelo id devolvido no envio ou liste os envios recentes. As consultas não consomem crédito.

MétodoEndpointFinalidade
GET/api/v1/email/sends/:idStatus e linha do tempo de um envio
GET/api/v1/email/sendsEnvios recentes, do mais novo para o mais antigo

Com o token do e-mail você vê os envios daquele e-mail; com o API Token do projeto, os de todos os e-mails do projeto. Limite das consultas: 120 requisições por minuto por origem, separado do limite de envio.

Status

statusSignificado
acceptedaceito pela Sendeasy, ainda sem evento de entrega
sentsaiu para o servidor do destinatário
delivery_delayedo servidor do destinatário adiou a entrega (nova tentativa automática)
deliveredentregue ao servidor do destinatário
openedaberto pelo destinatário
clickedo destinatário clicou em um link
bounceddevolvido (endereço inexistente, caixa cheia, bloqueio); o motivo vem em detail
complainedo destinatário marcou como spam
failedo envio falhou antes de sair
suppressednão enviado: o endereço está bloqueado por devoluções ou reclamações anteriores
canceledenvio cancelado

O status só avança: eventos que chegam fora de ordem (aberto antes de entregue) não fazem o status voltar, e bounced/complained prevalecem sobre os demais.

Consultar um envio

curl --location 'https://backend.sendeasy.app/api/v1/email/sends/9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61' \
  --header 'Authorization: Bearer TOKEN_DO_EMAIL'
{
  "id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61",
  "status": "bounced",
  "from": "no-reply@suaempresa.com.br",
  "to": ["cliente@exemplo.com"],
  "subject": "Redefinição de senha",
  "createdAt": "2026-11-17T14:02:11.000Z",
  "lastEventAt": "2026-11-17T14:02:14.000Z",
  "events": [
    { "status": "sent", "at": "2026-11-17T14:02:12.000Z", "detail": null },
    {
      "status": "bounced",
      "at": "2026-11-17T14:02:14.000Z",
      "detail": { "type": "Permanent", "subType": "General", "message": "The recipient's mailbox does not exist." }
    }
  ]
}

Envios feitos antes deste registro existir também podem ser consultados pelo id: nesse caso a resposta traz o status atual, sem a linha do tempo.

Listar envios

curl --location 'https://backend.sendeasy.app/api/v1/email/sends?status=bounced&since=2026-11-01' \
  --header 'Authorization: Bearer TOKEN_DO_EMAIL'
ParâmetroObservações
statusum dos status da tabela acima
tosó envios para este destinatário
since / untilintervalo pela data do envio (ISO 8601)
pagepágina, a partir de 1
limititens por página, até 100 (padrão 50)
{ "sends": [ { "id": "9fbbb3a9-...", "status": "bounced", "...": "..." } ], "count": 1, "page": 1, "hasMore": false }

No console

Os mesmos envios aparecem em Canais → E-mail → Configurações → API de envio → Envios pela API, com filtro por status e a linha do tempo de cada envio.

Webhook de status

Se o projeto tem um webhook configurado (em Integrações), cada evento de um envio pela API chega no evento message_status, com channel: "email":

{
  "event": "message_status",
  "channel": "email",
  "channelId": "uuid-do-canal-de-email",
  "data": {
    "messageId": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61",
    "status": "delivered",
    "currentStatus": "delivered",
    "timestamp": "2026-11-17T14:02:13.000Z",
    "to": ["cliente@exemplo.com"],
    "subject": "Redefinição de senha",
    "detail": null
  }
}

status é o evento que acabou de chegar; currentStatus, o status do envio depois dele.

Créditos e estorno

  • Cada envio aceito desconta 1 crédito de e-mail do projeto.
  • Sem crédito, a rota responde 402 ERR_NO_EMAIL_CREDITS antes de qualquer débito.
  • Se o envio falhar depois do débito (remetente não configurado, provedor indisponível), o crédito é estornado automaticamente e a rota responde 502/503.

Códigos de erro

HTTPerrorQuando acontece
400ERR_EMAIL_INVALID_BODYpayload inválido (sem to/subject, sem html nem text, nenhum destinatário válido)
400ERR_EMAIL_TOO_MANY_RECIPIENTSmais de 10 destinatários em um envio
401ERR_API_TOKEN_NOT_PROVIDED / ERR_API_TOKEN_INVALIDheader ausente ou token inválido/inativo
402ERR_NO_EMAIL_CREDITSprojeto sem créditos de e-mail
400ERR_VALIDATIONfiltro inválido na listagem de envios (o campo vem em params.field)
404ERR_EMAIL_SEND_NOT_FOUNDid de envio desconhecido ou de outro e-mail/projeto
429ERR_PUBLIC_EMAIL_RATE_LIMITmais de 20 envios ou 120 consultas por minuto
502ERR_EMAIL_SEND_FAILEDfalha no provedor ao enviar (crédito estornado)
502ERR_EMAIL_STATUS_UNAVAILABLEnão foi possível consultar agora o status de um envio antigo; tente de novo
503ERR_EMAIL_SENDER_NOT_CONFIGUREDe-mail do token ainda não verificado (com token do e-mail, antes de qualquer débito)

E-mail API × Integração Custom

A Sendeasy tem duas formas de enviar e-mail por API — escolha pelo tipo de token que você tem:

E-mail API (/api/v1/email/send)Custom (/api/integration/generic)
Tokentoken do e-mail (Canais → E-mail → API de envio)Token de integração amarrado a um canal de e-mail
Remetenteo e-mail dono do tokeno canal do token
Uso típicoe-mails transacionais de uma aplicação suaintegrações por canal, com bcc, inReplyTo etc.

Detalhes da integração Custom em /server/integracoes.

Essa informação foi útil?