Messages resource

A Message resource represents a message sent or received through the Twilio Bulk Messaging API. You can send messages to up to 10,000 recipients in a single API request across SMS, MMS, RCS, and WhatsApp channels.

When you send messages, the API responds with a 202 Accepted status code and an operationId header. Use the Operations resource to track the status of your request.

Message Properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

required

Not PII

A reference to a Message.

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

from

oneOf:

required

Not PII

The sender of the Message.

Show from properties

array(oneOf):

required

Not PII

The list of recipient(s) that the Message was directed to.

This list is always of size 1, except for Group Messaging usage, where the number of recipients plus the sender will match the group size.

Show to properties

statusenum<string>

required

Not PII

The status of a Message. The status can be one of the following:

SCHEDULED The Message is scheduled to be sent by Twilio in the future.
QUEUED The Message is queued in Twilio for sending.
SENT The Message has been sent by Twilio.
DELIVERED The Message has been successfully delivered to the recipient.
READ The Message has been read by the recipient.
UNDELIVERED The Message was successfully sent by Twilio but have not been delivered to the recipient.
FAILED The Message processing failed inside Twilio. Use GET /Messages/Operations/{operationId}/Errors for more details.
CANCELED The Message was canceled via API request.
GROUP The Message is part of a group communication. To get the status for each Recipient of the group communication, use the Receipts endpoint e.g. GET /Messages/comms_message_01h2xcejqtf2nbrexx3vqjhp41/Receipts
INBOUND The Message was received by Twilio from an external source.

Possible values:

QUEUEDSENTSCHEDULEDDELIVEREDREADFAILEDUNDELIVEREDCANCELEDGROUPINBOUND

relatedarray[RelatedResource]

required

Not PII

A list of resources that are associated with the Message.

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

createdAtstring<date-time>

required

Not PII

The date and time when the entity was created.

updatedAtstring<date-time>

required

Not PII

The date and time when the entity was last updated.

scheduledForstring or null

required

Not PII

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

Send Messages

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

Create and send messages to the specified recipients.

The API responds with a 202 Accepted status code and an empty response body. The response headers include an operationId, which you can use to check the status of your request with the Operations resource.

Request body parameters

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

array(oneOf):

required

Not PII

An array of recipient objects to send the Message(s) to.

Min items: 1Max items: 10000

Show to properties

content

oneOf:

required

Not PII

The content of the Message.

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 Audience or Profile recipients, you may specify variables with values that reference stored traits on the Profile -- for example: ${Twilio.Profile.firstName} or ${Twilio.Profile.myCustomField}.

Show content properties

from

oneOf:

Optional

Not PII

The sending identity to associate with the Message(s).

Show from properties

scheduleSchedule

Optional

Not PII

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

Min properties: 1

Show schedule 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

Responses

202400429500503

The request was accepted and an Operation was created to track its progress. The response body contains the ID and link to the Operation resource.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

operationIdstring

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}

operationLocationstring<uri>

Optional

The location (uri) of the Operation resource identified by operationId.

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

Send a basic SMS

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.send({
9        to: [
10            {
11                address: "+12065558844",
12                channel: "PHONE",
13            },
14        ],
15        content: {
16            text: "Hello, World!",
17        },
18        from: {
19            address: "+14153901002",
20            channel: "SMS",
21        },
22    });
23}
24main();

Fetch a Message

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

Retrieve a Message by its identifier. The response includes full details about the sender, recipients, delivery status, message content, and all delivery attempts.

Path parameters

Property nameTypeRequiredPIIDescription

messageIdstring

required

Not PII

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

Responses

200400404429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

A reference to a Message.

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

from

oneOf:

Optional

The sender of the Message.

Show from properties

array(oneOf):

Optional

The list of recipient(s) that the Message was directed to.

This list is always of size 1, except for Group Messaging usage, where the number of recipients plus the sender will match the group size.

Show to properties

statusenum<string>

Optional

The status of a Message. The status can be one of the following:

SCHEDULED The Message is scheduled to be sent by Twilio in the future.
QUEUED The Message is queued in Twilio for sending.
SENT The Message has been sent by Twilio.
DELIVERED The Message has been successfully delivered to the recipient.
READ The Message has been read by the recipient.
UNDELIVERED The Message was successfully sent by Twilio but have not been delivered to the recipient.
FAILED The Message processing failed inside Twilio. Use GET /Messages/Operations/{operationId}/Errors for more details.
CANCELED The Message was canceled via API request.
GROUP The Message is part of a group communication. To get the status for each Recipient of the group communication, use the Receipts endpoint e.g. GET /Messages/comms_message_01h2xcejqtf2nbrexx3vqjhp41/Receipts
INBOUND The Message was received by Twilio from an external source.

Possible values:

QUEUEDSENTSCHEDULEDDELIVEREDREADFAILEDUNDELIVEREDCANCELEDGROUPINBOUND

relatedarray[RelatedResource]

Optional

A list of resources that are associated with the Message.

Show related properties

tagsTags

Optional

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

createdAtstring<date-time>

Optional

The date and time when the entity was created.

updatedAtstring<date-time>

Optional

The date and time when the entity was last updated.

scheduledForstring or null

Optional

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

content

oneOf:

Optional

The resolved content of the Message.

Show content properties

attemptsarray[MessageAttempt]

Optional

The list of attempts Twilio executed to process the Message.

Show attempts properties

Property nameTypeRequiredDescriptionChild properties

fromMessageSender

Optional

A Message Sender is a person or entity whose communication identity is hosted by Twilio.

Show from properties

array(oneOf):

Optional

The recipients of the Message Attempt. This array will contain a single recipient element, except for GMMS use case, where there are multiple recipients.

Show to properties

statusenum<string>

Optional

The status of a Message. The status can be one of the following:

SCHEDULED The Message is scheduled to be sent by Twilio in the future.
QUEUED The Message is queued in Twilio for sending.
SENT The Message has been sent by Twilio.
DELIVERED The Message has been successfully delivered to the recipient.
READ The Message has been read by the recipient.
UNDELIVERED The Message was successfully sent by Twilio but have not been delivered to the recipient.
FAILED The Message processing failed inside Twilio. Use GET /Messages/Operations/{operationId}/Errors for more details.
CANCELED The Message was canceled via API request.
GROUP The Message is part of a group communication. To get the status for each Recipient of the group communication, use the Receipts endpoint e.g. GET /Messages/comms_message_01h2xcejqtf2nbrexx3vqjhp41/Receipts
INBOUND The Message was received by Twilio from an external source.

Possible values:

QUEUEDSENTSCHEDULEDDELIVEREDREADFAILEDUNDELIVEREDCANCELEDGROUPINBOUND

attemptedAtstring<date-time>

Optional

The date and time when the Message Attempt began processing.

infoUrlstring<uri>

Optional

A URL to view more information for this Message Attempt.

errorobject or null

Optional

An error object that describes an error that occurred during the Message Attempt. This field will be null if the attempt was successful.

Example:

{"code":21614,"message":"The address specified in the request is not a valid phone number.","infoUrl":"/docs/api/errors/21614","context":"$.from[0].address"}

Show error 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 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

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

List Messages

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

Retrieve a list of Messages. Use query parameters to filter results by operation, channel, status, date range, and more.

Query parameters

Property nameTypeRequiredPIIDescription

operationIdstring

Optional

Not PII

Filter Messages by Operation ID.

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

sessionIdstring

Optional

Not PII

Filter Messages by Session ID.

Example: comms_session_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_session_[a-hjkmnpqrstv-z0-9]{26,34}

startDatestring<date-time>

Optional

Not PII

Filter to Messages created after the specified date and time in ISO 8601 format. The date is in RFC3339 format. (e.g., 2025-06-18T12:00:00Z)

endDatestring<date-time>

Optional

Not PII

Filter to Messages created before the specified date and time in ISO 8601 format. The date is in RFC3339 format and must be greater than startDate if provided. (e.g., 2025-06-18T12:00:00Z)

profilestring

Optional

Not PII

Filter Messages sent or received by Profile ID.

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

channelenum<string>

Optional

Not PII

Filter Messages by channel.

Example: SMSPossible values:

SMSRCSWHATSAPP

statusenum<string>

Optional

Not PII

Filter Messages by Delivery Status.

Possible values:

QUEUEDSENTSCHEDULEDDELIVEREDREADFAILEDUNDELIVEREDCANCELEDGROUPINBOUND

tagsstring

Optional

Not PII

Match messages by one or many tags. If more than one tag is specified in the query, the search will return messages that have all the tags. For Example: GET /Messages?tags=region:EMEA;campaign:BUY_STUFF;

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

Responses

200400429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

messagesarray[MessageMetadata]

Optional

A list of Messages.

Show messages properties

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

A reference to a Message.

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

from

oneOf:

Optional

The sender of the Message.

Show from properties

array(oneOf):

Optional

The list of recipient(s) that the Message was directed to.

This list is always of size 1, except for Group Messaging usage, where the number of recipients plus the sender will match the group size.

Show to properties

statusenum<string>

Optional

The status of a Message. The status can be one of the following:

SCHEDULED The Message is scheduled to be sent by Twilio in the future.
QUEUED The Message is queued in Twilio for sending.
SENT The Message has been sent by Twilio.
DELIVERED The Message has been successfully delivered to the recipient.
READ The Message has been read by the recipient.
UNDELIVERED The Message was successfully sent by Twilio but have not been delivered to the recipient.
FAILED The Message processing failed inside Twilio. Use GET /Messages/Operations/{operationId}/Errors for more details.
CANCELED The Message was canceled via API request.
GROUP The Message is part of a group communication. To get the status for each Recipient of the group communication, use the Receipts endpoint e.g. GET /Messages/comms_message_01h2xcejqtf2nbrexx3vqjhp41/Receipts
INBOUND The Message was received by Twilio from an external source.

Possible values:

QUEUEDSENTSCHEDULEDDELIVEREDREADFAILEDUNDELIVEREDCANCELEDGROUPINBOUND

relatedarray[RelatedResource]

Optional

A list of resources that are associated with the Message.

Show related properties

tagsTags

Optional

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

createdAtstring<date-time>

Optional

The date and time when the entity was created.

updatedAtstring<date-time>

Optional

The date and time when the entity was last updated.

scheduledForstring or null

Optional

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

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

Select from available examples

{
  "messages": [
    {
      "id": "comms_message_01h2xcejqtf2nbrexx3vqjhp41",
      "from": {
        "address": "+12065558844",
        "channel": "SMS",
        "senderId": "comms_sender_01h9krwprkeee8fzqspvwy6nq8",
        "senderPoolId": "comms_senderpool_01h9krwprkeee8fzqspvwy6nq8"
      },
      "to": [
        {
          "address": "+14153901002",
          "channel": "PHONE",
          "profileId": "mem_profile_01h9krwprkeee8fzqspvwy6nq7",
          "memoryStoreId": "mem_store_00000000000000000000000000"
        }
      ],
      "status": "SENT",
      "related": [
        {
          "name": "OPERATION",
          "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
          "uri": "https://comms.twilio.com/v1/Messages/Operations/comms_operation_01h2xcejqtf2nbrexx3vqjhp41"
        }
      ],
      "tags": {},
      "scheduledFor": null,
      "createdAt": "2023-08-24T14:15:22Z",
      "updatedAt": "2023-08-24T14:15:22Z",
      "deletedAt": null
    },
    {
      "id": "comms_message_01h2xcejqtf2nbrexx3vqjhp41",
      "from": {
        "address": "+12065558844",
        "channel": "WHATSAPP",
        "senderId": "comms_sender_01h9krwprkeee8fzqspvwy6nq8"
      },
      "to": [
        {
          "address": "+14153901002",
          "channel": "PHONE",
          "profileId": "mem_profile_01h9krwprkeee8fzqspvwy6nq7",
          "memoryStoreId": "mem_store_00000000000000000000000000"
        }
      ],
      "status": "SENT",
      "related": [
        {
          "name": "OPERATION",
          "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
          "uri": "https://comms.twilio.com/v1/Messages/Operations/comms_operation_01h2xcejqtf2nbrexx3vqjhp41"
        }
      ],
      "tags": {},
      "scheduledFor": null,
      "createdAt": "2023-08-24T14:15:22Z",
      "updatedAt": "2023-08-24T14:15:22Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "next": null,
    "self": "eyJTSyI6IkEjMDFqbmVoYm5xYWZmNDlrazUxZHA1bmN5bXciLCJTSzEiOiJBI2FjdGl2YXRlZCMyMDI1LTAzLTAzVDE3OjM3OjQ3WiMwMWpuZWhibnFhZmY0OWtrNTFkcDVuY3ltdyIsIlBLIjoiQyNBQzYwMzg4ODJiZDY5ZWIyNGM4YzU4ZGI5NjE4NjE3OTE4I0EifQ=="
  }
}

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 all Messages

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.list({
9        operationId: "comms_operation_01h9krwprkeee8fzqspvwy6nq8",
10        sessionId: "comms_session_01h9krwprkeee8fzqspvwy6nq8",
11        startDate: new Date("2024-01-15T09:30:00Z"),
12        endDate: new Date("2024-01-15T09:30:00Z"),
13        profile: "mem_profile_01h9krwprkeee8fzqspvwy6nq8",
14        channel: "SMS",
15        status: "QUEUED",
16        tags: "key_1:value;key_2:value;",
17        pageToken: "pageToken",
18        pageSize: 50,
19    });
20}
21main();