Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

SenderPool Senders resource

The Senders in a SenderPool subresource lets you manage which senders are assigned to a specific SenderPool. You can list, add, and remove senders from a pool.

Sender Properties

sender-properties page anchor
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(link takes you to an external page). Specify variables with each recipient for personalization.

Max properties: 10
updatedAtstring<date-time>
required
Not PII
createdAtstring<date-time>
required
Not PII

Add Senders to a SenderPool

add-senders-to-a-senderpool page anchor

POST https://comms.twilio.com/v1/SenderPools/{senderPoolId}/Senders

Add one or more Senders to a SenderPool.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
senderPoolIdstring
required
Not PII
Example: comms_senderpool_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_senderpool_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
SchemaExample

Array of:

Property nameTypeRequiredPIIDescriptionChild properties
senderIdstring
required
Not PII

A reference to a Sender.

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

Responses

responses page anchor
202400404409429500503

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.

Add Senders to a SenderPoolLink to code sample: Add Senders to a SenderPool
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "TWILIO_ACCOUNT_SID",

6
        authToken: "TWILIO_AUTH_TOKEN",

7
    });

8
    await client.senderPools.addSender("comms_senderpool_01h9krwprkeee8fzqspvwy6nq8", [

9
        {

10
            senderId: "comms_sender_01h9krwprkeee8fzqspvwy6nq8",

11
        },

12
    ]);

13
}

14
main();

List Senders in a SenderPool

list-senders-in-a-senderpool page anchor

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

Retrieve a list of Senders assigned to a specific SenderPool.

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
senderPoolIdstring
required
Not PII
Example: comms_senderpool_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_senderpool_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

Query parameters

query-parameters page anchor
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

responses-1 page anchor
200400404409429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
sendersarray

Optional

A list of Senders that belong to the SenderPool.

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.
List Senders in a SenderPoolLink to code sample: List Senders in a SenderPool
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "TWILIO_ACCOUNT_SID",

6
        authToken: "TWILIO_AUTH_TOKEN",

7
    });

8
    await client.senderPools.listSenders("comms_senderpool_01h9krwprkeee8fzqspvwy6nq8", {

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
}

17
main();

Remove a Sender from a SenderPool

remove-a-sender-from-a-senderpool page anchor

DELETE https://comms.twilio.com/v1/SenderPools/{senderPoolId}/Senders/{senderId}

Remove a specific Sender from a SenderPool.

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
senderPoolIdstring
required
Not PII
Example: comms_senderpool_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_senderpool_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
senderIdstring
required
Not PII
Example: comms_sender_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_sender_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

Responses

responses-2 page anchor
202400404409429500503

The request was accepted and a resource ID is available to check the result. The response body contains the resource ID and link to the resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resourceIdstring

Optional

The Resource ID is an identifier for the resource that was created or updated in response to the request.

resourceLocationstring<uri>

Optional

The location (uri) of the resource identified by Resource-Id.

Remove a Sender from a SenderPoolLink to code sample: Remove a Sender from a SenderPool
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "TWILIO_ACCOUNT_SID",

6
        authToken: "TWILIO_AUTH_TOKEN",

7
    });

8
    await client.senderPools.removeSender("comms_senderpool_01h9krwprkeee8fzqspvwy6nq8", "comms_sender_01h9krwprkeee8fzqspvwy6nq8");

9
}

10
main();