Email Operation Resource

An Email Operation represents a batch of emails created in a single send request. Use this resource to track the overall status and delivery statistics of your email sends.

When you send an email, the API returns an operationId that correlates all email resources created in that request. Use the Operation resource to monitor delivery progress and retrieve aggregate statistics.

Data retention is limited to 7 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

Operation Properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

required

Not PII

The Operation ID is an identifier that can be used to correlate all of the resources created in a request.

Issue a GET request to the resource list location, using the Operation ID as a query parameter to retrieve the resources that correlate with the Operation.

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

statusenum<string>

required

Not PII

The status of an Operation.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

statsEmailOperationStats

required

Not PII

Represents the stats of a sending operation of one or many Emails.

total is the total number of Email resources created in the Operation.
- To get the status for each individual Email, fetch the Email resource: GET /Email/{emailId}.
- For Emails with multiple recipients, use Receipts e.g. GET /Emails/{emailId}/Receipts.
recipients is the total number of recipients targeted in an Operation.
attempts is the total number of sending attempts made by Twilio.
scheduled is the number of Emails that are scheduled to be sent by Twilio in the future.
queued is the number of Emails that are queued in Twilio for sending.
sent is the number of Emails that have been sent by Twilio.
delivered is the number of Emails that have been successfully delivered to recipients.
opened is the number of Emails that have been opened by unique recipients.
undelivered is the number of Emails that were successfully sent by Twilio but have not been delivered to the recipient.
failed is the number of Emails that failed during processing by Twilio. Get Errors with GET /Emails/Operations/{operationId}/Errors fore more detail.
canceled is the number of Emails that were canceled via API request.

Example:

{"total":1,"recipients":1,"attempts":1,"queued":0,"sent":0,"scheduled":0,"delivered":0,"opened":0,"undelivered":0,"failed":0,"canceled":0}

Show stats properties

createdAtstring<date-time>

required

Not PII

updatedAtstring<date-time>

required

Not PII

Fetch an Email Operation

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

Retrieves a single Email Operation by its ID. Records are available for 7 days after creation.

Path parameters

Property nameTypeRequiredPIIDescription

operationIdstring

required

Not PII

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

Fetch an Email Operation

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.fetchOperation("comms_operation_01h9krwprkeee8fzqspvwy6nq8");
9}
10main();

List Email Operations

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

Returns a paginated list of Email Operations. Data retention is limited to 7 days after creation.

Query parameters

Property nameTypeRequiredPIIDescription

startDatestring<date-time>

Optional

Not PII

Filter to Operations created after the specified date and time.

endDatestring<date-time>

Optional

Not PII

Filter to Operations created before the specified date and time.

statusenum<string>

Optional

Not PII

Filter to Operations with the specified status.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

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 Email Operations

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.listOperations({
9        startDate: new Date("2024-01-15T09:30:00Z"),
10        endDate: new Date("2024-01-15T09:30:00Z"),
11        status: "SCHEDULED",
12        pageToken: "pageToken",
13        pageSize: 50,
14    });
15}
16main();