Using Cohorts with Bulk Messaging and Email

Overview

Twilio Cohorts defines the audience you want to target. Other Twilio products, such as the Bulk Messaging API and the Email API, use that definition to determine which recipients to reach.

There are two common patterns for combining Cohorts with the Bulk Messaging API and the Email API. Choose a pattern based on whether you need the most recent data at send time or a fixed list that you can review in advance.

Pattern 1: Referenced cohort (latest data at send time)

In this pattern, you pass a saved cohortId directly to the Bulk Messaging API or Email API when you trigger a send.

When the send executes, the messaging or email engine generates its own snapshot. This approach guarantees that your message reaches the profiles that match your targeting criteria at the precise moment of send.

Bulk Messaging API example

Include a cohortId property in an object inside the to array:

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "<Your Purchased Twilio Phone Number>",
6        "channel": "SMS"
7    },
8    "to": [
9        {
10            "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
11        }
12    ],
13    "content": {
14        "text": "Thanks for being a customer!"
15    }
16}' \
17-u $TWILIO_API_KEY:$TWILIO_API_SECRET

(information)

Info

Check the Bulk Messaging API reference for the exact request parameters accepted for cohort-based sends.

Email API example

Include a cohortId property in an object inside the to array:

1curl -X POST 'https://comms.twilio.com/preview/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r"
11        }
12    ],
13    "content": {
14        "subject": "Thanks for being a customer!",
15        "html": "<p>Thanks for being a customer!</p>",
16        "text": "Thanks for being a customer!"
17    }
18}' \
19-u $TWILIO_API_KEY:$TWILIO_API_SECRET

(information)

Info

Check the Twilio Email API reference for the exact request parameters accepted for cohort-based sends.

Use this pattern for recurring campaigns or any scenario in which each send must reflect the current state of your customer data.

Pattern 2: Referenced snapshot (immutable list)

In this pattern, you generate a snapshot first, wait for the evaluation to complete, optionally review or audit the population, and then pass the resulting cohortSnapshotId to the messaging or email API.

Because a snapshot is immutable, the messaging or email engine delivers only to the profiles captured when the snapshot was generated, regardless of any profile changes that occur afterward.

Bulk Messaging API example

Include a cohortSnapshotId property in an object inside the to array:

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "<Your Purchased Twilio Phone Number>",
6        "channel": "SMS"
7    },
8    "to": [
9        {
10            "cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r"
11        }
12    ],
13    "content": {
14        "text": "Thanks for being a customer!"
15    }
16}' \
17-u $TWILIO_API_KEY:$TWILIO_API_SECRET

(information)

Info

Check the Bulk Messaging API reference for the exact request parameters accepted for cohort-based sends.

Email API example

Include a cohortSnapshotId property in an object inside the to array:

1curl -X POST 'https://comms.twilio.com/preview/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "cohortSnapshotId": "cmp_cohortsnapshot_01h9d8r0vte3hz8tykdj329t7r"
11        }
12    ],
13    "content": {
14        "subject": "Thanks for being a customer!",
15        "html": "<p>Thanks for being a customer!</p>",
16        "text": "Thanks for being a customer!"
17    }
18}' \
19-u $TWILIO_API_KEY:$TWILIO_API_SECRET

(information)

Info

Check the Twilio Email API reference for the exact request parameters accepted for cohort-based sends.

Use this pattern when you need to review the exact list of profiles before sending or when you plan to send at a later time than when the cohort was generated.

Personalizing sends with profile data

When you send a message to a fixed list of recipients, you supply personalization variables as literal values for each entry in your recipient payload. When you target a cohort using cohortId or cohortSnapshotId, there is no predefined recipient list. Twilio evaluates which profiles match and resolves their trait data at runtime.

To personalize a cohort-based send, define your variables by using Common Expression Language (CEL) syntax wrapped in ${} rather than literal values. Twilio evaluates each expression against the matching profile and substitutes the result into your message content. Reference variables in the content by using the same Liquid syntax ({{ }}) that you use for any other personalized send.

1curl -X POST 'https://comms.twilio.com/preview/Messages' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "<Your Purchased Twilio Phone Number>",
6        "channel": "SMS"
7    },
8    "to": [
9        {
10            "cohortId": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r",
11            "variables": {
12                "firstName": "${profile.trait.Contact.firstName}",
13                "netRevenue": "${profile.trait.Metrics.revenue - profile.trait.Metrics.refunds}"
14            }
15        }
16    ],
17    "content": {
18        "text": "Hi {{ firstName | default: '\''there'\'' }}! Your net spend with us is {{ netRevenue }}."
19    }
20}' \
21-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Next steps

Learn about Cohorts and Snapshots.
Review the Bulk Messaging getting started guide for details on sending messages.
Review the Email API getting started guide for details on sending email.