API Reference

Agent Inbox provides disposable email addresses for AI agents via a simple REST API.

Authentication

All API requests require a Bearer token. You can create API keys from the Settings page in your dashboard. Keys are prefixed with ak_.

Authorization: Bearer ak_your_api_key_here

Create Inbox

POST /api/v1/inboxes

Creates a new disposable email inbox. Optionally attach a note or tags.

Request Body

{
  "note": "optional description",
  "tags": ["signup", "testing"]
}

Response

{
  "id": "inbox_abc123",
  "address": "abc123@agents-inbox.com",
  "note": "optional description",
  "tags": ["signup", "testing"],
  "createdAt": "2026-01-15T10:30:00.000Z"
}

Example

curl -X POST https://agents-inbox.com/api/v1/inboxes \
  -H "Authorization: Bearer ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"note": "signup test", "tags": ["testing"]}'

List Inboxes

GET /api/v1/inboxes

Returns all inboxes for your account. Optionally filter by tag.

Query Parameters

tag — Filter inboxes by tag

Example

curl https://agents-inbox.com/api/v1/inboxes?tag=testing \
  -H "Authorization: Bearer ak_your_api_key"

Get Inbox

GET /api/v1/inboxes/:id

Returns a single inbox by ID.

Example

curl https://agents-inbox.com/api/v1/inboxes/inbox_abc123 \
  -H "Authorization: Bearer ak_your_api_key"

Delete Inbox

DELETE /api/v1/inboxes/:id

Deletes an inbox and all its messages permanently.

Example

curl -X DELETE https://agents-inbox.com/api/v1/inboxes/inbox_abc123 \
  -H "Authorization: Bearer ak_your_api_key"

List Messages

GET /api/v1/inboxes/:id/messages

Returns messages for a specific inbox.

Query Parameters

since — ISO 8601 timestamp to filter messages after
unseen — Set to true to only return unseen messages

Example

curl "https://agents-inbox.com/api/v1/inboxes/inbox_abc123/messages?unseen=true" \
  -H "Authorization: Bearer ak_your_api_key"

Cross-Inbox Query

GET /api/v1/messages

Query messages across multiple inboxes at once.

Query Parameters

inbox_ids — Comma-separated list of inbox IDs
since — ISO 8601 timestamp to filter messages after

Example

curl "https://agents-inbox.com/api/v1/messages?inbox_ids=inbox_abc,inbox_def&since=2026-01-15T00:00:00Z" \
  -H "Authorization: Bearer ak_your_api_key"