Skip to main content

​
Custom headers

Custom headers let you attach RFC 5322 compliant headers to your messages. This is useful for message classification, tracking, and per-recipient identifiers.
Some headers are restricted to prevent abuse, and MailChannels may limit how many times the same header can be repeated.

​
Adding custom headers

Include custom headers in the top-level headers object to apply them to every recipient of the message: 
#!/usr/bin/env bash
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/plain",
      "value": "Hello from MailChannels."
    }
  ],
  "headers": {
    "X-Campaign-Id": "welcome-2026"
  }
}
JSON
Using custom headers incorrectly could significantly harm your email deliverability.

​
Custom headers within personalizations

Custom headers can also be added to individual personalizations, allowing for recipient-specific headers. This is useful for personalized unsubscribe links, tracking, or identification headers that vary per recipient. 
#!/usr/bin/env bash
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL_1:?Set TO_EMAIL_1}"
: "${TO_EMAIL_2:?Set TO_EMAIL_2}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    {
      "to": [{ "email": "$TO_EMAIL_1" }],
      "headers": {
        "X-Campaign-Id": "welcome-2026-cohort-a"
      }
    },
    {
      "to": [{ "email": "$TO_EMAIL_2" }],
      "headers": {
        "X-Campaign-Id": "welcome-2026-cohort-b"
      }
    }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/plain",
      "value": "Hello from MailChannels."
    }
  ]
}
JSON
When a header is defined both globally and in a personalization object, the value in the personalization object is used.