Tags and Metadata
The basics
Both tags and custom metadata allow you to label your messages, which lets you search activity, compare stats, and more. This documentation outlines how to create and manage tags and metadata; to explore further ways to use them, see Activity and Reports.
Tags vs. custom metadata
Tags are great for broad categories of messages like welcome or forgot-password emails. The content for these emails may vary, but tags can help track data like opens and clicks for that type of email over time.
Metadata is generally better for managing more user-specific information, like a user ID from your system. Metadata information is returned in webhooks and is searchable in Outbound Activity, so you can tie certain information back to data in your own system.
You can filter both tags and metadata via the View Stats By drop-down menu on your Dashboard, or by using the /messages/search
and /messages/search-time-series
API calls. Tag-based stats are kept indefinitely and are viewable for the lifetime of the account; metadata stats in Outbound Activity are only viewable for 30 days.
Metadata
Mailchimp Transactional lets you attach custom, individualized metadata to messages, which you can integrate into your application’s data model. Metadata is searchable, and it’s included with webhook events and activity CSV exports.
Formatting
Metadata format differs slightly whether you’re sending with SMTP or the API, but there are a few general rules. Key names should include only alphanumeric characters and underscores, though names cannot start with an underscore. Field names can contain spaces, but Mailchimp doesn’t support searching for field names with spaces or non-alphanumeric characters.
Regardless of how you send your message, the following rules apply:
For each message, metadata is limited to 250 bytes of JSON-encoded data.
Nested data structures are not supported.
Values should be limited to scalar types (numbers, strings, Boolean values, and null).
With SMTP, include the X-MC-Metadata
header with a JSON-encoded set of key–value pairs as the value. For example:
X-MC-Metadata header
X-MC-Metadata: { "user_id": "45829", "location_id": "111" }
Via the API, include metadata as part of the message parameter with the messages/send
or messages/send-template
endpoints. For example, a payload with metadata included might look like this:
API payload with metadata
{
"key": "example key",
"message": {
"html": "example html",
"subject": "example subject",
"from_email": "message.from_email@example.com",
"to": [
{
"email": "recipient_email",
"name": "recipient_name"
}
],
"metadata": {
"user_id": "45829",
"location_id": "111"
}
}
}
Recipient-specific metadata
The previous examples add metadata for all recipients of a message, but you can also individualize the metadata for each recipient.
With SMTP, include a _rcpt
key in the encoded JSON object to designate which recipient the metadata should apply to. Via the API, use the recipient_metadata
parameter to designate the recipient and their corresponding values.
Note: Metadata that does not specify a recipient will be applied globally to all recipients of the message. Per-recipient keys take precedence over global keys with the same name.
For example, we’ll send to three recipients — foo@example.com, bar@example.com, and baz@example.com — but we won’t include recipient-specific metadata for baz@example.com.
With SMTP:
SMTP recipient metadata
X-MC-Metadata: { "group_id": "users_active" }
X-MC-Metadata: { "_rcpt": "foo@example.com", "user_id": "123" }
X-MC-Metadata: { "_rcpt": "bar@example.com", "user_id": "456" }
With the API:
API recipient metadata
...
"metadata": {
"group_id": "users_active"
},
"recipient_metadata": [
{
"rcpt": "foo@example.com",
"values": {
"user_id": "123"
}
},
{
"rcpt": "bar@example.com",
"values": {
"user_id": "456"
}
}
]
...
The following metadata will be stored:
Recipient | group_id | user_id |
---|---|---|
foo@example.com | users_active | 123 |
bar@example.com | users_active | 456 |
baz@example.com | users_active | null |
Because the global metadata does not include a user_id
field and no per-recipient metadata was defined for baz@example.com, that recipient’s metadata doesn’t have a value for the user_id
field.
Note: When merging global metadata with per-recipient metadata, each recipient’s final, merged metadata must still be below the 250-byte encoded size limit. If a recipient’s merged metadata exceeds this limit, the metadata for that recipient will be discarded.
Configure metadata fields
By default, message metadata is included with webhook calls — but not in your search index. To enable searching and reporting on metadata, navigate to Settings and then Custom Metadata and enter the keys Mailchimp Transactional should add to its search index. What you enter in Field Name should match exactly what you’re naming the field in your API call or SMTP header.
For example, if you’re sending signup confirmation messages with a unique username in each message’s metadata, you might find it useful to add that username as a custom metadata field and make it searchable from your Outbound Activity.
Note: When you add or remove a custom metadata field, the change will take effect immediately for new messages; Mailchimp will also process your previously sent messages to apply the change to them. Depending on the size of your account, this can take some time.
In addition to adding custom metadata to your search index, you can also define a custom template — even including other metadata — to determine how the metadata appears in your Outbound Activity. For example, if you have a user_id
field and a username
field, you could enter the following in View Template to build a link to the user’s profile page:
<a href="http://example.com/user/{{metadata.user_id}}">{{metadata.username}}</a>
You can reference any custom metadata field by prefixing its name with metadata
. In addition to values namespaced under metadata
, the following properties are also available in metadata view templates for all messages:
name
: the current field’s name, e.g.,user_id
value
: the current field’s value, e.g.,123456
, assuming theuser_id
for the current message is123456
email
: the message recipient’s email addresssubject
: the message’s subject