Quick Start

Do zero ao primeiro e-mail na fila em poucos passos. O indispensável é o domínio verificado no DNS, sem isso o envio não sai.

Em poucas palavras

Verifique um domínio no DNS, prova que você controla o remetente (noreply@seudominio.com).
Envie com assunto e corpo (texto e/ou HTML) para até 500 destinatários por chamada.
Consulte, agende ou cancele e receba status por webhooks.

Contexto: Introdução. Escopos: Escopos da API Key.

Antes de começar

Chave com email:domains:create, email:domains:list e email:send (ou escopo admin em teste)
O domínio do from precisa estar VERIFIED antes do envio
Autenticação: Authorization: Bearer sk_live_... ou x-api-key
Base URL: https://api.notifique.dev, use sk_test_... no Sandbox se estiver começando

No sandbox com sk_test_, o domínio From não precisa estar verificado. Com sk_live_, envie ao destino de teste do workspace (…@sandbox.notifique.dev) para interceptar na Inbox sandbox sem entrega real. Pré-visualização HTML e checker de compatibilidade estão no composer Novo e-mail e na inbox.

1. Verificar domínio

Dois caminhos, escolha o que combina com sua integração:

1A, Pelo painel

Settings → E-mail → Adicionar domínio
Copie os registros DNS (TXT/CNAME) para o provedor do domínio
Clique em Verificar até o status ficar VERIFIED

1B, Pela API

Registrar domínio

POST /v1/email/domains
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "domain": "seudominio.com"
}

Resposta esperada: 200 com status PENDING e registros DNS (estrutura atual):

{
  "success": true,
  "data": {
    "id": "clxx123...",
    "domain": "seudominio.com",
    "status": "PENDING",
    "dnsRecords": [
      { "type": "TXT", "name": "api._domainkey.seudominio.com", "value": "k=rsa; p=..." },
      { "type": "CNAME", "name": "bounce.z.seudominio.com", "value": "bounce.z.notifique.dev" },
      { "type": "CNAME", "name": "bounce.e.seudominio.com", "value": "bounce.e.notifique.dev" },
      { "type": "CNAME", "name": "tracking.seudominio.com", "value": "tracking.notifique.dev" }
    ],
    "suggestedDnsRecords": [
      { "type": "TXT", "name": "seudominio.com", "value": "v=spf1 include:_spf.notifique.dev ~all" },
      { "type": "TXT", "name": "_dmarc.seudominio.com", "value": "v=DMARC1; p=none; rua=mailto:dmarc@seudominio.com" }
    ],
    "inboundDnsRecords": [
      { "type": "MX", "name": "seudominio.com", "value": "10 inbound.notifique.dev" }
    ],
    "dkim": { "name": "api._domainkey.seudominio.com", "value": "k=rsa; p=..." },
    "verification": {
      "domainStatus": "PENDING",
      "providers": [
        { "id": "send", "status": "pending", "checks": { "dkim": "pending", "bounce": "pending" }, "isPrimary": true },
        { "id": "delivery", "status": "pending", "checks": { "dkim": "pending", "bounce": "pending", "tracking": "pending" } }
      ],
      "records": {
        "TXT|api._domainkey.seudominio.com": "pending",
        "MX|seudominio.com": "not_checked"
      }
    },
    "createdAt": "2025-02-15T10:00:00.000Z"
  },
  "message": "Add the DNS record(s) above to your domain, then call the verify endpoint or use the Verify button in the dashboard."
}

Os hosts exatos (bounce.z, inbound, etc.) podem variar conforme a instância da plataforma. Use sempre os valores retornados em data, não copie de outro workspace.

Guarde o id do domínio para o passo de verificação. Verificar (repita após propagar o DNS):

POST /v1/email/domains/:id/verify
Authorization: Bearer sk_live_xxxxx

DNS ainda pendente, 200, não é erro HTTP:

{
  "success": true,
  "verified": false,
  "code": "EMAIL_DOMAIN_DNS_PENDING",
  "message": "provedor de envio: pendente (DKIM, bounce) · provedor de entrega: pendente (DKIM, bounce, tracking)",
  "verificationSummary": "provedor de envio: pendente (DKIM, bounce) · provedor de entrega: pendente (DKIM, bounce, tracking)",
  "data": {
    "id": "clxx...",
    "domain": "seudominio.com",
    "status": "PENDING",
    "verification": { "domainStatus": "PENDING", "records": { "TXT|api._domainkey.seudominio.com": "pending" } }
  }
}

Verificado, 200:

{
  "success": true,
  "verified": true,
  "code": "EMAIL_DOMAIN_VERIFIED",
  "message": "Domínio verificado com sucesso.",
  "verificationSummary": "provedor de envio: OK · provedor de entrega: OK",
  "data": { "id": "clxx...", "domain": "seudominio.com", "status": "VERIFIED", "verifiedAt": "2025-02-16T12:00:00.000Z" }
}

Códigos e erros HTTP: Respostas de erro.

2. Enviar e-mail

Com domínio VERIFIED, envie para um ou vários destinatários. to é sempre um array (até 500).

POST /v1/email/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Confirmação de pedido",
    "html": "<p>Olá, seu pedido foi confirmado.</p>",
    "text": "Olá, seu pedido foi confirmado."
  }
}

Obrigatório em payload: subject e pelo menos text ou html. No from, coloque o nome antes do e-mail — como aparece na caixa de entrada do destinatário.

Enviar com cópias (CC e BCC)

Cópia (CC) é como colocar colegas no mesmo e-mail do Outlook: todos veem quem recebeu. Cópia oculta (BCC) funciona igual, mas os outros destinatários não sabem quem está em BCC. Com cc ou bcc, todos recebem um único e-mail. Sem cópias, cada endereço em to recebe um envio separado — como mandar cartas individuais para cada pessoa.

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "cc": ["gestor@example.com"],
  "bcc": ["auditoria@example.com"],
  "type": "email",
  "payload": {
    "subject": "Pedido #12345",
    "html": "<p>Segue o comprovante.</p>"
  }
}

Responder para outro endereço (replyTo)

Quando o remetente é noreply@..., a resposta do cliente normalmente não chega a lugar nenhum. Use replyTo para dizer para onde vão as respostas — como deixar um bilhete “responda na recepção”.

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "replyTo": ["atendimento@seudominio.com"],
  "type": "email",
  "payload": {
    "subject": "Dúvida sobre seu pedido",
    "html": "<p>Responda este e-mail se precisar de ajuda.</p>"
  }
}

Anexos

Até 10 arquivos, no máximo ~30 MB no total. Envie o arquivo em base64 (content) ou informe uma URL pública (path).

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Comprovante do pedido",
    "html": "<p>Segue o comprovante em anexo.</p>"
  },
  "attachments": [
    {
      "filename": "comprovante.pdf",
      "content": "JVBERi0xLjQK...",
      "contentType": "application/pdf"
    },
    {
      "filename": "logo.png",
      "path": "https://cdn.seudominio.com/assets/logo.png",
      "contentType": "image/png"
    }
  ]
}

E-mail com links

Links no HTML funcionam como em qualquer cliente de e-mail. Use <a href="..."> no corpo para botões de ação, reset de senha, rastreamento de pedido e afins.

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Redefina sua senha",
    "html": "<p>Clique <a href=\"https://app.seudominio.com/reset?token=abc\">aqui</a> para redefinir sua senha. O link expira em 1 hora.</p>"
  }
}

Enviar com template

Se você já tem um template do workspace com canal e-mail habilitado:

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "name": "Maria", "orderId": "12345" }
  }
}

cc, bcc, replyTo e attachments também funcionam com template — o mesmo padrão do envio com conteúdo livre. Resposta esperada: 202

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clemail1..."],
  }
}

messageIds retorna os IDs dos envios.

Domínio do from não verificado → 400 com DOMAIN_NOT_VERIFIED.

Opções em options: priority (high, normal, low), category (transactional ou marketing), webhook (URL e segredo só deste lote). metadata fica na raiz do body (não em options). Use headers para responder threads (In-Reply-To, References). Detalhes na referência da API. RFC 8058 (one-click unsubscribe): por padrão, se o destinatário for contato do workspace, a Notifique injeta List-Unsubscribe. Em e-mails transacionais use "listUnsubscribe": false. Tópico inválido → 400 INVALID_LIST_UNSUBSCRIBE_TOPIC. Guia: One-click unsubscribe.

3. Consultar, agendar e cancelar

Listar enviados

GET /v1/email/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

Filtros opcionais: fromDate, toDate, status, emailDomainId. Requer email:read. Ver um envio

GET /v1/email/messages/:id
Authorization: Bearer sk_live_xxxxx

Agendar, inclua no body do envio:

{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Lembrete",
    "html": "<p>Conteúdo.</p>"
  },
  "schedule": {
    "sendAt": "2025-12-31T14:00:00.000Z"
  }
}

Cancelar (status QUEUED ou SCHEDULED):

POST /v1/email/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

Escopo: email:cancel. Créditos do agendamento voltam para o workspace.

4. Evitar duplicata

Header Idempotency-Key no POST. Repetições em até 24 h não criam dois envios iguais. Veja Segurança e Confiabilidade.

5. Webhooks (opcional)

Configure email.sent, email.delivered, email.opened, email.clicked, email.failed, email.complained, email.cancelled e email.received (inbound) para acompanhar sem polling. Guia: Eventos dos webhooks. Recebimento: Recebimento de e-mails.

Todos os tipos de envio

Na referência da API (aba E-mail), abra Enviar e-mail (POST /v1/...) e escolha o exemplo no playground: básico, cópias, anexos, links, agendado, template e template com cópias.

Próximos passos

Introdução: quando usar e ciclo de status
Escopos: permissões da chave
Eventos dos webhooks: status em tempo real
Respostas de erro: códigos HTTP e code

API E-mail

E-mail

Domínios

E-mails recebidos

Em poucas palavras

Antes de começar

1. Verificar domínio

1A, Pelo painel

1B, Pela API

2. Enviar e-mail

Enviar com cópias (CC e BCC)

Responder para outro endereço (replyTo)

Anexos

E-mail com links

Enviar com template

3. Consultar, agendar e cancelar

4. Evitar duplicata

5. Webhooks (opcional)

Todos os tipos de envio

Próximos passos

​Em poucas palavras

​Antes de começar

​1. Verificar domínio

​1A, Pelo painel

​1B, Pela API

​2. Enviar e-mail

​Enviar com cópias (CC e BCC)

​Responder para outro endereço (replyTo)

​Anexos

​E-mail com links

​Enviar com template

​3. Consultar, agendar e cancelar

​4. Evitar duplicata

​5. Webhooks (opcional)

​Todos os tipos de envio

​Próximos passos

Em poucas palavras

Antes de começar

1. Verificar domínio

1A, Pelo painel

1B, Pela API

2. Enviar e-mail

Enviar com cópias (CC e BCC)

Responder para outro endereço (replyTo)

Anexos

E-mail com links

Enviar com template

3. Consultar, agendar e cancelar

4. Evitar duplicata

5. Webhooks (opcional)

Todos os tipos de envio

Próximos passos