# Tags Tags are custom key-value metadata that you attach to your resources. Use Tags to label resources with your own business context, such as a campaign name, region, or customer segment, and then filter on those labels when you search. Tags follow a single, shared schema. The behavior described on this page is identical whether you tag a Message, a Sender Pool, or an Email. ## What Tags are 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. ```json { "tags": { "campaign": "summer_sale", "region": "EMEA" } } ``` Tags are metadata only. They don't affect delivery, sender selection, or content rendering. They help you organize, correlate, and retrieve resources. ## Tag schema and limits The same constraints apply to Tags on every resource that supports them. | Constraint | Limit | | ------------------------------------- | --------------------------------------- | | Maximum number of key-value pairs | 10 | | Maximum key length | 128 characters | | Maximum value length | 256 characters | | Allowed characters in keys and values | `a-z`, `A-Z`, `0-9`, `.`, `_`, `~`, `-` | 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. ## Add Tags to a resource 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. ```bash curl -X POST 'https://comms.twilio.com/v1/Messages' \ --header 'Content-Type: application/json' \ --data '{ "from": { "address": "", "channel": "SMS" }, "to": [ { "address": "+15558675310", "channel": "PHONE" } ], "content": { "text": "Hello, World!" }, "tags": { "campaign": "summer_sale", "region": "EMEA" } }' \ -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. ```bash curl -X POST 'https://comms.twilio.com/v1/SenderPools' \ --header 'Content-Type: application/json' \ --data '{ "name": "Sales Leads - APAC", "tags": { "region": "APAC" } }' \ -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": {}`). ## Personalize tag values per recipient The `tags` field supports the [Liquid](https://shopify.github.io/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. ```bash curl -X POST 'https://comms.twilio.com/v1/Messages' \ --header 'Content-Type: application/json' \ --data '{ "from": { "address": "", "channel": "SMS" }, "to": [ { "address": "+15558675310", "channel": "PHONE", "variables": { "tier": "gold" } }, { "address": "+15558675311", "channel": "PHONE", "variables": { "tier": "silver" } } ], "content": { "text": "Thanks for being a customer!" }, "tags": { "campaign": "loyalty_2026", "tier": "{{tier | default: 'bronze'}}" } }' \ -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](/docs/bulk-messaging/personalization). ## Tag inbound messages 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. ## Filter resources by Tag 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. ```bash curl -X GET 'https://comms.twilio.com/v1/Messages?tags=region:EMEA;campaign:summer_sale;' \ --header 'Content-Type: application/json' \ -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. ## Common use cases * **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. ## Next steps * Learn how to [personalize message content](/docs/bulk-messaging/personalization) with Liquid. * See [Operations and Message Tracking](/docs/bulk-messaging/operations-and-message-tracking) to track the resources you've tagged.