Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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-To and References, 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.