Emails created through the Partner API (POST /api/partner/emailMessages) can now carry custom headers. Pass a headers object with the message and they are recorded on the email and sent with it.
The main use is RFC 8058 one-click unsubscribe: set List-Unsubscribe and List-Unsubscribe-Post and mailbox providers such as Gmail and Yahoo show their unsubscribe button for your messages.
A few guardrails apply so headers can’t interfere with delivery:
- Sender, recipient, identity, MIME-structure, and provider-control headers (
From,To,Bcc,Reply-To,Message-ID,Date,Content-Type,Content-Disposition, and similar) can’t be overridden — usefromEmailandtoEmailinstead. - Up to 50 headers per message, names up to 200 characters, and each header line within the 998-byte RFC 5322 limit. Accented or other non-ASCII values are measured as the encoded form that actually goes on the wire.
- Invalid headers are rejected with a clear error before anything is recorded or sent.
The recorded headers are returned with the message in the create response and in GET /api/partner/emailMessages/{id}. Only messages created through the Partner API carry them — email synced in from a connected Gmail or Outlook mailbox does not expose its headers.