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/workflow/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.waits.createInboxAndWait({
  waitType: "otp",
  timeoutSeconds: 120,
  ttlSeconds: 3600,
});
 
console.log(workflow.inbox.emailAddress);
console.log(workflow.wait.result?.value); // "123456"

python

import os
import 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"

POST/api/v1/workflow/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)
purpose	string	Optional	Optional purpose 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
    }
  },
  "instructions": {
    "emailAddress": "k3v9x2m4q7tz@agentinbox.in",
    "useThisEmail": "Use k3v9x2m4q7tz@agentinbox.in for the signup form."
  }
}

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/workflow/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.waits.signup({
  waitType: "magic_link",
  timeoutSeconds: 300,
});
 
console.log(workflow.inbox.emailAddress);
console.log(workflow.wait.result?.value); // Magic link URL
console.log(workflow.instructions.emailAddress);

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
    }
  },
  "instructions": {
    "emailAddress": "k3v9x2m4q7tz@agentinbox.in",
    "useThisEmail": "Use k3v9x2m4q7tz@agentinbox.in for the signup form."
  }
}