API Reference: Workflows
Complete reference for the Workflows API including endpoints, request/response schemas, and examples.
Authentication
All workflow endpoints require a valid API key passed in the
Authorization header as Bearer <token>.Atomic Operations
Workflows are atomic: if any step fails, the entire workflow is rolled back. This prevents orphan inboxes or incomplete waits.
POST
/api/v1/workflows/create-inbox-and-waitCreate an inbox and immediately start a wait in one atomic call. Returns the inbox, wait result, and optional session.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| waitType | string | Required | The type of email to wait for (otp, magic_link, etc.). |
| timeoutSeconds | integer | Required | Maximum time to wait for the email.(default: 120) |
| ttlSeconds | integer | Optional | TTL for the created inbox.(default: 3600) |
| sessionId | string | Optional | Associate with an existing session. |
| metadata | object | Optional | Metadata for the created inbox. |
bash
curl -X POST https://agentinbox.in/api/v1/workflows/create-inbox-and-wait \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "waitType": "otp", "timeoutSeconds": 120, "ttlSeconds": 3600, "sessionId": "sess_abc", "metadata": { "workflow": "signup" } }'typescript
const workflow = await client.workflows.createInboxAndWait({ waitType: "otp", timeoutSeconds: 120, ttlSeconds: 3600, sessionId: "sess_abc", metadata: { workflow: "signup" },}); console.log(workflow.inbox.emailAddress);console.log(workflow.wait.result?.value); // "123456"python
workflow = client.workflows.create_inbox_and_wait( wait_type="otp", timeout_seconds=120, ttl_seconds=3600, session_id="sess_abc", metadata={"workflow": "signup"},) print(workflow.inbox.email_address)print(workflow.wait.result.value) # "123456"Responses
HTTP 201
{ "inbox": { "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "expiresAt": "2024-06-12T11:30:00Z" }, "wait": { "id": "wait_789", "status": "completed", "result": { "type": "otp", "value": "123456", "confidence": 0.98 } }, "session": { "id": "sess_abc", "name": "workflow-signup", "status": "active" }}HTTP 400
{ "error": "Invalid request", "message": "waitType is required"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 408
{ "inbox": { "id": "inb_123", "emailAddress": "...", "expiresAt": "..." }, "wait": { "id": "wait_789", "status": "timed_out", "result": null }, "session": null}HTTP 500
{ "error": "Internal server error", "message": "Workflow failed and was rolled back"}POST
/api/v1/workflows/signupComplete signup workflow: creates an inbox, waits for a verification email, extracts the code or link, and returns everything needed.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| waitType | string | Required | Expected email type. Use otp or magic_link for signup flows. |
| timeoutSeconds | integer | Required | Maximum time to wait for the verification email.(default: 300) |
| ttlSeconds | integer | Optional | TTL for the created inbox.(default: 3600) |
| sessionId | string | Optional | Associate with an existing session. |
| metadata | object | Optional | Metadata for the created inbox. |
bash
curl -X POST https://agentinbox.in/api/v1/workflows/signup \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "waitType": "magic_link", "timeoutSeconds": 300, "ttlSeconds": 3600, "sessionId": "sess_abc", "metadata": { "source": "landing-page" } }'typescript
const workflow = await client.workflows.signup({ waitType: "magic_link", timeoutSeconds: 300, ttlSeconds: 3600, sessionId: "sess_abc", metadata: { source: "landing-page" },}); console.log(workflow.inbox.emailAddress);console.log(workflow.wait.result?.value); // Magic link URLconsole.log(workflow.session?.id);python
workflow = client.workflows.signup( wait_type="magic_link", timeout_seconds=300, ttl_seconds=3600, session_id="sess_abc", metadata={"source": "landing-page"},) print(workflow.inbox.email_address)print(workflow.wait.result.value) # Magic link URLprint(workflow.session.id)Responses
HTTP 201
{ "inbox": { "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "expiresAt": "2024-06-12T11:30:00Z" }, "wait": { "id": "wait_789", "status": "completed", "result": { "type": "magic_link", "value": "https://example.com/verify?token=abc123", "confidence": 0.97 } }, "session": { "id": "sess_abc", "name": "workflow-signup", "status": "active" }}HTTP 400
{ "error": "Invalid request", "message": "waitType must be otp or magic_link"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 408
{ "inbox": { "id": "inb_123", "emailAddress": "...", "expiresAt": "..." }, "wait": { "id": "wait_789", "status": "timed_out", "result": null }, "session": null}HTTP 500
{ "error": "Internal server error", "message": "Workflow failed and was rolled back"}Schema: Workflow Response
All workflow responses share the same structure containing the created inbox, wait result, and optional session.
WorkflowResponse Object
{ "inbox": Inbox, "wait": Wait, "session": Session | null}Example Response
{ "inbox": { "id": "inb_123", "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "expiresAt": "2024-06-12T11:30:00Z" }, "wait": { "id": "wait_789", "status": "completed", "result": { "type": "otp", "value": "123456", "confidence": 0.98 } }, "session": { "id": "sess_abc", "name": "workflow-signup", "status": "active" }}