Workflows

Workflows combine multiple API calls into a single, atomic operation. Use them to simplify common automation patterns.

Atomic Operations

Workflows are atomic: if any step fails, the entire workflow is rolled back. This prevents orphan inboxes or incomplete operations.

create-inbox-and-wait

The most common workflow. Creates a new inbox and immediately starts a wait for the expected email type.

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
  }'

typescript

const workflow = await client.workflows.createInboxAndWait({
  waitType: "otp",
  timeoutSeconds: 120,
  ttlSeconds: 3600,
});
 
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,
)
 
print(workflow.inbox.email_address)
print(workflow.wait.result.value)  # "123456"

POST/api/v1/workflows/create-inbox-and-wait

Create an inbox and wait for an email in one atomic call

Parameters

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)
metadata	object	Optional	Optional metadata for the created inbox.

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"
  }
}

signup

A complete signup workflow that creates an inbox, waits for a verification email, extracts the code or link, and returns everything needed to complete the signup.

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
  }'

typescript

const workflow = await client.workflows.signup({
  waitType: "magic_link",
  timeoutSeconds: 300,
  ttlSeconds: 3600,
});
 
console.log(workflow.inbox.emailAddress);
console.log(workflow.wait.result?.value); // Magic link URL
console.log(workflow.session?.id);        // Session tracking

Workflow Response

All workflow responses include the created inbox, wait result, and optionally a session.

Workflow 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"
  }
}