API Reference: Waits
Complete reference for the Waits API including endpoints, request/response schemas, and examples.
Authentication
All wait endpoints require a valid API key passed in the
Authorization header as Bearer <token>.POST
/api/v1/waitsCreate a wait on an inbox. Poll or stream the wait to receive the extracted result when the email arrives.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| inboxId | string | Required | The inbox to monitor for incoming emails. |
| type | string | Required | Wait type. One of otp, magic_link, password_reset, email, check. |
| timeoutSeconds | integer | Required | Maximum seconds to wait before timing out.(default: 120) |
| sessionId | string | Optional | Associate this wait with an existing session. |
bash
curl -X POST https://agentinbox.in/api/v1/waits \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inboxId": "inb_123", "type": "otp", "timeoutSeconds": 120, "sessionId": "sess_abc" }'typescript
const wait = await client.waits.create({ inboxId: "inb_123", type: "otp", timeoutSeconds: 120, sessionId: "sess_abc",}); console.log(wait.id); // "wait_789"python
wait = client.waits.create( inbox_id="inb_123", type="otp", timeout_seconds=120, session_id="sess_abc",) print(wait.id) # "wait_789"Responses
HTTP 201
{ "id": "wait_789", "inboxId": "inb_123", "type": "otp", "status": "pending", "timeoutSeconds": 120, "createdAt": "2024-06-12T10:00:05Z", "expiresAt": "2024-06-12T10:02:05Z", "result": null, "sessionId": "sess_abc"}HTTP 400
{ "error": "Invalid request", "message": "timeoutSeconds must be between 1 and 600"}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 create wait"}GET
/api/v1/waits/{id}Get the current status of a wait. Poll this endpoint to check if the wait is completed, timed out, or still pending.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique wait ID. |
bash
curl -s https://agentinbox.in/api/v1/waits/wait_789 \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const wait = await client.waits.get("wait_789");console.log(wait.status, wait.result?.value);python
wait = client.waits.get("wait_789")print(wait.status, wait.result.value)Responses
HTTP 200
{ "id": "wait_789", "inboxId": "inb_123", "type": "otp", "status": "pending", "timeoutSeconds": 120, "createdAt": "2024-06-12T10:00:05Z", "expiresAt": "2024-06-12T10:02:05Z", "result": null, "sessionId": "sess_abc"}HTTP 200
{ "id": "wait_789", "inboxId": "inb_123", "type": "otp", "status": "completed", "timeoutSeconds": 120, "createdAt": "2024-06-12T10:00:05Z", "expiresAt": "2024-06-12T10:02:05Z", "result": { "type": "otp", "value": "123456", "confidence": 0.98 }, "sessionId": "sess_abc"}HTTP 200
{ "id": "wait_789", "inboxId": "inb_123", "type": "otp", "status": "timed_out", "timeoutSeconds": 120, "createdAt": "2024-06-12T10:00:05Z", "expiresAt": "2024-06-12T10:02:05Z", "result": null, "sessionId": "sess_abc"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Wait not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to retrieve wait"}DELETE
/api/v1/waits/{id}Cancel an active wait. This immediately stops the wait and sets its status to canceled.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique wait ID to cancel. |
bash
curl -X DELETE https://agentinbox.in/api/v1/waits/wait_789 \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
await client.waits.cancel("wait_789");python
client.waits.cancel("wait_789")Responses
HTTP 204
// No bodyHTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Wait not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to cancel wait"}GET
/api/v1/waits/{id}/streamStream wait status updates via Server-Sent Events (SSE). Receive real-time updates without polling.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique wait ID to stream. |
bash
curl -N -H "Authorization: Bearer $AgentInbox_API_KEY" \ https://agentinbox.in/api/v1/waits/wait_789/streamtypescript
const stream = await client.waits.stream("wait_789");for await (const event of stream) { console.log(event.status, event.result?.value);}python
stream = client.waits.stream("wait_789")for event in stream: print(event.status, event.result.value)Responses
HTTP 200
event: status_updatedata: {"status":"pending","result":null} event: status_updatedata: {"status":"completed","result":{"type":"otp","value":"123456","confidence":0.98}}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Wait not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to stream wait"}Polling vs Streaming
Use polling (GET by ID) for simple scripts and streaming (GET /stream) for real-time applications. Streaming reduces latency and API calls.
Schema: Wait
The Wait object represents an asynchronous expectation for an incoming email.
Wait Object
{ "id": string, "inboxId": string, "type": "otp" | "magic_link" | "password_reset" | "email" | "check", "status": "pending" | "completed" | "timed_out" | "canceled", "timeoutSeconds": number, "createdAt": string, "expiresAt": string, "result": { "type": string, "value": string, "confidence": number } | null, "sessionId": string | null}