# agentsbase — Email for AI Agents Give your AI agent its own email. Create mailboxes, send & receive emails, auto-extract verification codes. ## Setup ```bash export AGENTSBASE_URL="https://agentsbase.net" export AGENTSBASE_API_KEY="" ``` **If you don't have an API key yet**, ask the user to visit https://agentsbase.net/login and register with their email. After registration, they'll see an API key (starts with `ak_`) — ask them to paste it here. > **Security**: Keep your API key private. Do not commit it to version control. Use environment variables. You can rotate your key with `POST /api/keys/rotate` or generate short-lived tokens with `POST /api/keys/token`. ## Before You Start: Check Existing Mailboxes **ALWAYS check for existing mailboxes first before creating a new one.** The free tier only allows 3 mailboxes. ```bash curl -s -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/info" | jq '{mailboxes: .mailboxes, usage: .usage, limits: .limits}' ``` If you already have a mailbox, **reuse it** — all API Key endpoints (`/api/keys/*`) let you operate on any mailbox you own without needing the original mailbox token. ## Quick Start ### 1. Register a mailbox (only if needed) Skip this step if you already have a mailbox from `/api/keys/info`. **When the user asks to create a mailbox**, ask them what name they'd like (e.g. `alice`, `support`). If they don't have a preference, create one with a random name by sending an empty body. ```bash # With a custom name (ask the user first): RESULT=$(curl -s -X POST \ -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ -H "Content-Type: application/json" \ "$AGENTSBASE_URL/api/register" -d '{"name":"alice"}') # Or with a random name: RESULT=$(curl -s -X POST \ -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ -H "Content-Type: application/json" \ "$AGENTSBASE_URL/api/register" -d '{}') MAILBOX=$(echo "$RESULT" | jq -r '.mailbox') echo "Mailbox: $MAILBOX" ``` With `name`: creates `alice@agentsbase.net`. Without: creates a random address like `swift-fox-1234@agentsbase.net`. Returns: `{ mailbox, token }` ### 2. Send an email ```bash curl -s -X POST \ -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ -H "Content-Type: application/json" \ "$AGENTSBASE_URL/api/keys/send" \ -d '{"from":"'$MAILBOX'","to":["user@example.com"],"subject":"Hello","text":"World"}' ``` The `from` address must be a mailbox you own. Body fields: `from` (required), `to` (required, array), `subject`, `text`, `html`, `reply_to`, `attachments`. Returns: `{ id, from }` **Important**: Always send the JSON body as UTF-8. For non-ASCII content (Chinese, Japanese, etc.), send the raw Unicode characters directly in the JSON string — do NOT escape or encode them. ### 2b. Send with HTML and attachments ```bash curl -s -X POST \ -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ -H "Content-Type: application/json" \ "$AGENTSBASE_URL/api/keys/send" \ -d '{ "from":"'$MAILBOX'", "to":["user@example.com"], "subject":"Invoice", "html":"

Invoice #123

Amount: $50

", "attachments":[ {"filename":"invoice.pdf","content":"","content_type":"application/pdf"} ] }' ``` Note: attachment `content` should be base64-encoded. ### 3. Check inbox ```bash curl -s -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/inbox?mailbox=$MAILBOX" | jq '.emails' ``` Query params: `mailbox` (required), `direction` (`inbound`/`outbound`), `query` (search subject/body/sender), `since` (ISO 8601), `limit` (default 20, max 100), `offset` (default 0). Returns: `{ emails: [{ id, from_address, to_address, subject, body_text, code, direction, status, has_attachments, received_at, ... }] }` Search example: ```bash curl -s -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/inbox?mailbox=$MAILBOX&query=reset+password&since=2026-01-01T00:00:00Z" | jq '.emails' ``` ### 4. Wait for verification code ```bash SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ) # ... use $MAILBOX to sign up somewhere ... CODE=$(curl -s -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/code?mailbox=$MAILBOX&timeout=55&since=$SINCE" | jq -r '.code') echo "Code: $CODE" ``` Long-polls up to `timeout` seconds (default 30, max 55). Codes are auto-extracted (4–8 digit numbers from subject/body). Returns: `{ id, code, from, subject, received_at }` ### 5. Get email detail ```bash curl -s -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/email?id=EMAIL_ID" | jq ``` Returns: `{ id, from_address, to_address, subject, body_text, body_html, code, direction, status, received_at, attachments: [{ filename, content_type, size_bytes }] }` ### 6. Rotate API key ```bash curl -s -X POST -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/rotate" | jq ``` Returns: `{ key, previous_key_prefix }`. The old key is immediately invalidated. ### 7. Generate short-lived token ```bash curl -s -X POST -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ -H "Content-Type: application/json" \ "$AGENTSBASE_URL/api/keys/token" -d '{"expires_in": 3600}' | jq ``` Creates a session token (`st_...`) valid for `expires_in` seconds (default & max: 86400 = 24h). Use it as a Bearer token like the API key, but with limited lifetime. Returns: `{ token, expires_at }` ### 8. Webhooks Receive real-time notifications when emails arrive. ```bash # Create webhook curl -s -X POST -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ -H "Content-Type: application/json" \ "$AGENTSBASE_URL/api/keys/webhooks" \ -d '{"url":"https://your-server.com/webhook","events":"email.received"}' # List webhooks curl -s -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/webhooks" | jq # Delete webhook curl -s -X DELETE -H "Authorization: Bearer $AGENTSBASE_API_KEY" \ "$AGENTSBASE_URL/api/keys/webhooks?id=WEBHOOK_ID" ``` Webhook payloads are signed with the `secret` returned on creation (HMAC-SHA256 in `X-Webhook-Signature` header). ## API Reference All endpoints use `Authorization: Bearer ` header. | Endpoint | Method | Description | |----------|--------|-------------| | `/api/keys/info` | GET | Account info, usage, mailbox list | | `/api/register` | POST | Create a new mailbox. Body: `{name?, domain?}` | | `/api/keys/send` | POST | Send email. Body: `{from, to, subject, text, html?, reply_to?, attachments?}` | | `/api/keys/inbox?mailbox=X` | GET | List emails. Params: `direction, query, since, limit, offset` | | `/api/keys/email?id=X` | GET | Get full email detail with body and attachments | | `/api/keys/code?mailbox=X` | GET | Wait for verification code. Params: `timeout, since` | | `/api/keys/rotate` | POST | Rotate API key (invalidates current key) | | `/api/keys/token` | POST | Generate short-lived session token. Body: `{expires_in?}` | | `/api/keys/webhooks` | POST | Create webhook. Body: `{url, events?}` | | `/api/keys/webhooks` | GET | List webhook subscriptions | | `/api/keys/webhooks?id=X` | DELETE | Delete a webhook | ## Notes - **Reuse mailboxes**: Always check `/api/keys/info` first. Only register a new one if you have none. - The `from` address in send must be a mailbox you own. - Verification codes are auto-extracted from email subject and body (4–8 digit numbers). - Free tier: 500 sends/month, 1,000 receives/month, up to 3 mailboxes. - API responses may include a `usage_alert` field when you're approaching plan limits.