Evento de webhook · Entrega
failed
Enviado quando desistimos de um email depois que as novas tentativas se esgotam.
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.
Controle por quanto tempo continuamos tentando. Defina retryRateLimited, retryUnavailable e retryUnavailableSeconds por email.
Opções de entrega →Referência dos campos
eventValor fixo: "failed".
emailIdID do email, o mesmo retornado pelo POST /send.
timestampQuando o evento aconteceu (ISO 8601, UTC).
data.recipientEmailEndereço de email do destinatário.
data.fromAddressEndereço de email do remetente.
data.reasonPor 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.notSentSó 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.