Transactional Email allows you to attach custom, individualized metadata to messages. Use custom metadata to integrate your application's data model with Transactional Email. Metadata is searchable (either in the activity view or via the API) and is included with webhook events and activity CSV exports.
Metadata Format
The metadata format differs slightly depending on whether you are using SMTP or the API to send your messages. Key names should include only alphanumeric characters and underscores, and names may not start with an underscore. Field names can contain spaces, but Transactional Email does not 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).
SMTP
To include custom metadata with an SMTP submission, include the X-MC-Metadata header with a JSON-encoded set of key-value pairs as the value. For example:
X-MC-Metadata: { "user_id": "45829", "location_id": "111" }
API
Using the messages/send.json or messages/send-template.json endpoint, include metadata as part of the message parameter:
{
"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"
}
}
}
Global and Per-Recipient Metadata
The previous examples add metadata for all recipients of the message. If your message has many recipients and you want to individualize the metadata for each recipient, you can include recipient-specific metadata.
SMTP
Include a _rcpt key in the encoded JSON object to designate which recipient the metadata should apply to. Metadata that does not specify a recipient is applied globally to all recipients of the message, and per-recipient keys take precedence over global keys with the same name.
API
Use the recipient_metadata parameter to designate the recipient and their corresponding values. Per-recipient keys take precedence over global keys with the same name.
Examples
For example, consider the headers for the following message, with three recipients (foo@example.com, bar@example.com, and baz@example.com):
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" }
Or the following specified via an API call:
...
"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. 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:
Recipientgroup_iduser_id
foo@example.com users_active 123
bar@example.com users_active 456
baz@example.com users_active null
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 included in your search index. To enable searching and reporting on metadata, you must tell Transactional Email which keys to add to its search index. You can do this on the Custom Metadata settings page.
When you add or remove a custom metadata field, the change will take effect immediately for new messages, and Transactional Email will process your previously-sent messages to apply the change to them. Depending on the size of your account, this can take some time.
Search Metadata
You can search your indexed metadata fields, either in the Outgoing Activity in your account or via the API's messages/search call. To search for an indexed field, prefix the metadata field name with u_ in your search query:
full_email:test@example.com AND u_order_id:1398274
If the metadata value that you are searching for includes non-alphanumeric characters, surround it in quotes:
full_email:test@example.com AND u_contact_url:"http://example.com/test"
View Metadata
Transactional Email automatically displays indexed metadata fields on the Outbound Activity page. You can also configure each custom field with a unique Mustache template to control how the metadata renders in your activity log.
For example, if you are using Transactional Email to send signup confirmation messages, and you include a unique user identifier in each message's metadata, you could use the following view template to transform the user id field into a link to the user's profile page in your application:
<a href="http://yourapplication.com/user/{{value}}">{{value}}</a>
You can reference other custom metadata fields by prefixing their names with metadata. If you configured the username and user_id fields, you could change the template in the previous example to include the username as the text of the link:
<a href="http://yourapplication.com/user/{{metadata.user_id}}">{{metadata.username}}</a>
These properties are also available in metadata view templates for all messages:
- name: the current field's name
- value: the current field's value
- email: the message recipient's email address
- subject: the messages subject