Custom metadata FAQ
Custom metadata lets you add information to messages to help track them for their entire lifecycle. Custom metadata can be added to messages sent using both our REST API and SMTP services. Metadata added to a message will be displayed in the Postmark UI, available using our API, and also returned in webhook events. Read on for some answers to common questions about Postmark’s custom metadata feature.
Can't I just use tags instead?
Tags can be used to group like emails together for easy tracking, such as tagging all of your welcome emails with the tag 'welcome'. Tags are limited though in that only one tag can be applied to each message. Anywhere you need one or more unique identifiers on a message, rather than a generic grouping of similar messages, you will want to use metadata instead.
How do I add custom metadata when sending with the API?
{
"From": "sender@example.com",
"To": "recipient@example.com",
"Subject": "Email from Postmark with some custom metadata",
"HtmlBody": "<a href=\"http://postmarkapp.com\">Go to Postmark</a>",
"Metadata": {
"color": "blue",
"client-id": "12345"
},
"TrackOpens": false,
"TrackLinks": "HtmlAndText"
}
How do I add custom metadata using SMTP?
"X-PM-Metadata-color":"blue"
"X-PM-Metadata-client-id":"12345"
How is metadata displayed in the UI?
Will recipients be able to see the metadata on the received message?
How do I search for messages using metadata?
curl "https://api.postmarkapp.com/messages/outbound?count=50&offset=0&metadata_color=blue" \
-X GET \
-H "Accept: application/json" \
-H "X-Postmark-Server-Token: server token"
Note: you can currently only search by a single metadata field at a time.
What are the limitations?
- When sending with the API, duplicate keys, including the same key with case differences, are not allowed
- i.e. You cannot use both 'a_key' and 'A_Key' for your metadata value names
- When sending with SMTP, if you add duplicate keys we will append the additional keys with an incremental number
- You can add up to 10 metadata fields to each message.
- You can use as many different unique fields across all of your outbound messages as you need.
- Metadata field names are limited to 20 characters.
- Metadata field values are limited to 80 characters.
- All metadata field values will be interpreted and returned in webhook payloads as strings.
- You can currently only search by a single metadata field at a time.