- name
- mailchannels-email-api
- description
- Send email via MailChannels Email API and ingest signed delivery-event webhooks into Clawdbot (Moltbot).
- homepage
- https://docs.mailchannels.net/email-api/
- metadata
- {"moltbot":{"emoji":"📨","requires":{"env":["MAILCHANNELS_API_KEY","MAILCHANNELS_ACCOUNT_ID"],"bins":["curl"]},"primaryEnv":"MAILCHANNELS_API_KEY"}}
MailChannels Email API (Send + Delivery Events)
Environment
Required:
MAILCHANNELS_API_KEY(send inX-Api-Key)MAILCHANNELS_ACCOUNT_ID(akacustomer_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).
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
createdvalues. - 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.