> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# email.delivery.updated

> Occurs when an email delivery status is updated, and the status changes to `delivered` or `failed`.

Use `email.delivery.updated` to handle this event at your webhook endpoint.

## Triggers

Occurs when an email delivery status is updated, and the status changes to `delivered` or `failed`.

Subscribe to `email.delivery.updated` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Syntax

YCloud sends an HTTP `POST` request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under **Parameters**. Optional fields and other variants are described below.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "email.delivery.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "emailDelivery": {
    "emailId": "<EMAIL_ID>",
    "recipientAddress": "<RECIPIENT_ADDRESS>",
    "status": "<STATUS>",
    "externalId": "<EXTERNAL_ID>"
  }
}
```

## Parameters

Validate the `YCloud-Signature` HTTP header before you process the JSON body. See [signature validation](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Event envelope

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique ID for the event. Minimum length: `6`. Maximum length: `128`. |
| `type` | string | Yes | Always `email.delivery.updated`. |
| `apiVersion` | string | Yes | The API version used to render this event. |
| `createTime` | string (date-time) | Yes | The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. |

### Event payload

| Parameter | Type | Required | Description |
| - | - | - | - |
| `emailDelivery` | object | No | Event-specific `emailDelivery` payload. |

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, **Required** applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

#### emailDelivery

| Parameter | Type | Required | Description |
| - | - | - | - |
| `emailId` | string | Yes | Unique ID for the related email you've previously sent.Minimum length: `6`. Maximum length: `128`. |
| `recipientAddress` | string | Yes | A recipient's email address. |
| `status` | string | No | Delivery status of the email to the specific recipient address.<ul><li>`sending`: The messaging request is accepted by our system.</li><li>`failed`: The message failed to be sent from our system.</li><li>`sent`: The message has been sent from our system.</li><li>`delivered`: Our system has received a delivery receipt indicating that message is delivered.</li><li>`undelivered`: Our system has received a delivery receipt indicating that message is not delivered.</li></ul> |
| `errorCode` | string | No | Error code when the email is undeliverable. |
| `errorMessage` | string | No | Error message when the email is undeliverable. |
| `externalId` | string | No | The `externalId` you set when you sent the email. |
| `bizType` | string | No | This can be either empty or one of `email`, or `verify`. Defaults to `email`.<ul><li>`email`: Indicates that the message is sent via the **Email** product.</li><li>`verify`: Indicates that the message is sent via the **Verify** product.</li></ul> |
| `verificationId` | string | No | The verification ID. Included only when `bizType` is `verify`. |

## Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
  }
}
```

After verifying the signature and durably accepting the event, return a `2xx` response. Process slow work asynchronously.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.