Set up DMARC and see who's sending email using your brand's domain.

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?

Add your metadata to the“Metadata” field in the body of your API call when sending an email. Metadata is added to the“Metadata” JSON field in name/value pairs, as shown in this example request:
 "From": "",
 "To": "",
 "Subject": "Email from Postmark with some custom metadata",
 "HtmlBody": "<a href=\"\">Go to Postmark</a>",
 "Metadata": {
    "color": "blue",
    "client-id": "12345"
 "TrackOpens": false,
 "TrackLinks": "HtmlAndText"

How do I add custom metadata using SMTP?

Metadata can be added to message sent using SMTP by adding an SMTP header. If you add an SMTP header that contains the prefix X-PM-Metadata-, it will be registered as a metadata field. For an example, here are the SMTP headers you would add to the message to register custom metadata values for color and client-id:


How is metadata displayed in the UI?

When viewing a message’s details page in the Postmark UI, you will be able to see the metadata fields and their values when viewing a message:

Will recipients be able to see the metadata on the received message?

Metadata added to a message will not appear on the message received by the recipient(s). Headers used for metadata will be processed by Postmark prior to sending the message and removed before sending the message to the recipient.

How do I search for messages using metadata?

Searching by metadata fields and their values is not possible in the UI at this time but can be done when using the Messages API. To search by metadata with the API, add a search parameter with prefix metadata_ and the value you are targeting. This will narrow down the search to only messages who have that metadata name with the value you supplied. As an example, here is a search for emails sent where the metadata value of color is blue:
 curl "" \
    -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.
Last updated May 24th, 2023

Still need some help?

Our customer success team has your back!