Mailchannels Email Api

Send email via MailChannels Email API and ingest signed delivery-event webhooks into Clawdbot (Moltbot).

Install

openclaw skills install @deniz-mailchannels/mailchannels

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:

json

{
  "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

Enable hooks in ~/.clawdbot/moltbot.json.
Map /hooks/<path> to an agent action via hooks.mappings and optional transform.
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.

More MailChannels Skills

For maintained skills covering SDKs, domain setup and operations beyond this quick reference, see the Codex plugin (npx skills add mailchannels/mailchannels-codex-plugin --list) and the Claude Code plugin.