# Email API Overview

The Email API lets you send transactional and marketing emails to single or multiple recipients. The endpoint accepts a JSON object that specifies the sender, recipients, subject, and content of the email.

The `content` object requires the `subject` and `html` fields. Twilio Email doesn't require the `text` field. If you don't provide it, Twilio generates a plain-text version from your HTML body.

## Base URL

All requests to the Email API use the following base URL:

`https://comms.twilio.com/v1/Emails`

## Sending concepts

### Asynchronous operations

The `Emails` endpoint is asynchronous. When you submit a request, the API returns a `202 Accepted` status and an `operationId`.

* **Track progress**: Use the `operationLocation` URL in the response to poll for the status of your send.
* **Check status**: Issue a `GET` request to the `operationLocation` URI to retrieve the current status.

### Operation status values

Each Operation progresses through the following statuses:

| Status       | Description                                       |
| ------------ | ------------------------------------------------- |
| `SCHEDULED`  | The operation is scheduled for future processing. |
| `PROCESSING` | The operation is currently being processed.       |
| `COMPLETED`  | All emails in the operation have been processed.  |
| `CANCELED`   | The operation was canceled.                       |

### Email status values

Each individual email progresses through a series of statuses as it moves from submission to delivery:

| Status        | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `SCHEDULED`   | The email is scheduled for future delivery.                         |
| `QUEUED`      | The email is queued for sending.                                    |
| `SENT`        | The email was sent to the recipient's mail server.                  |
| `DELIVERED`   | The recipient's mail server confirmed delivery.                     |
| `UNDELIVERED` | The email was sent by Twilio but wasn't delivered to the recipient. |
| `OPENED`      | The recipient opened the email.                                     |
| `FAILED`      | The email failed during processing.                                 |
| `CANCELED`    | The email was canceled through an API request.                      |
| `INBOUND`     | The email was received by Twilio from an external source.           |

### Personalize with Liquid

You can use [LiquidJS](https://liquidjs.com) templating in the `subject`, `text`, and `html` fields.

For each variable in your content (for example, `{{firstName}}`), include a matching key in the `variables` object for every recipient in the `to` array. For examples, see [Personalization with variables](/docs/email/api/mail-send#personalization-with-variables).

### Schedule a send

Use the `schedule` object to send an email at a future time. The `sendAt` field is an array, but currently only the first value is used. Provide a value in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format (for example, `2026-12-15T14:15:22Z`). You can schedule emails up to 7 days in advance.

If your schedule has the flexibility, schedule sending your email message at off-peak times. Most emails are scheduled at the top of the hour or half hour. Scheduling at off-peak times, like `10:53` rather than `11:00`, can lower deferral rates.

### Attachments

To include file attachments in your email message, add an `attachments` array to the request body. Each attachment requires the following fields:

| Field         | Necessity | Description                                                          | Example                               |
| ------------- | --------- | -------------------------------------------------------------------- | ------------------------------------- |
| `filename`    | Required  | The name of the file displayed to the recipient.                     | `example.pdf`                         |
| `contentType` | Required  | The MIME type of the file included in the email message.             | `application/pdf`                     |
| `content`     | Required  | The file content encoded in Base64.                                  |                                       |
| `cid`         | Optional  | A Content-ID that references the attachment inline in the HTML body. | `<img src="cid:yourContentIdHere" />` |

Attachments count toward the [total request size limit](#request-limitations).

### Pagination

The List endpoints for both [Email](/docs/email/api/reference/mail-send-resource) and [Email Operation](/docs/email/api/reference/email-operation-resource) resources support pagination with the following query parameters:

* `pageToken` — A token returned in the previous response to fetch the next page of results.
* `pageSize` — The number of records to return per page. Minimum: 1, maximum: 1,000, default: 50.

### Tags

If you want to categorize email messages for filtering and tracking purposes, add custom metadata called *tags* to your List requests.

To filter the [List Emails](/docs/email/api/reference/mail-send-resource) endpoint with tags, use the following query string format:

```http
?tags=key1:value1;key2:value2;
```

When you specify multiple tags, the API returns only emails that match all of them.

### Tag limitations

These tags have the following constraints:

* Maximum of 10 key-value pairs per email message.
* Maximum key length: 128 characters.
* Maximum value length: 256 characters.
* Keys and values can contain alphanumeric characters, periods (`.`), underscores (`_`), hyphens (`-`), and tildes (`~`).

## Request limitations

* Your full request, including attachments, must not exceed 10 MB.
* The total number of recipients must be no more than 10,000.
* The `from` field doesn't support Unicode encoding.

## Validation

When you send a request to the `v1/Emails` endpoint, Twilio validates your JSON payload before sending the email. If Twilio finds errors, Twilio returns as many issues as possible in its single error response. To learn more about possible errors, see [Status codes and errors](/docs/email/api/errors).