email.delivery.updated

Usa email.delivery.updated para gestionar este evento en tu endpoint de webhook.

Desencadenadores

Se produce cuando se actualiza el estado de entrega de un correo electrónico y el estado cambia a delivered o failed. Suscríbete a email.delivery.updated cuando configures tu endpoint de webhook.

Sintaxis

YCloud envía una solicitud HTTP POST a tu URL de webhook configurada. La siguiente estructura muestra una variante de la carga útil. Los valores entre corchetes angulares son marcadores de posición; sus tipos se indican en Parámetros. Los campos opcionales y otras variantes se describen a continuación.

{
  "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

Valida el encabezado HTTP YCloud-Signature antes de procesar el cuerpo JSON. Consulta la validación de firmas.

Envoltura del evento

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	ID único para el evento. Longitud mínima: `6`. Longitud máxima: `128`.
`type`	string	Sí	Siempre `email.delivery.updated`.
`apiVersion`	string	Sí	La versión de la API utilizada para representar este evento.
`createTime`	string (date-time)	Sí	La hora en la que se creó este evento, con formato RFC 3339. P. ej., `2022-06-01T12:00:00.000Z`.

Carga útil del evento

Parámetro	Tipo	Requerido	Descripción
`emailDelivery`	object	No	Carga útil de `emailDelivery` específica del evento.

Los cuatro campos comunes de la envoltura son obligatorios. Los campos de la carga útil dependen de la variante del evento. En cada tabla de objetos, Requerido aplica cuando su objeto padre está presente. Los campos opcionales pueden omitirse; una muestra de ejemplo no hace que un campo sea obligatorio.

emailDelivery

Parámetro	Tipo	Requerido	Descripción
`emailId`	string	Sí	ID único para el correo electrónico relacionado que enviaste previamente. Longitud mínima: `6`. Longitud máxima: `128`.
`recipientAddress`	string	Sí	Dirección de correo electrónico de un destinatario.
`status`	string	No	Estado de entrega del correo electrónico a la dirección de destinatario específica. `sending`: la solicitud de mensajería ha sido aceptada por nuestro sistema. `failed`: el mensaje no pudo enviarse desde nuestro sistema. `sent`: el mensaje ha sido enviado desde nuestro sistema. `delivered`: nuestro sistema ha recibido un comprobante de entrega que indica que el mensaje se ha entregado. `undelivered`: nuestro sistema ha recibido un comprobante de entrega que indica que el mensaje no se ha entregado.
`errorCode`	string	No	Código de error cuando el correo electrónico no se puede entregar.
`errorMessage`	string	No	Mensaje de error cuando el correo electrónico no se puede entregar.
`externalId`	string	No	El `externalId` que definiste al enviar el correo electrónico.
`bizType`	string	No	Puede estar vacío o ser uno de `email` o `verify`. El valor predeterminado es `email`. `email`: indica que el mensaje se envía a través del producto Email. `verify`: indica que el mensaje se envía a través del producto Verify.
`verificationId`	string	No	El ID de verificación. Solo se incluye cuando `bizType` es `verify`.

Ejemplo

El siguiente JSON es el cuerpo entregado a tu receptor. Los ID, los números de teléfono y otros valores de cuenta son solo 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"
  }
}

Después de verificar la firma y aceptar el evento de forma duradera, devuelve una respuesta 2xx. Procesa las tareas lentas de forma asíncrona.

HTTP/1.1 200 OK

Para ver guías detalladas de escenarios, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

email.delivery.updated

Desencadenadores

Sintaxis

Parámetros

Envoltura del evento

Carga útil del evento

emailDelivery

Ejemplo

​Desencadenadores

​Sintaxis

​Parámetros

​Envoltura del evento

​Carga útil del evento

​emailDelivery

​Ejemplo

Desencadenadores

Sintaxis

Parámetros

Envoltura del evento

Carga útil del evento

emailDelivery

Ejemplo