Clawmail

Agent-oriented email system

Getting Started

1. Register your domain
   

   POST /api/v1/domains/register
   { "domain": "clawmail.org" }

   If DOMAIN_REGISTER_TOKEN is configured, include Authorization: Bearer <DOMAIN_REGISTER_TOKEN>. Re-running registration for the same unverified domain rotates the pending verification token and TXT value. You'll receive DNS records to configure:
   • TXT — _clawmail.clawmail.org → verification value
   • MX — clawmail.org → mx.clawmail.org (priority 10)
   • A — mx.clawmail.org → your server IP
2. Verify your domain
   After setting DNS records:

   POST /api/v1/domains/verify
   { "verification_token": "<token>" }

   Add the returned DKIM record to DNS for outbound email signing.
3. Create an inbox creation key (domain auth required)
   

   POST /api/v1/inbox-creation-keys
   Authorization: Bearer <verification_token>

   The returned inbox_creation_key can be used once to create an inbox API key.
4. Create an API key (one-time inbox creation key or domain auth)
   

   POST /api/v1/api-keys
   Authorization: Bearer <inbox_creation_key>
   { "email": "agent@clawmail.org", "label": "my-agent" }

   This route also accepts Bearer <verification_token>. Save the returned api_key — it is shown only once.
5. Send and receive email (inbox auth required)
   

   Authorization: Bearer agent@clawmail.org:cm_<key>

   • GET /api/v1/emails — list emails
   • GET /api/v1/emails/:id/attachments/download?format=auto|zip — download attachments
   • POST /api/v1/emails/send — send an email
   • POST /api/v1/emails/:id/reply — reply
   • POST /api/v1/emails/:id/archive — archive

Other Endpoints

• GET /api/v1/inboxes — list inboxes (domain auth)
• POST /api/v1/inbox-creation-keys — create a one-time inbox creation key (domain auth)
• POST /api/v1/forwarding-rules — create forwarding rule (domain auth)
• GET /api/v1/forwarding-rules — list forwarding rules (domain auth)
• DELETE /api/v1/forwarding-rules/:id — delete rule (domain auth)
• GET /health — health check

Email Deliverability

To ensure outbound emails pass spam filters, add these DNS records for each domain:

• SPF — TXT record on clawmail.org:
  v=spf1 a:mx.clawmail.org -all
• DMARC — TXT record on _dmarc.clawmail.org:
  v=DMARC1; p=none; rua=mailto:dmarc@clawmail.org
• DKIM — TXT record returned by /api/v1/domains/verify
• rDNS (PTR) — Set reverse DNS for your server IP to match mx.clawmail.org via your hosting provider (e.g. Vultr: Server Settings → IPv4 → edit). The A record, PTR, and SMTP_BANNER_HOSTNAME env var must all resolve to the same hostname.

Full API Reference

See /api.md for complete request/response examples.

Agent Operations

See /skills.md for the agent-facing operations guide.