You are an AI agent setting up your own email address on mbag.ai. The whole flow is four HTTP calls. Your human is needed exactly once: to read you a 6-digit code from their inbox.

# Before you start

Ask your human for the email address they want to own this account. The account belongs to them; you operate the mailbox.

# Step 1 — request a sign-in code for your human

curl -X POST https://mbag.ai/api/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{"email": "<their email>"}'

• 200 {} — a 6-digit code is now in their inbox.
• 429 {"error":"too_many_requests"} — more than 5 codes in 15 minutes. Wait 15 minutes; do not retry in a loop.
• 400 {"error":"invalid_email"} — re-check the address with your human.

# Step 2 — ask your human for the code

Say: "I've sent a 6-digit code to . Please read it to me — it expires in 10 minutes." Do not guess codes: 5 wrong attempts invalidates every outstanding code for that address and you must start over.

# Step 3 — exchange the code for your API key

curl -X POST https://mbag.ai/api/auth/otp/cli-exchange \
  -H "Content-Type: application/json" \
  -d '{"email": "<their email>", "code": "<the code>"}'

• 200 {"api_key": "mbk_..."} — store this securely (an environment variable or your secret store — never in code or logs). It is shown once. First sign-in creates the account on the free tier and automatically provisions your mailbox on mbag.ai (1 mailbox, 1,000 emails/month).
• 401 — wrong or expired code. Ask your human to re-read it; after 5 failures, return to Step 1.

# Step 4 — find your mailbox

Your mailbox already exists: signing in created it. List your mailboxes to get its address and id:

curl https://mbag.ai/api/v1/mailboxes \
  -H "Authorization: Bearer <your api key>"

The response includes your address (email_address, something like [email protected]) and its id — you'll need the id for Step 5.

In the rare case the list comes back empty (a provisioning hiccup at signup), you may create one yourself:

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

Use the OpenAPI specification for the exact schema. Note the field is email_local_part, not handle. The free tier allows exactly 1 mailbox — if you already have one, this call fails; use Step 4's GET instead.

# Step 5 — prove it works

Send your human a hello via POST /api/v1/mailboxes/{id}/send (single recipient, to/subject/text_body). A 200 with "status": "sent" and a message_id means you have a working address.

# The rules the server enforces (regardless of what you do)

• Send caps: free tier is 1,000 emails/month per account and 100/day per mailbox. You get 429 with an upgrade link when you hit them.
• Policy: the mailbox owner can blocklist recipients and set inbound sender rules; blocked sends return 403 and are logged for the owner.
• Audit: every governed send lands in a tamper-evident audit log the owner can inspect.

These are server-side. Read the trust model for the full picture.