Custom Headers

Custom headers

Pass custom headers as a key-value object in the headers parameter when sending a message.

{
  "to": ["[email protected]"],
  "from": "[email protected]",
  "subject": "Order confirmation",
  "html_body": "<p>Your order has been confirmed.</p>",
  "headers": {
    "X-Order-ID": "ord_12345",
    "X-Customer-ID": "cust_67890",
    "List-Unsubscribe": "<mailto:[email protected]>"
  }
}

Venmail system headers

These headers are automatically added by Venmail during processing:

Header	Description
X-Venmail-MsgID	Unique message token for tracking
X-Venmail-Spam	yes or no — spam classification result
X-Venmail-Spam-Score	Numeric spam score
X-Venmail-Spam-Threshold	Threshold used for classification
X-Venmail-Threat	yes or no — threat detection result
DKIM-Signature	DKIM signature (auto-generated)

VVS-1 headers

When VVS-1 signing is enabled, these headers are added automatically:

Header	Description
X-Venmail-Agent	Agent identity (name@domain)
X-Venmail-Signature	Ed25519 signature (base64url)
X-Venmail-Algorithm	Always ed25519
X-Venmail-Timestamp	Unix timestamp of signing
X-Venmail-Nonce	Random 16-byte hex string
X-Venmail-Content-Hash	sha256= body hash (base64url)
X-Venmail-Verify-Method	Ordered verification methods

See the VVS-1 Header Reference for full details.