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, metadata, 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) |
| metadata | object | Optional | User-defined key-value pairs for tracking or tagging. |
| 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, "metadata": { "workflow": "signup" }, "sessionId": "sess_abc" }'typescript
const inbox = await client.inboxes.create({ ttlSeconds: 3600, metadata: { workflow: "signup" }, sessionId: "sess_abc",}); console.log(inbox.emailAddress); // "k3v9x2m4q7tz@agentinbox.in"python
inbox = client.inboxes.create( ttl_seconds=3600, metadata={"workflow": "signup"}, session_id="sess_abc",) 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", "metadata": { "workflow": "signup" }, "sessionId": "sess_abc"}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) |
| offset | integer | Optional | Number of results to skip.(default: 0) |
| 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, offset: 0, status: "active",}); console.log(inboxes.data.length);python
inboxes = client.inboxes.list( limit=20, offset=0, status="active",) print(len(inboxes.data))Responses
HTTP 200
{ "data": [ { "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "status": "active", "expiresAt": "2024-06-12T11:30:00Z" } ], "pagination": { "limit": 20, "offset": 0, "total": 42 }}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", "metadata": {}, "sessionId": null}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 "metadata": object, // User-defined key-value pairs "sessionId": string | null}