Email API Overview

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

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

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.

Each Operation progresses through the following statuses:

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

You can use LiquidJS 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.

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 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.

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

Attachments count toward the total request size limit.

The List endpoints for both Email and Email Operation 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.

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 endpoint with tags, use the following query string format:

?tags=key1:value1;key2:value2;

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

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 (~).

• 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.

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.