Custom headers

Add custom MIME headers to an outbound email with the headers object — a map of header name to string value. These are written verbatim into the message, which is useful for correlation IDs, threading, or downstream filtering on the receiving side.

MailBlastr already sets all the headers required for deliverability. Custom headers are an advanced feature for a few specific cases — for example, setting a unique `X-Entity-Ref-ID` so that Gmail does not collapse a series of distinct messages into a single conversation thread.

Example

A common use is a per-message reference ID you can correlate against your own systems:

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@example.com"],
  "subject": "Order confirmation",
  "html": "<p>Thanks for your order.</p>",
  "headers": {
    "X-Entity-Ref-ID": "order_12345",
    "X-Mailer-Campaign": "transactional"
  }
});
console.log({ data, error });

Header sanitization

Both header names and values are sanitized before they are written to the message: any carriage-return or line-feed characters (\r, \n) are stripped and collapsed to a single space. This prevents header injection — a value cannot smuggle in extra headers or a premature body break.