Send a Message to a Cohort

Before you begin, make sure you have:

1. Completed the Getting started guide, including a Twilio account, a compliant sender in your target region (note its senderId, which starts with comms_sender_), and API key credentials.
2. A Cohort in the same Twilio account you are authenticating as. Its ID starts with cmp_cohort_. To create one, see the Cohorts getting started guide.
3. Optional: any Profile traits you plan to reference in personalization, for example Contact.firstName.

Copy the ID of the Cohort you want to send to. It looks like this:

cmp_cohort_01h9krwprkeee8fzqspvwy6nq8

If you want a frozen audience instead of live membership, use a Cohort Snapshot ID (cmp_cohortsnapshot_...) and substitute cohortSnapshotId for cohortId in the requests below. The variables field, personalization behavior, and validation rules apply identically to cohortSnapshotId recipients. For a comparison of both options, see Cohorts.

Make a POST request to /v1/Messages. In the to array, include a single entry with your cohortId. Twilio expands that entry to every Profile in the Cohort at send time.

1
curl -X POST 'https://comms.twilio.com/v1/Messages' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "from": {
5
        "senderId": "comms_sender_01h9krwprkeee8fzqspvwy6nq8"
6
    },
7
    "to": [
8
        {
9
            "cohortId": "cmp_cohort_01h9krwprkeee8fzqspvwy6nq8",
10
            "variables": {
11
                "firstName": "${profile.trait.Contact.firstName}"
12
            }
13
        }
14
    ],
15
    "content": {
16
        "text": "Hello {{ firstName | default: '\''Valued Customer'\'' }}!"
17
    }
18
}' \
19
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

For each Profile in the Cohort, Twilio does the following:

1. Resolves ${profile.trait.Contact.firstName} from that Profile's traits.
2. Renders content.text with Liquid, replacing {{ firstName }} with the resolved value. If the trait is missing, the Liquid default filter falls back to Valued Customer.

A cohortId or cohortSnapshotId recipient must be the only entry in the to array. Mixing it with any other recipient, including another Cohort or Cohort Snapshot, returns 400. The 10,000-entry cap on to applies to array length, not to Cohort size — a Cohort can contain many more Profiles than that cap.

Twilio validates Cohort sends asynchronously, so check the Operation to confirm the outcome for each recipient.

1
curl -X GET 'https://comms.twilio.com/v1/Messages/Operations/comms_operation_01h9krwprkeee8fzqspvwy6nq8' \
2
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

For the full response schema and status semantics, see Operations and Message Tracking.

• 400 Bad Request on send: a synchronous personalization violation. Check that each ${...} expression is at most 500 characters, that no single variables value contains more than one ${...} expression, and that a recipient references at most 25 distinct expressions. See Limits and validation on the Cohorts page.
• Request succeeds (202) but the Operation reports failures: a semantic error in a Cohort expression, for example a trait path that doesn't exist on the target Profiles. Twilio does not retry failed recipients automatically, and there is no partial-retry endpoint. Fix the expression and issue a new send for the affected recipients.
• cohortId rejected: confirm the ID prefix is cmp_cohort_ and that the Cohort belongs to the same account you're authenticating as.

• Learn how to personalize message content with Liquid syntax, filters, and control flow.
• See Operations and Message Tracking to track the delivery status of your Cohort send.