MCP server

​

Add the server

export MAILR_API_KEY="ak_live_xxxxxxxxxxxxxxxxxxxxxxxx"

claude mcp add --transport http mailr https://app.getmailr.com/api/mcp \
  --header "Authorization: Bearer $MAILR_API_KEY"

{
  "mcpServers": {
    "mailr": {
      "type": "http",
      "url": "https://app.getmailr.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MAILR_API_KEY}"
      }
    }
  }
}

​

Tools

​

Safety model

• send_event defaults to dry_run: true. A dry run performs the full binding match, filter, address and dedup checks and returns exactly the outcomes a live call would, but writes nothing: no connection upsert, no sample, no enqueue, no log. Only an explicit dry_run: false mails anything. (A dry run still costs one unit of rate-limit quota.)
• import_jobs mails nothing immediately — it stages only. But one call burns one of just 10 import slots per org per UTC day, and the staged batch is what an operator later sends.
• Confirm-before-spend is baked into the tool descriptions, so the agent sees the warning at call time rather than only in these docs.
• subscribe_leads returns a signing_secret you must store. The tool tells the agent to show it to you once and not repeat it. The secret is disclosed exactly once, at creation: re-subscribing the same URL is idempotent and returns the existing row’s id with signing_secret: null — never the stored secret, and never a silent rotation. A lost secret is replaced via POST /api/v1/webhooks/rotate, which returns the new one a single time.
• Scopeless keys are unrestricted. Per the v1 policy, a key that declares no scopes passes every check. Treat the key like a password: it is the whole credential, it identifies the tenant on its own, and anything holding it can mail on the org’s behalf. Scope the key you hand to an agent, and revoke it from the Mailr dashboard if it leaks.
• The route is key-authed, not session-authed. /api/mcp runs no dashboard session logic and holds no privileged access of its own; every tool call is authorized downstream by the same API-key check the /api/v1/* endpoint it proxies to performs.
• Every tool result carries a notice telling the agent to treat response data — lead messages, names, custom fields — strictly as data, never as instructions.

​

Try it

> Which Mailr org is this key for?

  ⏺ whoami
    HTTP 200 OK
    { "org_id": "org_2abcXYZ", "org_name": "Reyes Roofing" }

  This key belongs to Reyes Roofing.

> Dry-run a completed job at 3134 River Valley Dr, Austin TX 78701 for Dana Reyes, $6,400.

  ⏺ send_event (dry_run: true)
    HTTP 202
    {
      "received": true,
      "duplicate": false,
      "dry_run": true,
      "matched_automations": 1,
      "outcomes": [
        { "automation_id": "a1b2c3d4-…", "name": "Post-job reactivation",
          "matched": true, "reason": "queued" }
      ]
    }

  "Post-job reactivation" would fire and mail this address. Nothing was written.
  Want me to send it for real? That enqueues a live postcard and spends postage.