Email Resource

To send emails, retrieve individual email details, and list emails with filtering, use the Email resource. This resource represents an email message sent through the Twilio Email API.

Twilio Email retains data for seven days after creation. Requests for older records may yield incomplete results.

API Base URL

All URLs in the reference documentation use the following base URL:

https://comms.twilio.com/v1

Email Properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

required

Not PII

A reference to an Email.

Example: comms_email_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_email_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

from

oneOf:

required

Not PII

The sender of the email.

Show from properties

array(oneOf):

required

Not PII

The recipients of the email on the to line.

Show to properties

statusenum<string>

required

Not PII

The status of an Email. The status can be one of the following:

SCHEDULED The Email is scheduled to be sent by Twilio in the future.
QUEUED The Email is queued in Twilio for sending.
SENT The Email has been sent by Twilio.
DELIVERED The Email has been successfully delivered to the recipient.
UNDELIVERED The Email was successfully sent by Twilio but has not been delivered to the recipient.
OPENED The Email has been opened by the recipient.
FAILED The Email processing failed inside Twilio.
CANCELED The Email was canceled via API request.
INBOUND The Email was received by Twilio from an external source.

Possible values:

SCHEDULEDQUEUEDSENTDELIVEREDUNDELIVEREDOPENEDFAILEDCANCELEDINBOUND

relatedarray[RelatedResource]

required

Not PII

A list of resources that are associated with the Email.

Show related properties

tagsTags

required

Not PII

Custom metadata in the form of key-value pairs. Maximum size of a tag key is 128 characters. Maximum size of a tag value is 256 characters. There can be a maximum of 10 key-value pairs.

This field can be templated with Liquid. Specify variables with each recipient for personalization.

Max properties: 10

Show tags properties

scheduledForstring or null

required

Not PII

The scheduled send time of the Email. This field is only present if the Email was created with a schedule.

createdAtstring<date-time>

required

Not PII

The date and time when the Email was created.

updatedAtstring<date-time>

required

Not PII

The date and time when the Email was last updated.

deletedAtstring or null

required

Not PII

The date and time when the Email was deleted.

Send an Email

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

Creates and sends emails to the specified recipients. The API processes requests asynchronously and returns a 202 Accepted response with an operationId you can use to track send status.

The full request size must not exceed 5 MB.

Request body parameters

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

from

oneOf:

required

Not PII

The sending identity to associate with the Email.

Show from properties

array(oneOf):

required

Not PII

A list of recipients to send the email(s) to.

Min items: 1Max items: 10000

Show to properties

content

oneOf:

required

Not PII

The content of the Email.

Use the Liquid templating language for personalization in any text-based field.
When using a templated content, use the variables field on each recipient to specify the values to substitute.
For each variable you specify in your template, you should have a matching key in each recipient's variables object.
When targeting Profile recipients, you may specify variables with values that reference stored traits, on the Profile -- for example: ${Twilio.Profile.dateLastPurchase} ${Twilio.Profile.firstName} or ${Twilio.Profile.myCustomField}.

Show content properties

tagsTags

Optional

Not PII

Custom metadata in the form of key-value pairs. Maximum size of a tag key is 128 characters. Maximum size of a tag value is 256 characters. There can be a maximum of 10 key-value pairs.

This field can be templated with Liquid. Specify variables with each recipient for personalization.

Max properties: 10

Show tags properties

scheduleSchedule

Optional

Not PII

A schedule defines when a communication will be sent to a recipient.

Min properties: 1

Show schedule properties

ipPoolNamestring

Optional

Not PII

The name of the IP Pool to use for sending Emails.

If not specified, all dedicated IPs associated with your account will be considered for sending.

IP pools are only available to accounts with dedicated IPs.

This field can be templated with Liquid. Specify variables with each recipient for personalization.

Min length: 2Max length: 64

Send an Email

1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "TWILIO_ACCOUNT_SID",
6        authToken: "TWILIO_AUTH_TOKEN",
7    });
8    await client.emails.send({
9        from: {
10            address: "support@example.company.io",
11            name: "Cool Co Support",
12        },
13        to: [
14            {
15                address: "bob@example.com",
16                name: "Bob Smith",
17            },
18        ],
19        content: {
20            html: "<html><body>Hey, <br/><br/><b>Cake</b></body></html>",
21            text: "Hey, the cake is ready.",
22            subject: "Re: Wedding Cake",
23            attachments: [
24                {
25                    filename: "filename",
26                    contentType: "contentType",
27                    content: "content",
28                },
29            ],
30        },
31    });
32}
33main();

Fetch an Email

GET https://comms.twilio.com/v1/Emails/{emailId}

Retrieves a single Email based on its ID. Retains records for seven days after creation.

Path parameters

Property nameTypeRequiredPIIDescription

emailIdstring

required

Not PII

Example: comms_email_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_email_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

Fetch an Email

1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "TWILIO_ACCOUNT_SID",
6        authToken: "TWILIO_AUTH_TOKEN",
7    });
8    await client.emails.fetch("comms_email_01h9krwprkeee8fzqspvwy6nq8");
9}
10main();

List Emails

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

Returns a paginated list of Emails. Retains data for seven days after creation.

Query parameters

Property nameTypeRequiredPIIDescription

operationIdstring

Optional

Not PII

Filter to Emails created in a specific Operation.

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

startDatestring<date-time>

Optional

Not PII

Filter Emails created after the specified date and time.

endDatestring<date-time>

Optional

Not PII

Filter Emails created before the specified date and time.

statusenum<string>

Optional

Not PII

Filter Emails by Delivery Status.

Possible values:

SCHEDULEDQUEUEDSENTDELIVEREDUNDELIVEREDOPENEDFAILEDCANCELEDINBOUND

tagsstring

Optional

Not PII

Match emails by one or many tags. If more than one tag is specified in the query, the search will return emails that have all the tags. For Example: GET /Emails?tags=ageGroup:20s;industry:engineering;

Example: key_1:value;key_2:value;Pattern: ^(?:[a-zA-Z0-9._~-]+:[a-zA-Z0-9._~-]+;){1,10}$

pageTokenstring

Optional

Not PII

The token to retrieve the next page of results.

pageSizeinteger

Optional

Not PII

The number of resources to return in a page.

Default: 50Example: 50Minimum: 1Maximum: 1000

List Emails

1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "TWILIO_ACCOUNT_SID",
6        authToken: "TWILIO_AUTH_TOKEN",
7    });
8    await client.emails.list({
9        operationId: "comms_operation_01h9krwprkeee8fzqspvwy6nq8",
10        startDate: new Date("2024-01-15T09:30:00Z"),
11        endDate: new Date("2024-01-15T09:30:00Z"),
12        status: "SCHEDULED",
13        tags: "key_1:value;key_2:value;",
14        pageToken: "pageToken",
15        pageSize: 50,
16    });
17}
18main();