mbag.ai

Documentation

Everything below is the real API — no SDK required. You need curl and an email address you can read.

1. Request a sign-in code

curl -X POST https://mbag.ai/api/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

A 6-digit code lands in your inbox within seconds. (Limit: 5 codes per email per 15 minutes.)

2. Exchange the code for an API key

curl -X POST https://mbag.ai/api/auth/otp/cli-exchange \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

Response: {"api_key": "mbk_..."}. Signing in for the first time is signing up — this call creates your account on the free tier and provisions your first mailbox on mbag.ai automatically (1 mailbox, 1,000 emails/month). Store the key; it is shown once.

3. Find your mailbox

Step 2 already created your mailbox — the free tier starts with one handle@mbag.ai address and stays capped at one. List your mailboxes to get its id and email_address:

curl https://mbag.ai/api/v1/mailboxes \
  -H "Authorization: Bearer $MBAG_API_KEY"

The response is a JSON array; take the id of the mailbox you just got (this is your $MAILBOX_ID below).

Want a second mailbox on your own domain? That needs a paid tier with room for another mailbox, plus a domain you've verified yourself — GET /api/v1/domains lists domains you own, not the shared mbag.ai platform domain. Then:

curl -X POST https://mbag.ai/api/v1/mailboxes \
  -H "Authorization: Bearer $MBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "domain_id": <your verified domain id>, "email_local_part": "yourhandle"}'

email_local_part is optional — omit it and the handle falls back to a normalised form of name. The full request/response schema is in the OpenAPI specification.

4. Send your first email

curl -X POST https://mbag.ai/api/v1/mailboxes/$MAILBOX_ID/send \
  -H "Authorization: Bearer $MBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "you@example.com", "subject": "hello from my agent", "text_body": "It works."}'

Response: {"message_id": "...", "status": "sent"}. Sends run a server-side policy check first — a recipient your policy blocks returns 403 send_blocked_by_policy, and tier send caps return 429 with an upgrade link. Only mail that actually leaves counts against your quota.

5. Read replies

curl https://mbag.ai/api/v1/mailboxes/$MAILBOX_ID/messages/new \
  -H "Authorization: Bearer $MBAG_API_KEY"

Or register a webhook and get pushed email.received events instead.

Next