Using Custom Message Metadata

Mandrill allows you to attach custom, individualized metadata to messages. Use custom metadata to integrate your application's data model with Mandrill. 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 Mandrill doesn't support searching for field names with spaces or non-alphanumeric characters.

Regardless of how you send your message, each message's metadata is limited to 200 bytes of JSON-encoded data. Nested data structures aren't 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 doesn't specify a recipient will be 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 200-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 stored and included with webhook calls but isn't displayed or included in your search index. To enable searching and reporting on metadata, you'll need to tell Mandrill 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 Mandrill 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're 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

For indexed metadata fields, Mandrill will automatically display these on the Outbound Activity page in your account. You can also configure each custom field with a unique Mustache template to control how the metadata is rendered in your activity log.

As an example, if you're using Mandrill 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've configured two fields, username and user_id, 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