email.delivery.updated

Use email.delivery.updated para manipular este evento em seu endpoint de webhook.

Gatilhos

Ocorre quando o status de entrega de um e-mail é atualizado e o status muda para delivered ou failed. Inscreva-se em email.delivery.updated quando você configurar seu endpoint de webhook.

Sintaxe

A YCloud envia uma requisição HTTP POST para a URL de webhook configurada. O formato a seguir mostra uma variante do payload. Os valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variantes estão descritos abaixo.

{
  "id": "<ID>",
  "type": "email.delivery.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "emailDelivery": {
    "emailId": "<EMAIL_ID>",
    "recipientAddress": "<RECIPIENT_ADDRESS>",
    "status": "<STATUS>",
    "externalId": "<EXTERNAL_ID>"
  }
}

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo para o evento. Comprimento mínimo: `6`. Comprimento máximo: `128`.
`type`	string	Sim	Sempre `email.delivery.updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`emailDelivery`	object	Não	Payload de `emailDelivery` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objetos, Obrigatório se aplica quando o objeto pai estiver presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

emailDelivery

Parâmetro	Tipo	Obrigatório	Descrição
`emailId`	string	Sim	ID exclusivo para o e-mail relacionado enviado anteriormente. Comprimento mínimo: `6`. Comprimento máximo: `128`.
`recipientAddress`	string	Sim	Um endereço de e-mail do destinatário.
`status`	string	Não	Status de entrega do e-mail para o endereço de destinatário específico. `sending`: A solicitação de mensagem foi aceita pelo nosso sistema. `failed`: Falha ao enviar a mensagem do nosso sistema. `sent`: A mensagem foi enviada pelo nosso sistema. `delivered`: Nosso sistema recebeu um comprovante de entrega indicando que a mensagem foi entregue. `undelivered`: Nosso sistema recebeu um comprovante de entrega indicando que a mensagem não foi entregue.
`errorCode`	string	Não	Código de erro quando o e-mail não puder ser entregue.
`errorMessage`	string	Não	Mensagem de erro quando o e-mail não puder ser entregue.
`externalId`	string	Não	O `externalId` que você definiu ao enviar o e-mail.
`bizType`	string	Não	Pode estar vazio ou ser um de `email` ou `verify`. O padrão é `email`. `email`: Indica que a mensagem foi enviada pelo produto Email. `verify`: Indica que a mensagem foi enviada pelo produto Verify.
`verificationId`	string	Não	O ID de verificação. Incluído somente quando `bizType` for `verify`.

Exemplo

O JSON a seguir é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos.

{
  "id": "evt_example_email_delivery_updated",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "email_12345678",
    "recipientAddress": "recipient@example.com",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Após verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Para orientações detalhadas sobre cenários, consulte exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

email.delivery.updated

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

emailDelivery

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​emailDelivery

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

emailDelivery

Exemplo