Skip to main content

​
O fluxo principal (visão geral)

  1. Registrar domínio e publicar os registros DNS que a API devolver.
  2. Chamar verify até o domínio ficar VERIFIED.
  3. Enviar com POST /v1/email/messages usando um from @seu-dominio.
Só então vale listar, consultar por ID ou cancelar agendados — tudo descrito abaixo.

​
Pré-requisitos

  • API Key com escopos: email:domains:create, email:domains:list, email:send, email:read (e opcionalmente email:cancel para agendados).
  • O domínio do remetente (from) deve estar verificado no workspace antes de enviar.
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx

​
1. Registrar e verificar domínio

Para enviar com um endereço como noreply@seudominio.com, o domínio seudominio.com precisa estar registrado e verificado. Registrar domínio 
POST /v1/email/domains
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "domain": "seudominio.com"
}
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx...",
    "domain": "seudominio.com",
    "status": "PENDING",
    "dnsRecords": [...]
  }
}
Verificar status DNS 
POST /v1/email/domains/:id/verify
Authorization: Bearer sk_live_xxxxx
Configure os registros DNS indicados na resposta (ex.: CNAME, TXT) no seu provedor de DNS. Após propagar, chame o verify novamente até o status do domínio ser VERIFIED (maiúsculas, como na API).

​
2. Enviar e-mail

Com o domínio verificado, envie e-mails usando esse domínio no campo from. Request 
POST /v1/email/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "from": "noreply@seudominio.com",
  "fromName": "Suporte",
  "to": ["cliente@example.com"],
  "subject": "Confirmação de pedido",
  "html": "<p>Olá, seu pedido foi confirmado.</p>",
  "text": "Olá, seu pedido foi confirmado."
}
É obrigatório informar subject e pelo menos um corpo: text e/ou html. Response (202) — envio imediato 
{
  "success": true,
  "data": {
    "emailIds": ["clxx123..."],
    "status": "QUEUED",
    "count": 1
  }
}
Response (202) — agendado Com schedule.sendAt: 
{
  "success": true,
  "data": {
    "emailIds": ["clxx123..."],
    "status": "SCHEDULED",
    "count": 1,
    "scheduledAt": "2025-12-31T14:00:00.000Z"
  }
}
Se o domínio do from não estiver verificado, a API retorna 400 com code: DOMAIN_NOT_VERIFIED.

​
3. Listar e-mails

Liste o histórico de e-mails do workspace com paginação (escopo email:read). Filtros opcionais: fromDate, toDate (ISO 8601, createdAt), status (vários separados por vírgula), emailDomainId (cuid do domínio verificado). Se a API Key tiver restrição domainIds, só aparecem envios daqueles domínios; pedir outro emailDomainId retorna 403. Request 
GET /v1/email/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "data": [
    {
      "id": "clxx123...",
      "to": "cliente@example.com",
      "from": "noreply@seudominio.com",
      "fromName": "Suporte",
      "subject": "Confirmação de pedido",
      "status": "DELIVERED",
      "scheduledFor": null,
      "sentAt": "2025-02-20T14:00:00.000Z",
      "deliveredAt": null,
      "failedAt": null,
      "errorMessage": null,
      "createdAt": "2025-02-20T14:00:00.000Z"
    }
  ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}

​
4. Consultar status

Obtenha o status e os dados de um e-mail pelo ID. Request 
GET /v1/email/messages/:id
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "success": true,
  "data": {
    "id": "clxx123...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "fromName": "Suporte",
    "subject": "Confirmação de pedido",
    "status": "DELIVERED",
    "scheduledFor": null,
    "sentAt": "2025-02-20T14:00:00.000Z",
    "deliveredAt": null,
    "failedAt": null,
    "errorMessage": null,
    "createdAt": "2025-02-20T14:00:00.000Z"
  }
}

​
5. Webhooks (opcional)

Para receber notificações de envio e entrega, configure um webhook com eventos:
  • email.sent — E-mail aceito e enviado.
  • email.delivered — E-mail entregue (notificação do provedor).
  • email.failed — E-mail falhou no envio ou bounce.
  • email.complained — Reclamação de spam.
No payload dos eventos de e-mail, o campo instanceId vem vazio; os dados vão em data (emailId, to, from, status, etc.).

​
6. Agendamento e cancelamento

Agendar: inclua no body do POST /v1/email/messages: 
{
  "from": "noreply@seudominio.com",
  "to": ["cliente@example.com"],
  "subject": "Lembrete",
  "html": "<p>Conteúdo.</p>",
  "schedule": {
    "sendAt": "2025-12-31T14:00:00.000Z"
  }
}
Cancelar: use o escopo email:cancel e chame: 
POST /v1/email/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

​
Resumo do fluxo

  1. POST /v1/email/domains → registrar domínio.
  2. POST /v1/email/domains/:id/verify e configurar DNS até status verified.
  3. POST /v1/email/messages com from (domínio verificado), to, subject, html e/ou text.
  4. GET /v1/email/messages → listar histórico com paginação e filtros (escopo email:read).
  5. GET /v1/email/messages/:id → consultar um envio pelo ID.
  6. (Opcional) Configurar webhook para email.sent, email.delivered, email.failed, email.complained.

​
Referências

  • Idempotência: use o header Idempotency-Key ou x-idempotency-key no envio para evitar duplicatas.