Senders resource

A Sender resource represents a messaging sender identity available for use with the Bulk Messaging API. Use the Senders resource to list, fetch, resolve, and search your available senders.

Sender Properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

required

Not PII

A reference to a Sender.

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

displayNamestring or null

required

Not PII

The name associated with the address inventory, such as phone number or email address.

This name might be visible to recipients in certain communications, such as Email, and helps identify the sender.

Note: To update this value, use the appropriate Twilio API for the inventory type. For example, for Senders with the channel email, update displayName using the EmailSenders API.

addressstring

required

Not PII

The Sender’s communication address within a channel, such as a phone number, email address, or device token.

channelenum<string>

required

Not PII

The medium which a unit of communication is transmitted through. These are differentiated by a mix of transmission protocol, network controller/owner, endpoint and address model, as well as the model for content of the atomic unit of communication itself.

Possible values:

SMSRCSEMAILWHATSAPPPUSH

statusenum<string>

required

Not PII

The status of a Sender. If a Sender is activated, it is available to send and receive communications. If a Sender is deactivated, it is not available to send or receive communications.

Possible values:

ACTIVATEDDEACTIVATED

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

updatedAtstring<date-time>

required

Not PII

createdAtstring<date-time>

required

Not PII

Fetch a Sender

GET https://comms.twilio.com/v1/Senders/{senderId}

Retrieve a Sender by its ID.

Path parameters

Property nameTypeRequiredPIIDescription

senderIdstring

required

Not PII

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

Responses

200400404409429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

A reference to a Sender.

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

displayNamestring or null

Optional

The name associated with the address inventory, such as phone number or email address.

This name might be visible to recipients in certain communications, such as Email, and helps identify the sender.

Note: To update this value, use the appropriate Twilio API for the inventory type. For example, for Senders with the channel email, update displayName using the EmailSenders API.

addressstring

Optional

The Sender’s communication address within a channel, such as a phone number, email address, or device token.

channelenum<string>

Optional

Possible values:

SMSRCSEMAILWHATSAPPPUSH

statusenum<string>

Optional

The status of a Sender. If a Sender is activated, it is available to send and receive communications. If a Sender is deactivated, it is not available to send or receive communications.

Possible values:

ACTIVATEDDEACTIVATED

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

updatedAtstring<date-time>

Optional

createdAtstring<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 a request conflict with the current state of the target resource. 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 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 Sender

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

List Senders

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

Retrieve a list of all Senders available for messaging.

Query parameters

Property nameTypeRequiredPIIDescription

channelenum<string>

Optional

Not PII

Filter to Senders that match a specific channel.

Possible values:

SMSRCSEMAILWHATSAPPPUSH

statusenum<string>

Optional

Not PII

Filter to Senders with the specified status.

Possible values:

ACTIVATEDDEACTIVATED

startDatestring<date-time>

Optional

Not PII

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

endDatestring<date-time>

Optional

Not PII

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

pageTokenstring

Optional

Not PII

A page token that represents the start sender of a page

pageSizeinteger

Optional

Not PII

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

Responses

200400409429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

sendersarray

Optional

A list of Senders

Show senders properties

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 a request conflict with the current state of the target resource. 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 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 Senders

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