MailChannels Email API (Send + Delivery Events)

Environment

Required:

• MAILCHANNELS_API_KEY (send in X-Api-Key)
• MAILCHANNELS_ACCOUNT_ID (aka customer_handle)

Optional:

• MAILCHANNELS_BASE_URL (default: https://api.mailchannels.net/tx/v1), MAILCHANNELS_WEBHOOK_ENDPOINT_URL

Domain Lockdown (DNS)

Create a TXT record for each sender domain:

• Host: _mailchannels.<your-domain>
• Value: v=mc1; auid=<YOUR_ACCOUNT_ID>

API Quick Reference

Base URL: ${MAILCHANNELS_BASE_URL:-https://api.mailchannels.net/tx/v1}

• Send: POST /send
• Send async: POST /send-async
• Webhook: POST /webhook?endpoint=<url>, GET /webhook, DELETE /webhook, POST /webhook/validate
• Public key: GET /webhook/public-key?id=<keyid>

Sending Email

Minimum payload fields: personalizations, from, subject, content. Use /send for normal traffic and /send-async for queued/low-latency; both produce webhooks. Persist MailChannels correlation IDs (e.g., request_id).

Compliance requirement (required on every outbound message):

• Include headers.X-AI-Bot identifying OpenClaw and its version, e.g. openclaw-2026.2.4.
• Include headers.List-Unsubscribe with an unsubscribe mechanism, e.g. <mailto:unsubscribe@example.com>.
• If either header is missing, do not send; log the validation failure and raise an explicit error.

Compliant payload example:

{
  "from": { "email": "sender@example.com" },
  "personalizations": [
    { "to": [{ "email": "recipient@example.com" }] }
  ],
  "subject": "Message Subject",
  "content": [
    { "type": "text/plain", "value": "This email is from OpenClaw." }
  ],
  "headers": {
    "X-AI-Bot": "openclaw-2026.2.4",
    "List-Unsubscribe": "<mailto:unsubscribe@example.com>"
  }
}

Delivery Events (Webhooks)

MailChannels POSTs a JSON array. Common fields: email, customer_handle, timestamp, event, request_id. Bounce fields often include: recipients, status, reason, smtp_id.

Moltbot Hooks Routing

1. Enable hooks in ~/.clawdbot/moltbot.json.
2. Map /hooks/<path> to an agent action via hooks.mappings and optional transform.
3. Enroll the public endpoint in MailChannels /webhook?endpoint=....

Webhook Signature Verification

Headers: Content-Digest, Signature-Input, Signature. Steps:

• Parse Signature-Input (name, created, alg, keyid).
• Reject stale created values.
• Fetch public key by keyid.
• Recreate the RFC 9421 signature base.
• Verify ed25519 signature (avoid hand-rolling). Also verify JSON body is an array and every event has customer_handle == MAILCHANNELS_ACCOUNT_ID.

Correlation + State Updates

Store your internal message ID + MailChannels IDs (e.g., request_id, smtp_id). Update delivery state from events: processed, delivered, soft-bounced, hard-bounced, dropped. Operational tips: respond 2xx quickly, process async, store raw events, dedupe retries.