Operations resource

Operations represents an asynchronous request that creates one or more resources, such as sending a message to multiple recipients. When you submit a Send Messages request, the API returns an operationId that you can use to monitor the status and progress of the operation.

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

statsMessageOperationStats

required

Not PII

Represents the stats of a sending operation of one or many communications resources, such as Messages and Emails.

total is the total number of Messages in the Operation.
- To get the status for each individual Message, fetch the resource with: GET /Messages/{messageId}.
- For group communications, where there is more than one recipient per communication resource use Receipts e.g. GET /Messages/{messageId}/Receipts.
recipients is the total number of recipients targeted in an Operation.
attempts is the total number of sending attempts made by Twilio.
unaddressable is the number of recipients to which no sending attempts were made because a valid match could not be found between the available addresses for the recipient (to) and sender (from).
scheduled is the number of Messages that are scheduled to be sent by Twilio in the future.
queued is the number of Messages that are queued in Twilio for sending.
sent is the number of Messages that have been sent by Twilio.
delivered is the number of Messages that have been successfully delivered to recipients.
read is the number of Messages that have been read by recipients.
undelivered is the number of Messages that were successfully sent by Twilio but have not been delivered to the recipient.
failed is the number of Messages that failed during processing by Twilio. Get Errors with GET /Messages/Operations/{operationId}/Errors fore more detail.
canceled is the number of Messages that were canceled via API request.

Example:

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

Show stats properties

createdAtstring<date-time>

required

Not PII

updatedAtstring<date-time>

required

Not PII

Fetch a Message Operation

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

Retrieve an Operation by its ID, including its current status and aggregate delivery statistics.

Path parameters

Property nameTypeRequiredPIIDescription

operationIdstring

required

Not PII

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

Responses

200400404429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

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>

Optional

The status of an Operation.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

statsMessageOperationStats

Optional

Represents the stats of a sending operation of one or many communications resources, such as Messages and Emails.

total is the total number of Messages in the Operation.
- To get the status for each individual Message, fetch the resource with: GET /Messages/{messageId}.
- For group communications, where there is more than one recipient per communication resource use Receipts e.g. GET /Messages/{messageId}/Receipts.
recipients is the total number of recipients targeted in an Operation.
attempts is the total number of sending attempts made by Twilio.
unaddressable is the number of recipients to which no sending attempts were made because a valid match could not be found between the available addresses for the recipient (to) and sender (from).
scheduled is the number of Messages that are scheduled to be sent by Twilio in the future.
queued is the number of Messages that are queued in Twilio for sending.
sent is the number of Messages that have been sent by Twilio.
delivered is the number of Messages that have been successfully delivered to recipients.
read is the number of Messages that have been read by recipients.
undelivered is the number of Messages that were successfully sent by Twilio but have not been delivered to the recipient.
failed is the number of Messages that failed during processing by Twilio. Get Errors with GET /Messages/Operations/{operationId}/Errors fore more detail.
canceled is the number of Messages that were canceled via API request.

Example:

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

Show stats properties

createdAtstring<date-time>

Optional

updatedAtstring<date-time>

Optional

This error indicates that the request content was malformed or ambiguous.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the requested resource was not found.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is experiencing server-side issues. The request should not be retried.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is temporarily unavailable. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

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

List Message Operations

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

Retrieve a list of Operations. Use query parameters to filter results by status and date range.

Query parameters

Property nameTypeRequiredPIIDescription

startDatestring<date-time>

Optional

Not PII

Filter to Operations created after the specified date and time in ISO 8601 format.

endDatestring<date-time>

Optional

Not PII

Filter to Operations created before the specified date and time in ISO 8601 format.

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

Responses

200400429500503

Schema

Property nameTypeRequiredDescriptionChild properties

operationsarray[MessageOperation]

Optional

A list of Message Operations.

Show operations properties

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

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>

Optional

The status of an Operation.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

statsMessageOperationStats

Optional

Represents the stats of a sending operation of one or many communications resources, such as Messages and Emails.

total is the total number of Messages in the Operation.
- To get the status for each individual Message, fetch the resource with: GET /Messages/{messageId}.
- For group communications, where there is more than one recipient per communication resource use Receipts e.g. GET /Messages/{messageId}/Receipts.
recipients is the total number of recipients targeted in an Operation.
attempts is the total number of sending attempts made by Twilio.
unaddressable is the number of recipients to which no sending attempts were made because a valid match could not be found between the available addresses for the recipient (to) and sender (from).
scheduled is the number of Messages that are scheduled to be sent by Twilio in the future.
queued is the number of Messages that are queued in Twilio for sending.
sent is the number of Messages that have been sent by Twilio.
delivered is the number of Messages that have been successfully delivered to recipients.
read is the number of Messages that have been read by recipients.
undelivered is the number of Messages that were successfully sent by Twilio but have not been delivered to the recipient.
failed is the number of Messages that failed during processing by Twilio. Get Errors with GET /Messages/Operations/{operationId}/Errors fore more detail.
canceled is the number of Messages that were canceled via API request.

Example:

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

Show stats properties

createdAtstring<date-time>

Optional

updatedAtstring<date-time>

Optional

paginationPaginationMetadata

Optional

Metadata for paginated results. This object contains two tokens to navigate through paginated results.

Use next to retrieve the 'next' page in the result list.
Use self to retrieve the same page of the result list again.
Supply the token in the pageToken query param.

Show pagination properties

This error indicates that the request content was malformed or ambiguous.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is experiencing server-side issues. The request should not be retried.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is temporarily unavailable. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

List Message 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.messages.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();