Evento de webhook · Entrega

failed

Enviado quando desistimos de um email depois que as novas tentativas se esgotam.

i

Enviado como um POST assinado para a sua URL de webhook. Veja Configuração e eventos para saber como verificar a assinatura.

Payload

// Rate-limit cycles ran out
{
  "event": "failed",
  "emailId": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
  "timestamp": "2026-10-23T04:32:10.000Z",
  "data": {
    "recipientEmail": "user@example.com",
    "fromAddress": "hello@yourdomain.com",
    "reason": "Max retries (4) exceeded: 421 4.7.28 Our system has detected an unusual rate of mail from your IP"
  }
}
!

Você também pode receber bounced. Quando erros temporários, falhas de conexão ou greylisting esgotam as novas tentativas, o email também é registrado como bounce e um evento bounced é enviado. Quando os ciclos de rate limit se esgotam, só failed é enviado.

i

Controle por quanto tempo continuamos tentando. Defina retryRateLimited, retryUnavailable e retryUnavailableSeconds por email.

Opções de entrega →

Referência dos campos

  • event

    Valor fixo: "failed".

  • emailId

    ID do email, o mesmo retornado pelo POST /send.

  • timestamp

    Quando o evento aconteceu (ISO 8601, UTC).

  • data.recipientEmail

    Endereço de email do destinatário.

  • data.fromAddress

    Endereço de email do remetente.

  • data.reason

    Por que desistimos. "Max retries (N) exceeded" significa que os ciclos de rate limit se esgotaram; caso contrário, é a última resposta do servidor de destino.

  • data.notSent

    Só aparece (true) quando o email nem chegou a ser enviado por causa da sua conta: sem créditos, conta bloqueada ou restrita, domínio do remetente na Spamhaus ou sem DKIM, ou From inválido. Não é bounce. O log fica com status not_sent e data.reason traz o motivo exato.