# Mailbox in one call

{/* // MAILBOX IN ONE CALL */}

A live mailbox is one call away. Pick the surface that matches where your agent runs — the request
shape is identical underneath.
**Offline by default:** The Postern API is rolling out. Every example here works against built-in fixtures today: set
  `POSTERN_API_BASE_URL=mock` (SDK / curl through the SDK) or `POSTERN_MOCK=1` (MCP) and the whole
  flow runs deterministically with no network and no key. Flip in a real `pk_agent_…` key when yours
  is live.

## Get a key

You authenticate with a **scoped agent key** (`pk_agent_…`). You get one by redeeming an **enrollment
key** (`pk_enroll_…`) that a human or org-admin minted for you. The enrollment key can create up to
*N* mailboxes and nothing else — see [Authentication & keys](https://docs.agents.mszazu.com/quickstart/authentication/).

```bash frame="terminal"
export POSTERN_API_KEY="pk_agent_7Hq2…"          # your scoped agent key
export POSTERN_API_BASE_URL="https://api.agents.mszazu.com"
```

## Create a mailbox

```bash frame="terminal"
curl -sS -X POST "$POSTERN_API_BASE_URL/v1/inboxes" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Support Bot" }'
```

Response:

```json
{
  "id": "inbox_3kP9wQ",
  "address": "agent7@x4p.mszazu.com",
  "display_name": "Support Bot",
  "domain": "x4p.mszazu.com",
  "status": "live",
  "created_at": "2026-06-12T18:04:11Z"
}
```

Omit `username` and `domain` and Postern mints an instant address on a pre-verified, pre-warmed
shared `mszazu.com` subdomain — no DNS, no waiting.

  ```bash frame="terminal"
npm install @postern/sdk
```

```ts title="create-inbox.ts"
import { Postern } from "@postern/sdk";

const postern = new Postern({ apiKey: process.env.POSTERN_API_KEY! });

// One call. A real, send-and-receive-capable mailbox.
const inbox = await postern.inboxes.create({ display_name: "Support Bot" });

console.log(inbox.address); // agent7@x4p.mszazu.com
console.log(inbox.status);  // "live"
```

`inboxes.create()` returns an **`InboxHandle`** bound to that one address, so the rest of your agent
code reads naturally: `inbox.send(...)`, `inbox.messages()`, `inbox.waitForEmail(...)`,
`inbox.delete()`.

  Point your MCP host at the Postern server (see [Client configuration](https://docs.agents.mszazu.com/mcp/client-configuration/)),
then ask the agent to call `create_inbox`:

```json title="create_inbox (tool call)"
{
  "name": "create_inbox",
  "arguments": { "display_name": "Support Bot" }
}
```

```json title="result"
{
  "id": "inbox_3kP9wQ",
  "address": "agent7@x4p.mszazu.com",
  "status": "live"
}
```

Omit `username`/`domain` for an instant `agent@<label>.mszazu.com` address.

  ## Send from it

The mailbox is registered as an authenticated ACS sender at creation time, so mail from it is SPF +
DKIM aligned and doesn't bounce.

```bash frame="terminal"
curl -sS -X POST "$POSTERN_API_BASE_URL/v1/inboxes/agent7@x4p.mszazu.com/send" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ops@acme.test",
    "subject": "agent online",
    "text": "Reporting in."
  }'
```

  ```ts title="send.ts"
await inbox.send({
  to: "ops@acme.test",
  subject: "agent online",
  text: "Reporting in.",
});
```

  ```json title="send_email (tool call)"
{
  "name": "send_email",
  "arguments": {
    "address": "agent7@x4p.mszazu.com",
    "to": "ops@acme.test",
    "subject": "agent online",
    "text": "Reporting in."
  }
}
```

  ## Read what comes back

```bash frame="terminal"
curl -sS "$POSTERN_API_BASE_URL/v1/inboxes/agent7@x4p.mszazu.com/messages?direction=inbound" \
  -H "Authorization: Bearer $POSTERN_API_KEY"
```

  ```ts title="read.ts"
const { data: messages } = await inbox.messages({ direction: "inbound" });
const { data: threads } = await inbox.threads();
```

  ```json title="read_messages (tool call)"
{ "name": "read_messages", "arguments": { "address": "agent7@x4p.mszazu.com", "unread_only": true } }
```

  ## The whole flow

1. **Redeem** an enrollment key for a scoped agent key. POST /v1/enroll

2. **Create** a mailbox — instant on a shared subdomain. POST /v1/inboxes

3. **Send** from it, ACS-authenticated. POST /v1/inboxes/{addr}/send

4. **Receive** via `messages`, webhooks, or block on [`wait_for_email`](https://docs.agents.mszazu.com/quickstart/wait-for-email/). POST /v1/inboxes/{addr}/wait

5. **Delete** when the task is done — WildDuck account + ACS sender torn down. DELETE /v1/inboxes/{addr}

## Next

- [`wait_for_email`](https://docs.agents.mszazu.com/quickstart/wait-for-email/) — the OTP / verification flow.
- [Authentication & keys](https://docs.agents.mszazu.com/quickstart/authentication/) — enrollment keys, agent keys, scopes.
- [API reference](https://docs.agents.mszazu.com/api/overview/) — the full `/v1` contract.