MAIL API

Sender names, replies and unsubscribing.

Use the same sending API and restricted key for a recognizable sender name and unsubscribe headers.

Send with a display name.

POST this JSON to /api/v1/agent/send with your Bearer key and a unique, stable Idempotency-Key. Replace the sample addresses and unsubscribe URL before sending.

Named sender and one-click unsubscribe

{
  "from": {
    "email": "[email protected]",
    "name": "Lennart from Your App"
  },
  "to": "[email protected]",
  "subject": "An update from Your App",
  "text": "Your message. Unsubscribe: https://your-domain.example/unsubscribe?token=RECIPIENT_TOKEN",
  "headers": {
    "List-Unsubscribe": "<https://your-domain.example/unsubscribe?token=RECIPIENT_TOKEN>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

The From field accepts either an email string or an object with email and an optional name of up to 200 characters. The address must still belong to your mailbox and be allowed by your key. The name changes only what recipients see; it does not change your authenticated sender, return path or sending allowance. Control characters are rejected.

Make unsubscribing work.

The headers object accepts only List-Unsubscribe and List-Unsubscribe-Post, with case-insensitive names. Values must be strings without control characters. Duplicate names and other headers are rejected.

List-Unsubscribe uses angle-bracketed HTTPS or mailto URLs. For one-click, include exactly one HTTPS URL and set List-Unsubscribe-Post to List-Unsubscribe=One-Click. KeyKeeper signs both headers with your domain’s DKIM identity.

Your application must process an HTTPS POST to that URL with body List-Unsubscribe=One-Click. Encode the recipient and list in a hard-to-guess token. Do not require login, cookies, a redirect or another confirmation. A GET can show a confirmation page so link scanners do not unsubscribe people. Honor requests and exclude unsubscribed recipients from later marketing sends. Include a visible unsubscribe link in the message body as well.

These headers declare an unsubscribe mechanism; they do not create an endpoint or a mailing list. See RFC 8058 and Gmail’s sender guidelines.

Route replies to a person.

Omitting replyTo sends replies to your From address. A restricted sending key permits only Reply-To addresses in its allowed sender list. It cannot redirect replies to an arbitrary external inbox.

For personal correspondence, create a separate mailbox such as [email protected], issue its own send-only key and share incoming mail with the human owner. Send from that mailbox and omit Reply-To. A shared notifications mailbox also delivers replies to its human owner.

Keep retries and delivery checks accurate.

Reuse the identical message and idempotency key after a timeout. Changing the display name or unsubscribe URL is a different message and returns a conflict when the key has already been used. An accepted response means submission to the mail server; it does not guarantee Gmail inbox placement. Check the outgoing delivery result and the recipient’s authentication headers.