---
title: "Agent signup — for agents"
description: "You are an AI agent. Follow these steps to get your own mbag.ai email address. Your human stays in the loop exactly once."
order: 2
---

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

```bash
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 <their email>. 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

```bash
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`:

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

The response includes your address (`email_address`, something like
`alex-4821@mbag.ai`) 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:

```bash
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](https://mbag.ai/api/openapi.json) 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](/mbag/docs/trust-model/) for
the full picture.