maeil API & MCP

Overview

Every integration path drives the same core action: a phone-only person is invited to an event, maeil texts them a one-tap accept link, and on accept their real email is returned to you.

All three authenticate with the same mk_live_… API key. US phone numbers only in v1.

Authentication

Two credentials, two purposes:

Send the API key as either header:

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create an API key

Authenticate with your account JWT (not an API key). Max 20 active keys per account.

curl -X POST https://api.maeil.cc/v1/keys \
  -H "Authorization: Bearer <YOUR_ACCOUNT_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"production key"}'

Response — 201 Created:

{
  "id": "key_...",
  "key": "mk_live_...",                     // shown ONCE — copy it now
  "prefix": "mk_live_abcd",
  "name": "production key",
  "email_token": "mp_Xa9kQ3v7bN2pLw...",    // handle for the email on-ramp
  "email_address_template": "<phone>+mp_Xa9kQ3v7bN2pLw...@maeil.cc"
}

GET /v1/keys lists your keys (prefix, name, per-key limits, usage, revoked flag). DELETE /v1/keys/:id revokes one. Revoking a key also disables its email on-ramp address immediately.

Send an invite

Authenticate with an API key.

curl -X POST https://api.maeil.cc/v1/invite \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "event": {
      "title": "Intro call",
      "start": "2026-06-15T14:00:00Z",
      "end": "2026-06-15T14:30:00Z",
      "location": "Phone",
      "description": "Quick 15-min intro",
      "organizer": "agent@firm.com"
    },
    "consent_attestation": "client booked by phone on 6/1",
    "callback_url": "https://your-app.example/webhooks/maeil"
  }'

Response — 201 Created:

{ "invite_id": "V1StGXR8_Z5jdHi6B-myT", "status": "sent", "accept_url": "https://app.maeil.cc/a/V1StGXR8_Z5jdHi6B-myT" }

Get invite status

Status and the revealed email once accepted. Scoped to the key's owning account.

{
  "invite_id": "V1StGXR8_Z5jdHi6B-myT",
  "status": "accepted",
  "recipient_phone": "+15551234567",
  "event_title": "Intro call",
  "event_start": "2026-06-15T14:00:00Z",
  "revealed_email": "dana@example.com",
  "created_at": "2026-05-24T16:00:00.000Z"
}

status is one of sent · accepted · declined · failed. revealed_email is null until the recipient accepts and provides it.

Webhooks

If you passed callback_url (Builder plan), maeil POSTs it when the recipient responds:

{
  "invite_id": "V1StGXR8_Z5jdHi6B-myT",
  "status": "accepted",
  "recipient_email": "dana@example.com",
  "recipient_phone": "+15551234567",
  "event_title": "Intro call",
  "responded_at": "2026-05-24T17:02:11.000Z"
}

Verify the signature. Each callback carries X-Maeil-Signature: sha256=<hex> — an HMAC-SHA256 of the exact request body. Recompute it with your shared secret and compare before trusting the payload.

Error codes

Errors return a JSON body { "error": "...", "code": "..." } with the HTTP status below.

Rate limits

Two layers enforce sending: a per-key cap and your account's monthly pool. API keys draw from the same account pool as the dashboard and your personal MCP key — one total, not split.

New keys are seeded with per-key limits derived from your plan. On metered plans (Builder, Business) the per-key monthly bound is effectively unlimited so a single key can reach your full included volume and beyond — the account pool plus metered overage governs. Hitting a limit returns 429 (rate_limited for a daily/per-key cap, fair_use_reached for a non-metered monthly pool).

MCP server

maeil runs as a Model Context Protocol server so assistants can invite by phone and read back the email without leaving the conversation. It exposes exactly two tools:

Protocol revision 2025-06-18 (Streamable HTTP). consent_attestation is required at the tool — a send without it is refused before any network call.

Remote endpoint

Any client that can attach an Authorization header can point at https://mcp.maeil.cc/mcp:

{
  "mcpServers": {
    "maeil": {
      "url": "https://mcp.maeil.cc/mcp",
      "headers": { "Authorization": "Bearer mk_live_REPLACE_ME" }
    }
  }
}

Local connector

For clients that can't set a header (or require OAuth), launch the bundled Node connector with your key in the environment (Node 18+). Example — Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "maeil": {
      "command": "node",
      "args": ["/path/to/workers/mcp/dist/maeil-mcp-stdio.mjs"],
      "env": { "MAEIL_API_KEY": "mk_live_REPLACE_ME" }
    }
  }
}

Discover the tools over plain JSON-RPC:

curl -s https://mcp.maeil.cc/mcp \
  -H "Authorization: Bearer mk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Email on-ramp

An email-based scheduler (Cal.com, Howie, Reclaim, Motion, …) can use maeil with zero code — just add a tokenized maeil address as a guest on the calendar invite:

<phone>+<email_token>@maeil.cc
e.g.  5551234567+mp_Xa9kQ3v7bN2pLw...@maeil.cc

• <phone> — the recipient's US number (digits only).
• +<email_token> — your attributable handle (mp_…), returned when you create an API key (email_address_template). It marks the send as yours and applies your key's limits.

The plain consumer address 5551234567@maeil.cc is unrelated; the token is what attributes a send to a contracted partner. Revoke the key and the address stops resolving immediately.

Compliance

• Consent is the legal basis. A calendar invite is transactional under the TCPA only if you have the recipient's consent. Every send requires consent_attestation; it's stored on the invite and in the audit log.
• Transactional only. The locked SMS template carries no promotional content — one promo line would reclassify the message as marketing.
• STOP is honored globally. Any number that has texted STOP is suppressed across all callers; such sends return 403 suppressed.
• The caller is the accountable party for having consent, as reflected in the Terms.

Questions the docs don't answer? Email maeil@cb-industries.co or visit Help.