Tags

A Tag is a key-value pair. You define both the key and the value. Twilio doesn't reserve or require any specific keys, so you can use whatever keys make sense for your business.

1
{
2
    "tags": {
3
        "campaign": "summer_sale",
4
        "region": "EMEA"
5
    }
6
}

Tags are metadata only. They don't affect delivery, sender selection, or content rendering. They help you organize, correlate, and retrieve resources.

The same constraints apply to Tags on every resource that supports them.

Keys and values that include spaces or other characters outside the allowed set are rejected. There's no fixed list of keys: you choose your own keys on each request.

To attach Tags, include a tags object in your request body. The following request sends a Message and labels it with a campaign and region.

1
curl -X POST 'https://comms.twilio.com/v1/Messages' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "from": {
5
        "address": "<Your Purchased Twilio Phone Number>",
6
        "channel": "SMS"
7
    },
8
    "to": [
9
        {
10
            "address": "+15558675310",
11
            "channel": "PHONE"
12
        }
13
    ],
14
    "content": {
15
        "text": "Hello, World!"
16
    },
17
    "tags": {
18
        "campaign": "summer_sale",
19
        "region": "EMEA"
20
    }
21
}' \
22
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

You add Tags to other resources the same way. For example, this request creates a Sender Pool with a region Tag.

1
curl -X POST 'https://comms.twilio.com/v1/SenderPools' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "name": "Sales Leads - APAC",
5
    "tags": {
6
        "region": "APAC"
7
    }
8
}' \
9
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

When you retrieve a resource, its Tags are returned in the tags field. A resource with no Tags returns an empty object ("tags": {}).

The tags field supports the Liquid templating language, so you can set a different tag value for each recipient in a single bulk request. Reference a variable in the tag value with double curly braces, then provide the matching value in each recipient's variables object.

1
curl -X POST 'https://comms.twilio.com/v1/Messages' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "from": {
5
        "address": "<Your Purchased Twilio Phone Number>",
6
        "channel": "SMS"
7
    },
8
    "to": [
9
        {
10
            "address": "+15558675310",
11
            "channel": "PHONE",
12
            "variables": {
13
                "tier": "gold"
14
            }
15
        },
16
        {
17
            "address": "+15558675311",
18
            "channel": "PHONE",
19
            "variables": {
20
                "tier": "silver"
21
            }
22
        }
23
    ],
24
    "content": {
25
        "text": "Thanks for being a customer!"
26
    },
27
    "tags": {
28
        "campaign": "loyalty_2026",
29
        "tier": "{{tier | default: 'bronze'}}"
30
    }
31
}' \
32
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

In this request, every Message shares the campaign Tag, while the tier Tag resolves to each recipient's own value. Use Liquid's default filter ({{tier | default: 'bronze'}}) to supply a fallback value for any variable that might be missing, so the Tag still resolves. The same personalization rules apply here as in message Personalization.

You don't tag inbound messages directly. Instead, an inbound message automatically inherits the Tags from the previous outbound message sent to the same contact. When a recipient replies, the reply carries the same Tags you set on the Message you sent them.

This keeps a conversation's inbound and outbound Messages associated under the same labels. If you tag an outbound campaign Message with campaign: summer_sale, the recipient's reply carries campaign: summer_sale as well, so you can filter on that value to retrieve both halves of the exchange.

Search and list endpoints accept a tags query parameter so you can retrieve only the resources that carry specific Tags. Format the parameter as a string of key:value pairs, with each pair ending in a semicolon.

1
curl -X GET 'https://comms.twilio.com/v1/Messages?tags=region:EMEA;campaign:summer_sale;' \
2
--header 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

When you specify more than one Tag, the search uses AND logic. It returns only the resources that match every Tag you provide. There's no OR matching across Tags in a single request.

• Organize resources by business context: Label Messages, Sender Pools, and other resources with keys such as campaign, region, team, or environment so you can group and report on them in terms that match your business.
• Retrieve a campaign's activity: Tag every Message in a campaign with the same campaign value, then filter on that value to pull back the full set of Messages for analysis or auditing.
• Personalize at scale: Use Liquid to stamp recipient-specific values, such as a customer tier or account ID, onto each Message in a bulk send without making separate requests.

• Learn how to personalize message content with Liquid.
• See Operations and Message Tracking to track the resources you've tagged.