Custom email headers
The headers object adds your own fields to the outgoing message:
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"subject": "Order confirmed",
"text": "Thanks!",
"headers": {
"X-Order-Id": "12345",
"X-Environment": "production"
}
}
Those travel with the message and are visible to the recipient in the raw source, like any other header.
Reserved names
Some headers describe the message’s own structure or its authenticity. Lockally
sets those itself, and a value you supply for one of them is rejected with a
400.
Structural, because a duplicate would make the message ambiguous:
Message-ID · Date · From · To · Cc · Bcc · Subject ·
MIME-Version · Content-Type · Content-Transfer-Encoding
Identity and authentication, because these say something only the server may say:
Sender · Return-Path · Resent-From · Resent-Sender · Resent-To ·
Resent-Cc · Resent-Bcc · Resent-Date · Resent-Message-ID ·
DKIM-Signature · DomainKey-Signature · Authentication-Results ·
Received · Received-SPF · ARC-Seal · ARC-Message-Signature ·
ARC-Authentication-Results
The second group matters more than it looks. DKIM-Signature,
Authentication-Results and Received are what a receiving mail server reads
to decide whether your message is genuine. Our MTA adds its own, but a
caller-supplied copy would travel alongside, and some filters read the first
occurrence of a header rather than the last. Letting a caller write those would
hand anyone with an API key a way to make a message look pre-authenticated.
Matching is case-insensitive, so dkim-signature is reserved exactly as
DKIM-Signature is.
Valid header names
A name must be printable ASCII with no spaces and no colon, and at most 998 characters. Anything else is rejected by the same check that handles reserved names.
That check exists because of a real bug. The earlier version only stripped
carriage returns and newlines, so a name like From: passed the reserved-name
test (nothing is called from:) and then emitted From:: value, giving the
message a second From line. A name like X Y produced a header with a
space in it, which some parsers read as the end of the header block and the
start of the body.
An unusable header is an error
A reserved or malformed header name is refused at validation time:
{
"type": "about:blank",
"status": 400,
"title": "Reserved header",
"code": "reserved_header",
"detail": "\"From\" is set by the server and cannot be supplied in `headers`. Use the matching top-level field where there is one (`from`, `to`, `cc`, `bcc`, `subject`, `reply_to`), or choose a different header name."
}
A malformed name gives Invalid header name (code invalid_header_name)
instead, and suggests a usable spelling of what you sent.
Nothing is enqueued: the whole send is refused, so you find out before the
message goes anywhere. On POST /v1/send/batch each message is validated on
its own, so a bad header fails that message’s slot and the rest of the batch
still sends.
Headers Lockally adds for you
Two are added automatically in specific cases, and both use reserved-adjacent names you should not try to set yourself:
| Header | When |
|---|---|
List-Unsubscribe, List-Unsubscribe-Post |
On a send with "unsubscribe": true. One-click, managed by Lockally, keyed to the first to recipient. See Bulk. |
X-Lockally-Agent: v1 |
On mail sent through the agent endpoints, as a disclosure that the message was agent-originated. |
Practical uses
Headers are a good fit for values you do not mind the recipient seeing and that help a downstream system route or group mail:
X-Order-Id,X-Invoice-Number, and similar references your support team can search for in a reply thread.X-Environment: staging, so a test message is obvious in a shared inbox.In-Reply-ToandReferences, to thread a message against one you sent earlier. Neither is reserved, and setting them correctly is what makes a reply appear in the right conversation in the recipient’s client.