Send email using MailChannels Email API

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

Security Scan

The instructions match MailChannels' send+webhook use, but the published metadata/registry omits required environment variables and binary requirements and the runtime docs tell the agent to read/modify a user config path — those mismatches merit caution before installing.

Purpose & Capability

The skill's purpose (send email + ingest MailChannels delivery webhooks) aligns with the instructions (send endpoints, webhook enrollment, signature verification, persisting correlation IDs). However the registry metadata provided with the skill (no required env vars, no binaries) is inconsistent with the SKILL.md metadata and content, which require MAILCHANNELS_API_KEY, MAILCHANNELS_ACCOUNT_ID and 'curl' (primaryEnv MAILCHANNELS_API_KEY). This mismatch is unexpected and should be resolved.

Instruction Scope

SKILL.md instructs the agent to enable hooks in '~/.clawdbot/moltbot.json' and to persist MailChannels IDs and raw events. Referencing and modifying an agent/user config path is within the feature (webhook routing) but it is not declared in the registry. The instructions also require network calls to fetch webhook public keys and verify ed25519 signatures — these are appropriate, but the doc gives broad operational guidance (store raw events, process async) that implies persistent storage and write access to user config/files.

Install Mechanism

No install spec and no code files (instruction-only) — minimal disk footprint and low install risk. There is no downloaded/extracted code. That reduces risk compared to an installer that fetches arbitrary binaries.

Credentials

The environment variables the SKILL.md requires (MAILCHANNELS_API_KEY, MAILCHANNELS_ACCOUNT_ID, optional MAILCHANNELS_BASE_URL and MAILCHANNELS_WEBHOOK_ENDPOINT_URL) are appropriate and proportional to sending email and validating webhooks. The issue is that the registry summary claims no required envs/binaries while the SKILL.md metadata requires them (and lists 'curl'). This inconsistency could lead to unexpected behavior or misconfiguration.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It does instruct modifying the agent's own config (~/.clawdbot/moltbot.json) which is normal for integrating webhooks into Clawdbot, but users should confirm that such writes are acceptable. Autonomous invocation is allowed, which is platform default.

What to consider before installing

This skill's runtime instructions look legitimate for MailChannels integration, but the published registry metadata does not declare the environment variables and binary ('curl') that SKILL.md requires, and the docs instruct writing to ~/.clawdbot/moltbot.json. Before installing: (1) confirm the platform will securely store and scope MAILCHANNELS_API_KEY and MAILCHANNELS_ACCOUNT_ID and won't expose them elsewhere; (2) confirm you are comfortable allowing the skill to modify ~/.clawdbot/moltbot.json or ask the author to explicitly declare this config path; (3) request source code or an install spec if you need to review exact behavior; (4) test in a staging account, ensure webhook endpoint is hardened (validate signatures with a vetted ed25519 library), and monitor for unexpected outbound traffic or attempts to read other files. The mismatches may be innocuous packaging errors, but treat them as a red flag until clarified.

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).

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.