Operations and Email Tracking

What is an Operation?

An Operation represents a single API request to the v1/Emails endpoint. When you submit a send request, the Email API validates the input and returns an HTTP 202 Accepted response that includes an operationId and operationLocation. To monitor the status and progress of the Operation, use these values.

As Twilio Email processes the Operation, it generates an Email resource for each recipient in the to array. Each Email progresses through its own set of statuses as it moves from submission to delivery.

Retrieve an Operation

To retrieve its status and delivery statistics, make a GET request with the Operation ID.

1curl -X GET 'https://comms.twilio.com/v1/Emails/Operations/{operationId}' \
2-H 'Content-Type: application/json' \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Sample response

1{
2    "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
3    "status": "COMPLETED",
4    "stats": {
5        "total": 2,
6        "queued": 0,
7        "sent": 0,
8        "scheduled": 0,
9        "delivered": 2,
10        "opened": 0,
11        "undelivered": 0,
12        "failed": 0,
13        "canceled": 0
14    },
15    "createdAt": "2026-04-05T06:20:00Z",
16    "updatedAt": "2026-04-05T06:20:05Z"
17}

See the Email Operation API reference.

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.

Retrieve the Emails created by an Operation

To retrieve all Email resources that an Operation created, use the List Emails endpoint with the operationId query parameter.

1curl -X GET 'https://comms.twilio.com/v1/Emails?operationId={operationId}' \
2-H 'Content-Type: application/json' \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Sample response

1{
2    "data": [
3        {
4            "id": "comms_email_01h2xcejqtf2nbrexx3vqjhp41",
5            "from": {
6                "address": "support@example.com",
7                "name": "Support Team"
8            },
9            "to": {
10                "address": "john.doe@example.com",
11                "name": "John Doe"
12            },
13            "content": {
14                "subject": "Your subject line",
15                "html": "<p>Your message content.</p>",
16                "text": "Your message content."
17            },
18            "status": "DELIVERED",
19            "tags": {},
20            "operationId": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
21            "createdAt": "2026-04-05T06:20:00Z",
22            "updatedAt": "2026-04-05T06:20:05Z"
23        }
24    ],
25    "pagination": {
26        "nextPageToken": null,
27        "pageSize": 50
28    }
29}

To learn more about this resource, see the List Emails API reference.

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.

Track emails with tags

You can add custom metadata tags to your emails for filtering and tracking. When listing emails, filter by tags using the query string format: ?tags=key1:value1;key2:value2;.

1curl -X GET 'https://comms.twilio.com/v1/Emails?tags=campaign:monthlyNewsletter;' \
2-H 'Content-Type: application/json' \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

To learn more about tag constraints, see Tags.

Next steps

See the Personalization guide to learn how to personalize emails for each recipient.