API Reference

Inboxes

Create and manage email inboxes for your AI agents. Temporary inboxes require no authentication; persistent inboxes require an API key.

Inbox Object

Field	Type	Description
id	uuid	Unique inbox identifier
user_id	uuid?	Owner user ID (null for temporary inboxes)
address	string	Full email address (e.g. abc123@agentemail.email)
domain	string	Email domain
token	string	Access token (temporary inboxes only)
type	string	"temporary" or "persistent"
expires_at	timestamp?	Expiry time (temporary inboxes only)
created_at	timestamp	Creation time (ISO 8601)

Public Endpoints

POST/api/v1/public/inbox

Create Temporary Inbox

Create an anonymous temporary inbox. No authentication required. The inbox auto-expires after 60 minutes by default.

cURL

curl -X POST https://api.agentemail.email/api/v1/public/inbox

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "address": "abc123@agentemail.email",
    "token": "temp_xYz9kL...",
    "type": "temporary",
    "expires_at": "2026-03-27T22:00:00Z"
  }
}

GET/api/v1/public/inbox/{token}

Get Temporary Inbox

Retrieve a temporary inbox and all its messages by token.

Path Parameters

tokenstring

Inbox access token returned on creation

cURL

curl https://api.agentemail.email/api/v1/public/inbox/temp_xYz9kL...

Response

{
  "success": true,
  "data": {
    "address": "abc123@agentemail.email",
    "messages": [...]}
}

GET/api/v1/public/inbox/{token}/latest

Get Latest Message

Get the most recent message in a temporary inbox.

Path Parameters

tokenstring

Inbox access token

cURL

curl https://api.agentemail.email/api/v1/public/inbox/temp_xYz9kL.../latest

GET/api/v1/public/inbox/{token}/code

Extract Verification Code

Auto-extract a verification code from the latest email in the inbox.

Path Parameters

tokenstring

Inbox access token

cURL

curl https://api.agentemail.email/api/v1/public/inbox/temp_xYz9kL.../code

Response

{
  "success": true,
  "code": "847293",
  "text": "Your verification code is 847293"
}

DELETE/api/v1/public/inbox/{token}

Delete Temporary Inbox

Delete a temporary inbox and all its messages immediately.

Path Parameters

tokenstring

Inbox access token

cURL

curl -X DELETE https://api.agentemail.email/api/v1/public/inbox/temp_xYz9kL...

Authenticated Endpoints

POST/api/v1/inboxesAPI Key

Create Inbox

Create a new persistent or temporary inbox. Persistent inboxes don't expire and support sending emails.

Request Body

typestring

"persistent" or "temporary"

prefixstring

Custom email prefix (optional, random if omitted)

domainstring

Custom domain (optional, defaults to agentemail.email)

ttl_minutesint

TTL for temporary inboxes (optional)

cURL

curl -X POST https://api.agentemail.email/api/v1/inboxes \
  -H "X-API-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"type":"persistent","prefix":"my-agent"}'

Response

{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "address": "my-agent@agentemail.email",
    "type": "persistent"
  }
}

GET/api/v1/inboxesAPI Key

List Inboxes

List all inboxes owned by the authenticated user.

cURL

curl https://api.agentemail.email/api/v1/inboxes \
  -H "X-API-Key: ak_your_key"

GET/api/v1/inboxes/{id}API Key

Get Inbox

Get details of a specific inbox.

Path Parameters

iduuid

Inbox ID

cURL

curl https://api.agentemail.email/api/v1/inboxes/{id} \
  -H "X-API-Key: ak_your_key"

PATCH/api/v1/inboxes/{id}API Key

Update Inbox

Update inbox settings. Currently supports extending TTL for temporary inboxes.

Path Parameters

iduuid

Inbox ID

Request Body

ttl_minutesint

New TTL in minutes

cURL

curl -X PATCH https://api.agentemail.email/api/v1/inboxes/{id} \
  -H "X-API-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"ttl_minutes":120}'

DELETE/api/v1/inboxes/{id}API Key

Delete Inbox

Permanently delete an inbox and all its messages.

Path Parameters

iduuid

Inbox ID

cURL

curl -X DELETE https://api.agentemail.email/api/v1/inboxes/{id} \
  -H "X-API-Key: ak_your_key"