API Reference: Inboxes
Complete reference for the Inboxes API including endpoints, request/response schemas, and examples.
Authentication
All inbox endpoints require a valid API key passed in the
Authorization header as Bearer <token>.POST
/api/v1/inboxesCreate a new temporary email inbox with optional TTL, purpose, and session association.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| ttlSeconds | integer | Optional | Time-to-live in seconds. After this period, the inbox expires.(default: 3600) |
| purpose | string | Optional | Human-readable purpose for tracking this inbox. |
| sessionId | string | Optional | Associate this inbox with an existing session. |
bash
curl -X POST https://agentinbox.in/api/v1/inboxes \ -H "Authorization: Bearer $AGENTINBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ttlSeconds": 3600, "purpose": "signup", "sessionId": "00000000-0000-4000-8000-000000000004" }'typescript
const inbox = await client.inboxes.create({ ttlSeconds: 3600, purpose: "signup", sessionId: "00000000-0000-4000-8000-000000000004",}); console.log(inbox.emailAddress); // "k3v9x2m4q7tz@agentinbox.in"python
inbox = client.inboxes.create( ttl_seconds=3600, purpose="signup", session_id="00000000-0000-4000-8000-000000000004",) print(inbox.email_address) # "k3v9x2m4q7tz@agentinbox.in"Responses
HTTP 201
{ "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "status": "active", "ttlSeconds": 3600, "expiresAt": "2024-06-12T11:30:00Z", "createdAt": "2024-06-12T10:30:00Z"}HTTP 400
{ "error": "Invalid request", "message": "ttlSeconds must be a positive integer"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 500
{ "error": "Internal server error", "message": "Failed to create inbox"}GET
/api/v1/inboxesList all inboxes with pagination support. Filter by status or retrieve all.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | Optional | Number of results per page.(default: 20) |
| cursor | string | Optional | Pagination cursor from the previous response. |
| status | string | Optional | Filter by inbox status. One of active or expired. |
bash
curl -s https://agentinbox.in/api/v1/inboxes \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const inboxes = await client.inboxes.list({ limit: 20, status: "active",}); console.log(inboxes.data.length);python
inboxes = client.inboxes.list(limit=20) print(len(inboxes))Responses
HTTP 200
{ "object": "list", "data": [ { "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "status": "active", "expiresAt": "2024-06-12T11:30:00Z" } ], "nextCursor": null, "hasMore": false}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 500
{ "error": "Internal server error", "message": "Failed to list inboxes"}GET
/api/v1/inboxes/{id}Retrieve a specific inbox by its unique ID.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique inbox ID (e.g., inb_123). |
bash
curl -s https://agentinbox.in/api/v1/inboxes/inb_123 \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const inbox = await client.inboxes.get("inb_123");console.log(inbox.status);python
inbox = client.inboxes.get("inb_123")print(inbox.status)Responses
HTTP 200
{ "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "status": "active", "ttlSeconds": 3600, "expiresAt": "2024-06-12T11:30:00Z", "createdAt": "2024-06-12T10:30:00Z"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Inbox not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to retrieve inbox"}DELETE
/api/v1/inboxes/{id}Delete an inbox immediately. This action is irreversible.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique inbox ID to delete. |
bash
curl -X DELETE https://agentinbox.in/api/v1/inboxes/inb_123 \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
await client.inboxes.delete("inb_123");python
client.inboxes.delete("inb_123")Responses
HTTP 204
// No bodyHTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Inbox not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to delete inbox"}Schema: Inbox
The Inbox object represents a temporary email address.
Inbox Object
{ "id": string, // Unique inbox ID (e.g., "inb_123") "emailAddress": string, // Full email address "status": "active" | "expired", "ttlSeconds": number, // TTL in seconds "expiresAt": string, // ISO 8601 timestamp "createdAt": string // ISO 8601 timestamp}