Webhooks

Webhooks enviam eventos do ciclo de vida do e-mail aos seus endpoints conforme acontecem. Crie endpoints no painel, escolha quais tipos de evento cada um recebe e inspecione cada entrega (payload, resposta, tentativas) no log de entregas por endpoint.

Tipos de eventoCopiar link da seção

Eventos de conta não carregam e-mail; data descreve a situação da equipe:

No plano Free, as equipes Free que você criou dividem uma cota diária e um só histórico de bounces e reclamações: cada um desses eventos dispara uma vez para todas elas, numa das equipes que enviaram, com os números somados.

Eventos de audiência disparam quando um contato ou a lista de supressão muda, seja quem for que mudou. data traz o contato no formato do Resend — id, email, first_name, last_name, unsubscribed, created_at, updated_at — mais source: api, dashboard, hosted_page (a central de preferências) ou one_click (um POST de header RFC 8058). Dos eventos abaixo, o Resend emite contact.created, contact.updated, contact.deleted, suppression.added e suppression.removed; os demais são extensões do MillionSend. O MillionSend não envia o contact.topics.updated do Resend: escolha contact.topic_opt_in e contact.topic_opt_out no lugar dele.

E-mails agendados, com falha e suprimidosCopiar link da seção

Como todo evento de um e-mail que você envia, esses três trazem email_id, from, to, subject e created_at, a hora do evento.

{
  "type": "email.scheduled",
  "created_at": "2026-10-13T09:30:12.084Z",
  "data": {
    "email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
    "from": "Acme <hello@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-13T09:30:12.084Z"
  }
}

email.failed e email.suppressed disparam uma vez por e-mail que termina como failed ou suppressed, e acrescentam um objeto que diz o motivo.

{
  "type": "email.failed",
  "created_at": "2026-10-13T10:00:02.317Z",
  "data": {
    "email_id": "3f7b2c71-5274-4246-82f3-57bc1563c276",
    "from": "Acme <billing@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your receipt",
    "created_at": "2026-10-13T10:00:02.317Z",
    "failed": {
      "reason": "domain_not_verified"
    }
  }
}

{
  "type": "email.suppressed",
  "created_at": "2026-10-14T09:30:00.912Z",
  "data": {
    "email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
    "from": "Acme <hello@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-14T09:30:00.912Z",
    "suppressed": {
      "type": "OnAccountSuppressionList",
      "message": "The recipient is on your suppression list.",
      "reason": "recipient_suppressed"
    }
  }
}

OnAccountSuppressionList é o valor do Resend; Unsubscribed e Ineligible são do próprio MillionSend.

• Um POST /emails que a lista de supressão sozinha recusa com 422 all_recipients_suppressed guarda um e-mail suppressed, que também dispara o email.suppressed; veja Supressões.
• Remover só alguns destinatários, quando a API recebe o envio ou na hora de enviar, não dispara o email.suppressed: o e-mail vai para os outros.
• Cancelar uma transmissão não dispara nada para os e-mails que deixam de sair.

E-mails recebidosCopiar link da seção

email.received traz o payload do Resend, só com metadados: sem corpo, sem cabeçalhos e sem tamanho dos anexos, e from é só o endereço. received_for lista os endereços dos seus domínios para os quais a mensagem foi entregue, incluindo quem estava em Cco. Quando uma entrega posterior da mesma mensagem chega a mais endereços seus, outro email.received com o mesmo email_id lista só esses.

{
  "type": "email.received",
  "created_at": "2026-10-11T14:37:40.951Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "created_at": "2026-10-11T14:37:40.951Z",
    "from": "ada@example.org",
    "to": ["support@inbound.example.com"],
    "bcc": [],
    "cc": [],
    "received_for": ["support@inbound.example.com"],
    "message_id": "<CAF1x7Qm9@mail.example.org>",
    "subject": "Order #1042",
    "attachments": [
      {
        "id": "b344102e-962e-8943-aef6-271c7743e1dd",
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "content_disposition": "attachment",
        "content_id": null
      }
    ]
  }
}

Eventos de caixas de entradaCopiar link da seção

As caixas de entrada emitem os eventos inbox.* do Resend, mais dois do próprio MillionSend. Eles são opt-in: um endpoint só os recebe quando os escolhe pelo nome, nunca por "todos os eventos".

• O source é api (uma chave de API ou um cliente MCP), dashboard ou system (e-mails chegando, envios, caixas expirando). Nunca é agent.
• inbox é o objeto da caixa, thread é { object, id, subject, folder, labels, read }, email é um e-mail de conversa e draft, um rascunho. email e draft nunca trazem html, text, extracted_text, códigos ou links: busque o conteúdo pela API.
• Os objetos são capturados quando o evento acontece, não quando ele é entregue, então uma segunda mudança rápida não reescreve o primeiro evento.
• Chaves que não se aplicam ficam de fora, nunca vêm como null.

{
  "type": "inbox.email.received",
  "created_at": "2026-10-12T14:03:12.301Z",
  "data": {
    "source": "system",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147",
    "thread_id": "b9e1837b-c150-45c6-a055-73b02ec9f1dc",
    "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
    "thread": {
      "object": "inbox_thread",
      "id": "b9e1837b-c150-45c6-a055-73b02ec9f1dc",
      "subject": "Where is my order?",
      "folder": "inbox",
      "labels": [],
      "read": false
    },
    "email": {
      "id": "155252fb-e93e-45ee-8c19-5080a929c28b",
      "direction": "inbound",
      "from": "Maria Silva <maria@example.org>",
      "to": ["orders@inbound.example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "subject": "Where is my order?",
      "message_id": "<CAF7c1f0a2e5d3b@mail.example.org>",
      "attachments": [],
      "read": false,
      "received_at": "2026-10-12T14:03:11.229Z"
    }
  }
}

{
  "type": "inbox.email.quarantined",
  "created_at": "2026-10-12T14:05:40.017Z",
  "data": {
    "source": "system",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147",
    "thread_id": "6581da0f-148e-49c7-8ba3-b1c2fcabc5ef",
    "email_id": "6166ec82-4ea7-481a-a78d-42c6f84af265",
    "reason": "injection",
    "sender_trust": "external",
    "from": "billing@example.net",
    "subject": "Invoice overdue",
    "received_at": "2026-10-12T14:05:38.442Z"
  }
}

Só algumas caixas. POST /webhooks e PATCH /webhooks/{id} aceitam inbox_ids, até 100 caixas da equipe (null, o padrão, quer dizer todas), e os objetos de webhook o devolvem. Um endpoint assim só recebe os eventos de caixas e o email.received dessas caixas, então os e-mails de endereços do pega-tudo não chegam a ele. No painel: Só estas caixas.

Assinaturas (Standard Webhooks)Copiar link da seção

As entregas são assinadas seguindo a especificação Standard Webhooks — o mesmo esquema que Resend e Svix usam, então código de verificação existente funciona sem mudanças.

Cada endpoint tem um segredo whsec_..., exibido uma única vez na criação. Toda requisição carrega:

webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>

Os mesmos três valores também vão como svix-id, svix-timestamp e svix-signature — os nomes que a documentação do Resend manda ler. Uma assinatura, dois nomes de header: um handler escrito para qualquer uma das famílias verifica sem mudanças.

O conteúdo assinado é {webhook-id}.{webhook-timestamp}.{raw body}. Verifique com qualquer biblioteca Standard Webhooks, por exemplo em Node:

import { Webhook } from "standardwebhooks";

const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});

Sempre verifique contra o corpo bruto da requisição, e rejeite timestamps antigos.

Trazendo seu próprio segredoCopiar link da seção

POST /webhooks aceita um signing_secret opcional: whsec_ seguido de base64 padrão de 24 a 64 bytes — o formato que Resend e Svix emitem. Passe o segredo com que seu receptor já verifica e o endpoint continua funcionando sem novo deploy; omita e o MillionSend gera um. Qualquer outra coisa é rejeitada com 422 signing_secret must be whsec_ followed by base64 of 24-64 bytes.

Para trazer um segredo de outro provedor, leia-o na API ou no painel dele (o Resend o retorna em GET /webhooks/{id}) e crie o endpoint aqui com o mesmo valor:

curl -X POST "https://api.millionsend.com/webhooks" \
  -H "Authorization: Bearer ms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com/webhooks/email",
    "events": ["email.delivered", "email.bounced"],
    "signing_secret": "whsec_..."
  }'

O segredo é retornado na criação e em GET /webhooks/{id}, nunca nas linhas da listagem.

Rotacionando o segredoCopiar link da seção

POST /webhooks/{id}/rotate (ou Rotacionar segredo no painel) gera um novo segredo, ou usa o de signing_secret, e o retorna. Durante overlap_hours (padrão 24, até 72) o segredo anterior continua assinando: toda entrega nessa janela leva as duas assinaturas, separadas por espaço em webhook-signature, então um receptor com qualquer um dos dois verifica. Troque o receptor em qualquer momento da janela; depois dela só o novo assina. 0 descarta o antigo na hora, para um segredo vazado. GET /webhooks/{id} informa o fim da janela em previous_secret_expires_at, e uma segunda rotação dentro da janela substitui o segredo anterior.

curl -X POST "https://api.millionsend.com/webhooks/{id}/rotate" \
  -H "Authorization: Bearer ms_..." \
  -H "Content-Type: application/json" \
  -d '{ "overlap_hours": 24 }'

EntregaCopiar link da seção

Uma entrega é bem-sucedida em qualquer resposta 2xx. Cada endpoint tem a própria fila, iniciada na ordem de vencimento com até oito requisições em andamento a até 50 requisições por segundo; uma rajada de eventos espera na fila em vez de atingir o receptor de uma vez.

Uma tentativa que falha (não-2xx, timeout, erro de conexão) é repetida em um cronograma fixo: 5 s, 5 min, 30 min, 2 h, 5 h, 10 h — seis tentativas em cerca de 18 horas. Um 429 com header Retry-After é respeitado (até uma hora) e não conta como tentativa: é o receptor pedindo espaço, não falhando. Um evento ainda não entregue 24 horas depois de enfileirado é descartado como exhausted, sem nova tentativa.

Após 20 entregas esgotadas consecutivas o endpoint é desativado automaticamente e não recebe mais nada até você reativá-lo na página dele; os eventos do intervalo não são reenviados. Os proprietários da equipe recebem um e-mail quando as entregas de um endpoint começam a falhar (as últimas dez entregas encerradas todas esgotadas), quando ele é desativado e — no máximo uma vez por dia — quando a fila dele tem mais de seis horas de atraso. O painel mostra a profundidade da fila de cada endpoint e há quanto tempo a entrega mais antiga espera.

Um job de reconciliação rearma filas perdidas em quedas, então a entrega é pelo-menos-uma-vez — torne seus handlers idempotentes, chaveados por webhook-id. As linhas de entrega (payload, resposta, tentativas) são mantidas por WEBHOOK_DELIVERY_RETENTION_DAYS (padrão 30) e depois apagadas.

Inscreva cada endpoint só nos eventos de que ele precisa. Uma reimportação completa de contatos não emite nada para os contatos que não mudaram, mas cada contato novo é uma entrega contact.created — um endpoint inscrito em "todos os eventos" recebe todas elas.