Custom Headers

Custom headers enhance email deliverability, bounce handling, and recipient communication. Beyond standard headers (From, To, Subject), you can include additional headers for compliance, tracking, and improved user experience.

info

MailChannels may reject certain headers to prevent abuse and may limit your ability to specify the same header multiple times.

Adding Custom Headers

Include custom headers in the headers object:

"headers": {
  "Custom-Header": "Custom Value"
}

Example

Here's a minimal email payload with custom headers:

{
  "personalizations": [
    {
      "to": [{ "email": "recipient@example.com" }]
    }
  ],
  "from": { "email": "sender@example.com" },
  "subject": "Custom Header Example",
  "content": [
    {
      "type": "text/plain",
      "value": "This email includes custom headers."
    }
  ],
  "headers": {
    "List-Unsubscribe": "<mailto:unsubscribe@example.com>",
  }
}

warning

Using custom headers incorrectly could significantly harm your email deliverability.

Custom Headers Within Personalizations

The personalizations feature allows for recipient-specific custom headers, enabling fine-grained control over email metadata on a per-recipient basis.

Implementation

Custom headers can be defined within each personalization object using the headers field:

"personalizations": [
  {
    "to": [{ "email": "recipient@example.com" }],
    "subject": "Personalized Subject",
    "headers": {
      "List-Unsubscribe": "<mailto:unsubscribe@example.com>",
      "X-Custom-Header": "CustomValue"
    }
  }
]

If the same header appears in both the top-level and personalization objects, the value from the header in the personalization is used.

Example: Multiple Recipients with Custom Headers

{
  "personalizations": [
    {
      "to": [{ "email": "banana-lover123@example.com" }],
      "subject": "Bananas Are On Sale",
      "headers": {
        "List-Unsubscribe": "<mailto:unsubscribe@bananalovers.com>",
        "X-Custom-Header": "BananaFan123"
      }
    },
    {
      "to": [{ "email": "apple-lover123@example.com" }],
      "subject": "Apples Are On Sale",
      "headers": {
        "List-Unsubscribe": "<mailto:unsubscribe@applelovers.com>",
        "X-Custom-Header": "AppleFan123"
      }
    }
  ],
  "from": { "email": "sender@example.com" },
  "content": [
    {
      "type": "text/plain",
      "value": "This email includes custom headers for each recipient."
    }
  ]
}

This structure allows for:

• Recipient-specific custom headers
• Personalized unsubscribe links
• Unique tracking or identification headers per recipient