Quick Start - Notifique

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é 100 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

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:

{
  "success": true,
  "data": {
    "id": "clxx123...",
    "domain": "seudominio.com",
    "status": "PENDING",
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "notifique._domainkey.seudominio.com",
        "value": "p=MIGf..."
      }
    ],
    "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."
}

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": "Os registros DNS ainda não foram verificados. Confira no seu provedor DNS e tente novamente em alguns minutos.",
  "data": { "id": "clxx...", "domain": "seudominio.com", "status": "PENDING" }
}

Verificado, 200:

{
  "success": true,
  "verified": true,
  "code": "EMAIL_DOMAIN_VERIFIED",
  "message": "Domínio verificado com sucesso.",
  "data": { "id": "clxx...", "domain": "seudominio.com", "status": "VERIFIED" }
}

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é 100).

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

{
  "from": "noreply@seudominio.com",
  "fromName": "Suporte",
  "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.

Enviar com template

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

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

Resposta esperada: 202

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

messageIds é o campo canônico; emailIds é alias de compatibilidade.

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

Opções em options: priority (high, normal, low), webhook (URL e segredo só deste lote), metadata (texto livre). 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": "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 agendamento (só com status 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 e email.cancelled para acompanhar sem polling. Guia: Eventos dos webhooks.

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: HTML+texto, Só texto, Template, Agendado, List-Unsubscribe.

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

​Em poucas palavras

​Antes de começar

​1. Verificar domínio

​1A, Pelo painel

​1B, Pela API

​2. Enviar e-mail

​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 template

3. Consultar, agendar e cancelar

4. Evitar duplicata

5. Webhooks (opcional)

Todos os tipos de envio

Próximos passos