Mail Buttons

Developers

Technical overview for building on the Mailbuttons email API for domain-scoped inboxes and AI-powered workflows.

Platform architecture

Mailbuttons runs a managed, multi-tenant email api with a JMAP-compatible control plane and agent-focused extensions.

  • Inbound: Dedicated subdomains, SPF/DKIM/DMARC enforcement, bounce handling
  • Proxy: `/api/v1/jmap` terminates on Mailbuttons edge infrastructure with tenant-aware routing hints
  • Outbound: Signed mail via your verified domains or managed tenant pools
  • Agents: Optional tool execution layer for inbox-driven automations
  • Memory: Vector embeddings + timeline indexes so AI agents recall entire threads

What the API exposes

  • First-class JMAP-compatible session + method pipeline (mail, threads, identities)
  • Domain provisioning with DNS manifests and verification polling
  • Pluggable auth hints to scope a request to an individual agent inbox
  • Unified logging for inbound agent messages and outbound mail

JMAP-compatible call example

Authenticate with your tenant key and forward JMAP method calls exactly as you would against any standards-compliant server. Mailbuttons preserves compatibility while layering optional AI memory features through `_mailbuttons` hints.

List messages in an agent inbox:

# Save the payload once for reuse
cat <<'EOF' >/tmp/email-query.json
{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:mail"
  ],
  "_mailbuttons": { "account": "agent@example.com" },
  "methodCalls": [
    [
      "Email/query",
      {
        "accountId": "{{accountId}}",
        "filter": { "inMailbox": "{{mailboxId}}" },
        "sort": [{ "property": "receivedAt", "isAscending": false }],
        "limit": 25
      },
      "c1"
    ]
  ]
}
EOF
# Fetch the tenant-scoped JMAP session
curl -s https://emailapi.mailbuttons.com/api/v1/jmap/session   -H "Authorization: Bearer <TENANT_API_KEY>"
# Issue a JMAP request (email query in this example)
curl -s https://emailapi.mailbuttons.com/api/v1/jmap   -H "Authorization: Bearer <TENANT_API_KEY>"   -H "Content-Type: application/json"   --data @/tmp/email-query.json

Tip: The forthcoming Rust and Python SDKs wrap this payload alongside type-safe helpers for common operations like queueing outbound mail or ingesting threads.

Domain provisioning workflow

  1. Add a domain from the dashboard or via POST /api/domains/add
  2. Apply the generated TXT records for SPF, DKIM selector, and DMARC
  3. Poll verification or trigger it manually with POST /api/domains/{domain}/verify
  4. Create mailboxes through upcoming SDK helpers or raw JMAP-compatible calls
Create an accountLog in