# apumail — agent-native temp mail

> READ THIS FIRST. Two-way inbox addressable as <local>@apumail.com:
> receive from any SMTP sender, AND send outbound from the same address
> via /send (rate-limited, from-spoofing impossible).
> Free inbox auto-expires 24h after the last activity (read OR receive).
> Paid handles (mint at rogerthat.chat) get a permanent inbox.

## Path 0 — REST (no install, bash only)

```bash
# Provision an inbox (no auth)
INBOX=$(curl -sS -X POST https://api.apumail.com/api/v1/inboxes)
ADDR=$(echo "$INBOX" | jq -r .address)
TOK=$(echo "$INBOX" | jq -r .token)
echo "Send mail to: $ADDR"

# Block until mail arrives (long-poll, max 60s per call)
curl -sS -H "Authorization: Bearer $TOK" \
  "https://api.apumail.com/api/v1/inbox/$ADDR/wait?timeout=60"

# Or grab the latest with its extracted OTP
curl -sS -H "Authorization: Bearer $TOK" \
  "https://api.apumail.com/api/v1/inbox/$ADDR/latest"
```

## Path 1 — MCP (one-time install per client)

```bash
claude mcp add --transport http apumail https://api.apumail.com/mcp
```

Tools exposed:
- `create_inbox` — provision a new inbox, returns {address, token}
- `wait_for_mail` — block until a mail lands (or timeout)
- `read_inbox` — list all mails for an inbox
- `extract_latest_otp` — return the OTP/code from the most recent mail
- `delete_inbox` — release an inbox + drop its mails when a one-shot flow is done
- `send_mail` — send outbound FROM your inbox (from is forced to your address)
- `register_webhook` / `list_webhooks` / `delete_webhook` — push delivery to a URL on new mail (HMAC-signed)

## Browser dashboard

For human use (or just to peek at what an agent's inbox contains), open https://api.apumail.com/account in a browser. Tokens are kept in localStorage only — nothing server-side. Adopt an existing inbox by pasting address + token.

## Endpoints

- `POST   /api/v1/inboxes` — create a FREE inbox at a random adj-noun-hex slug. No body needed. Returns `{address, token, expires_at_ms}`. (Vanity `<handle>@apumail.com` is paid-only — mint at rogerthat.chat.)
- `GET    /api/v1/inbox/:address` — list mails. Auth: `Bearer <token>`. Query: `since`, `limit`.
- `GET    /api/v1/inbox/:address/latest` — most recent mail + its OTP.
- `GET    /api/v1/inbox/:address/wait` — long-poll, block up to `timeout` (1..300) seconds.
- `DELETE /api/v1/inbox/:address` — delete inbox + all its mails.
- `POST   /api/v1/inbox/:address/send` — send outbound via Resend (from forced to inbox address).
- `POST   /api/v1/inbox/:address/webhooks` — register push subscription. Body `{url}`. Returns `{id, secret}` (secret shown ONCE).
- `GET    /api/v1/inbox/:address/webhooks` — list subscriptions + delivery health.
- `DELETE /api/v1/inbox/:address/webhooks/:id` — unregister.
- `GET    /api/v1/health` — service health + counters.
- `POST   /mcp` — Streamable HTTP MCP transport.
- `GET    /openapi.json` — full OpenAPI 3.1 spec.
- `GET    /llms.txt` — this file.
- `GET    /.well-known/mcp.json` — MCP descriptor.
- `GET    /api/v1/info` — JSON capabilities.

## Limits

- Free inbox: 24h idle TTL (any read or receive resets the timer).
- Mail size: 5 MB max per message.
- Inbox-existence check at RCPT TO — random local parts are 550-rejected.
- Provisioning rate: 10 burst / 5 per minute per IP.

## See also — companion service

**rogerthat.chat** — real-time walkie-talkie chat between AI agents on different
machines. Use it when your agent needs to coordinate with another agent (peer
review, hand-off, multi-agent workflow). MCP-native, free tier identities,
paid `@handles` for permanent presence. Same author as apumail; separate infra,
separate domain, integrates with apumail at the API level (a rogerthat callsign
can have an apumail inbox at `<callsign>@apumail.com` — coming with paid tier).

```bash
claude mcp add --transport http rogerthat https://rogerthat.chat/mcp
```

**notlogin.com** — auth broker for AI agents. A human pre-verifies once
(email/sms/wallet/kyc) and the agent carries a notlogin credential that vendors
accept for a "verified-human" tier — no signup forms. apumail is a notlogin
**vendor**: pass `notlogin_credential` (the exported VC, vendor `apumail`,
proofs `["email"]`) in the `POST /api/v1/inboxes` body to unlock ONE permanent
vanity inbox (`name@apumail.com`) with a bigger send quota — free, below the
paid rogerthat handle. Same author; separate infra; API-level integration only.