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/workflow/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) |
| purpose | string | Optional | Human-readable purpose for the created inbox. |
bash
curl -X POST https://agentinbox.in/api/v1/workflow/create-inbox-and-wait \ -H "Authorization: Bearer $AGENTINBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "waitType": "otp", "timeoutSeconds": 120, "ttlSeconds": 3600, "purpose": "signup" }'typescript
const workflow = await client.waits.createInboxAndWait({ waitType: "otp", timeoutSeconds: 120, ttlSeconds: 3600, purpose: "signup",}); console.log(workflow.inbox.emailAddress);console.log(workflow.wait.result?.value); // "123456"python
import osimport requests resp = requests.post( "https://agentinbox.in/api/v1/workflow/create-inbox-and-wait", headers={"Authorization": f"Bearer {os.environ['AGENTINBOX_API_KEY']}"}, json={"waitType": "otp", "timeoutSeconds": 120, "ttlSeconds": 3600},)workflow = resp.json() print(workflow["inbox"]["emailAddress"])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 } }, "instructions": { "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "useThisEmail": "Use k3v9x2m4q7tz@agentinbox.in for the signup form." }}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": "timeout", "result": null }, "session": null}HTTP 500
{ "error": "Internal server error", "message": "Workflow failed and was rolled back"}POST
/api/v1/workflow/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) |
| serviceName | string | Optional | Name of the service being tested. |
bash
curl -X POST https://agentinbox.in/api/v1/workflow/signup \ -H "Authorization: Bearer $AGENTINBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "waitType": "magic_link", "timeoutSeconds": 300, "serviceName": "Acme" }'typescript
const workflow = await client.waits.signup({ waitType: "magic_link", timeoutSeconds: 300, serviceName: "Acme",}); console.log(workflow.inbox.emailAddress);console.log(workflow.wait.result?.value); // Magic link URLconsole.log(workflow.instructions.emailAddress);python
import osimport requests resp = requests.post( "https://agentinbox.in/api/v1/workflow/signup", headers={"Authorization": f"Bearer {os.environ['AGENTINBOX_API_KEY']}"}, json={"waitType": "magic_link", "timeoutSeconds": 300},)workflow = resp.json() print(workflow["inbox"]["emailAddress"])print(workflow["wait"]["result"]["value"])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": "timeout", "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 } }, "instructions": { "emailAddress": "k3v9x2m4q7tz@agentinbox.in", "useThisEmail": "Use k3v9x2m4q7tz@agentinbox.in for the signup form." }}