Lumbox

https://lumbox.co/docs
Admin
Lumbox provides AI agents with real email addresses, offering programmatic inbox creation, OTP...
Tokens:38,462
Snippets:395
Trust Score:5.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Development Servers

Source: https://lumbox.co/docs/getting-started

Commands to start the full development environment or individual application components.

```bash
# Start everything (API + dashboard)
bun run dev

# Or start individual apps
cd apps/api && bun run dev       # API on :3000
cd apps/web-new && bun run dev   # Dashboard on :3001
cd apps/mcp-server && bun run dev      # MCP stdio mode
cd apps/mcp-server && bun run dev:http # MCP HTTP mode on :3002
```

--------------------------------

### Docker Compose setup for Steel Browser

Source: https://lumbox.co/docs/browser

Recommended Docker setup for Steel Browser. The docker-compose.yml defines the Steel service with required ports, volume, shared memory, and resource limits; then `docker compose up -d` starts it. Requires Docker and at least 4GB RAM (2GB for Steel).

```yaml
# docker-compose.yml
services:
  steel:
    image: ghcr.io/steel-dev/steel-browser:latest
    restart: always
    ports:
      - "3000:3000"   # Steel API
      - "9223:9223"   # Chrome DevTools Protocol
    volumes:
      - ./data/steel-cache:/app/.cache
    shm_size: "2gb"
    cap_add:
      - SYS_ADMIN
    deploy:
      resources:
        limits:
          memory: 2G
```

```bash
docker compose up -d
```

--------------------------------

### Install Docker and clone repository

Source: https://lumbox.co/docs/deployment

Commands to install Docker and clone the Lumbox repository on the Hetzner server.

```bash
# Docker
curl -fsSL https://get.docker.com | sh

# Clone repo
git clone https://github.com/Lumbox/Lumbox.git
cd Lumbox
```

--------------------------------

### Install Lumbox Python SDK

Source: https://lumbox.co/docs/sdk-quickstart

Install the Lumbox Python SDK via pip.

```bash
pip install lumbox
```

--------------------------------

### Install Lumbox Node.js SDK

Source: https://lumbox.co/docs/sdk-quickstart

Install the Lumbox Node.js SDK via npm.

```bash
npm install lumbox
```

--------------------------------

### Namespace Isolation Examples

Source: https://lumbox.co/docs/credentials

Examples of defining credentials for different users using the namespace field.

```json
{
  "service": "github.com",
  "identifier": "fred@example.com",
  "value": "fred-password",
  "namespace": "agent:fred"
}
```

```json
{
  "service": "github.com",
  "identifier": "jane@example.com",
  "value": "jane-password",
  "namespace": "agent:jane"
}
```

--------------------------------

### Copy environment file

Source: https://lumbox.co/docs/deployment

Copies the example environment file to .env for configuration.

```bash
cp .env.example .env
```

--------------------------------

### GET /v1/routing-rules

Source: https://lumbox.co/docs/api-reference

Lists all routing rules.

```APIDOC
## GET /v1/routing-rules

### Description
Lists all routing rules.

### Method
GET

### Endpoint
/v1/routing-rules
```

--------------------------------

### Example AI Agent Commands

Source: https://lumbox.co/docs/mcp

Sample prompts for an AI agent once the Lumbox MCP server is connected.

```text
"Create an inbox called github-bot"
"Send an email to user@example.com saying hello"
"Wait for a verification email from github.com"
"What's the OTP code in my latest email?"
```

--------------------------------

### List Routing Rules (GET /v1/routing-rules)

Source: https://lumbox.co/docs/api-reference

Lists all routing rules.

```http
GET /v1/routing-rules
```

--------------------------------

### Audit Log API (GET /v1/credentials/audit?limit=50)

Source: https://lumbox.co/docs/credentials

Retrieves the audit log of credential accesses. The example shows a log entry for a use_in_browser action with metadata and timestamps.

```http
GET /v1/credentials/audit?limit=50
```

```json
{
  "data": [
    {
      "id": "log_abc",
      "credential_id": "cred_abc123",
      "action": "use_in_browser",
      "metadata": { "service": "github.com", "identifier": "bot@example.com" },
      "created_at": "2026-03-15T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Clone and Configure Lumbox

Source: https://lumbox.co/docs/getting-started

Commands to clone the repository, install dependencies, and initialize the environment configuration file.

```bash
# Clone and install
git clone https://github.com/Lumbox/Lumbox.git
cd Lumbox
bun install

# Configure environment
cp .env.example .env
# Edit .env - at minimum set DATABASE_URL
```

--------------------------------

### GET /v1/webhooks

Source: https://lumbox.co/docs/webhooks

Lists all registered webhooks.

```APIDOC
## GET /v1/webhooks

### Description
Lists all registered webhooks.

### Method
GET

### Endpoint
/v1/webhooks

### Parameters
No parameters are documented.

### Request Example
No request example is provided in the source.

### Response
#### Success Response (200)
No response body is explicitly documented.

#### Response Example
No response example is provided in the source.

```

--------------------------------

### Build and deploy with Docker Compose

Source: https://lumbox.co/docs/deployment

Starts the API, Haraka mail server, and MCP HTTP server on ports 3000, 25, and 3002 respectively.

```bash
cd apps/mail-server
docker compose up -d --build
```

--------------------------------

### Send Email - curl Example

Source: https://lumbox.co/docs/sending

Example curl command to send an email to the inbox `inb_abc123`. Uses the `X-API-Key` header and a JSON body with `to`, `subject`, and `text`.

```bash
curl -X POST https://api.lumbox.co/v1/inboxes/inb_abc123/send \
  -H "X-API-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello from my agent",
    "text": "This email was sent by an AI agent."
  }'
```

--------------------------------

### Use Lumbox Python SDK

Source: https://lumbox.co/docs/quickstart

Installs the Lumbox Python SDK and uses it to create an inbox and wait for an OTP. Requires the LUMBOX_API_KEY environment variable.

```bash
pip install lumbox
```

```python
from lumbox import Lumbox
import os

client = Lumbox(api_key=os.environ["LUMBOX_API_KEY"])

inbox = client.create_inbox(name="signup-bot")
print(inbox.address)  # signup-bot@lumbox.co

otp = inbox.wait_for_otp(timeout=60)
print(otp)  # "847291"
```

--------------------------------

### Podman run command for Steel Browser

Source: https://lumbox.co/docs/browser

Alternative Podman command to run Steel Browser with the same ports, shared memory, and capabilities as the Docker setup. Use this if you prefer Podman over Docker. Requires Podman and the same resource minimums.

```bash
podman run -d --name steel \
  -p 3000:3000 -p 9223:9223 \
  --shm-size=2g --cap-add SYS_ADMIN \
  -e STEEL_PUBLIC_URL=https://browser.yourdomain.com \
  -v ./data/steel-cache:/app/.cache \
  ghcr.io/steel-dev/steel-browser:latest
```

--------------------------------

### GET /v1/domains

Source: https://lumbox.co/docs/api-reference

Lists all domains associated with the account.

```APIDOC
## GET /v1/domains

### Description
Lists all domains associated with the account.

### Method
GET

### Endpoint
/v1/domains
```

--------------------------------

### Accessibility Tree Snapshot Example

Source: https://lumbox.co/docs/browser

A text representation of a page showing element references used for interaction.

```text
@e1 heading "Sign Up"
@e2 textbox "Email address"
@e3 textbox "Password"
@e4 button "Create account"
@e5 link "Already have an account? Sign in"
```

--------------------------------

### GET /v1/smtp-configs

Source: https://lumbox.co/docs/api-reference

Lists all SMTP configurations. Passwords and API keys are masked in the response.

```APIDOC
## GET /v1/smtp-configs

### Description
Lists all SMTP configurations. Passwords and API keys are masked in the response.

### Method
GET

### Endpoint
/v1/smtp-configs
```

--------------------------------

### List Webhooks - GET /v1/webhooks

Source: https://lumbox.co/docs/webhooks

Lists all registered webhooks for the authenticated account.

```http
GET /v1/webhooks
```

--------------------------------

### Use Lumbox TypeScript SDK

Source: https://lumbox.co/docs/quickstart

Installs the Lumbox TypeScript SDK and uses it to create an inbox and wait for an OTP. Requires the LUMBOX_API_KEY environment variable.

```bash
npm install lumbox
```

```typescript
import { Lumbox } from "lumbox";

const client = new Lumbox({ apiKey: process.env.LUMBOX_API_KEY });

const inbox = await client.createInbox({ name: "signup-bot" });
console.log(inbox.address); // signup-bot@lumbox.co

const otp = await inbox.waitForOtp({ timeout: 60_000 });
console.log(otp); // "847291"
```

--------------------------------

### Create Webhook - POST /v1/webhooks

Source: https://lumbox.co/docs/webhooks

Creates a webhook subscription. The HTTP method and endpoint are shown first, followed by a curl example that includes the required X-API-Key header and a JSON body specifying the target URL and the events to listen for (here email.received).

```http
POST /v1/webhooks
```

```bash
curl -X POST https://api.lumbox.co/v1/webhooks \
  -H "X-API-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "events": ["email.received"]}'
```

--------------------------------

### GET /v1/domains

Source: https://lumbox.co/docs/domains

Lists all custom domains associated with the account.

```APIDOC
## GET /v1/domains

### Description
Lists all custom domains associated with the account.

### Method
GET

### Endpoint
/v1/domains

### Response
#### Success Response (200)
- **domains** (array) - List of custom domains.

#### Response Example
```
[
  {
    "id": "dom_abc123",
    "domain": "yourdomain.com",
    "status": "verified"
  }
]
```
```

--------------------------------

### List SMTP Configs (GET /v1/smtp-configs)

Source: https://lumbox.co/docs/api-reference

Lists all SMTP configurations. Passwords and API keys are masked in the response.

```http
GET /v1/smtp-configs
```

--------------------------------

### List Domains - GET /v1/domains

Source: https://lumbox.co/docs/domains

Lists all custom domains associated with the account.

```http
GET /v1/domains
```

--------------------------------

### Secure Re-Login: login_with_credential

Source: https://lumbox.co/docs/browser

Secure re-login example. Steel auto-fills stored credentials, blurs the fields, and submits; the password never appears in the conversation.

```text
login_with_credential(
  login_url="https://github.com/login",
  service="github.com"
)
```

--------------------------------

### With LangChain using Lumbox Python SDK

Source: https://lumbox.co/docs/sdk-quickstart

Use the Lumbox LangChain integration to get LangChain Tool objects for inbox operations.

```python
from lumbox.langchain import LumboxToolkit

toolkit = LumboxToolkit(api_key="ak_your_key_here")
tools = toolkit.get_tools()
# Returns LangChain Tool objects for: create_inbox, wait_for_email, get_otp, etc.
```

--------------------------------

### Create Inbox Request and Response

Source: https://lumbox.co/docs/inboxes

Example curl request to create an inbox named 'github-bot' and the corresponding JSON response.

```bash
curl -X POST https://api.lumbox.co/v1/inboxes \
  -H "X-API-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "github-bot"}'
```

```json
{
  "id": "inb_abc123",
  "address": "github-bot@lumbox.co",
  "name": "github-bot",
  "domain": "lumbox.co",
  "created_at": "2025-01-01T00:00:00.000Z"
}
```

--------------------------------

### Obtain SSL certificate and reload nginx

Source: https://lumbox.co/docs/deployment

Uses certbot to get SSL certificates for both domains and reloads nginx.

```bash
sudo certbot --nginx -d api.lumbox.co -d mcp.lumbox.co
sudo systemctl reload nginx
```

--------------------------------

### Full Signup Flow: Individual Steps and skill_signup_with_email

Source: https://lumbox.co/docs/browser

Shows the full signup flow using individual browser and credential tools, then the equivalent single skill call. The first block lists the steps with tool calls and expected OTP output; the second block replaces steps 3-7 with the skill tool.

```text
1. Create inbox:        create_inbox(name="github-bot")
2. Store credentials:   store_credential(service="github.com", identifier="bot@lumbox.co", value="S3cur3P@ss!")
3. Navigate to signup:  browser_navigate(url="https://github.com/signup")
4. Fill email:          browser_type(ref="@e2", text="bot@lumbox.co")
5. Fill password:       use_credential_in_browser(service="github.com", identifier="bot@lumbox.co", ref="@e3")
6. Submit:              browser_click(ref="@e4")
7. Wait for OTP:        get_otp(inbox_id="inb_abc")  → "847291"
8. Enter OTP:           browser_type(ref="@e5", text="847291", press_enter=true)
```

```text
skill_signup_with_email(url="https://github.com/signup", inbox_id="inb_abc")
```

--------------------------------

### List Credentials API (GET /v1/credentials)

Source: https://lumbox.co/docs/credentials

Lists credentials, optionally filtered by service. The 200 response returns metadata only and never includes the actual credential values.

```http
GET /v1/credentials
GET /v1/credentials?service=github.com
```

```json
{
  "data": [
    {
      "id": "cred_abc123",
      "service": "github.com",
      "identifier": "bot@example.com",
      "credential_type": "PASSWORD",
      "label": "GitHub bot account",
      "last_used_at": "2026-03-15T10:00:00Z",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Database Schema and Studio

Source: https://lumbox.co/docs/getting-started

Commands to push the Prisma schema to the database and launch the visual data explorer.

```bash
cd apps/api
bun run db:push
```

```bash
bun run db:studio
```

--------------------------------

### Create Organization and Test API Key

Source: https://lumbox.co/docs/getting-started

Commands to create an organization via the API and verify the resulting API key.

```bash
# Create an org
curl -X POST http://localhost:3000/v1/orgs \
  -H "Content-Type: application/json" \
  -d '{"name": "my-org"}'
# Response includes api_key: "ak_..."

# Test the API key
curl http://localhost:3000/v1/inboxes \
  -H "X-API-Key: ak_your_key_here"
# → { "data": [] }
```

--------------------------------

### GET /v1/inboxes/:id/otp

Source: https://lumbox.co/docs/api-reference

Long-polls for the latest verification code. The simplest way to get an OTP.

```APIDOC
## GET /v1/inboxes/:id/otp

### Description
Long-polls for the latest verification code. The simplest way to get an OTP.

### Method
GET

### Endpoint
/v1/inboxes/:id/otp

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the inbox.

#### Query Parameters
- **timeout** (number) - Optional - Max seconds (default: 30, max: 120).
- **from** (string) - Optional - Filter by sender.
- **since** (string) - Optional - ISO timestamp.

### Response
#### Success Response (200)
- **code** (string) - The OTP code.
- **all_codes** (array of strings) - All codes found.
- **from** (string) - Sender email.
- **subject** (string) - Email subject.
- **expires** (string) - Expiration timestamp.
- **email_id** (string) - Email ID.

#### Response Example
{
  "code": "847291",
  "all_codes": ["847291"],
  "from": "noreply@github.com",
  "subject": "Your verification code",
  "expires": "2026-02-27T10:05:00Z",
  "email_id": "eml_abc123"
}
```

--------------------------------

### Get Inbox API Endpoint

Source: https://lumbox.co/docs/inboxes

The GET endpoint to retrieve details for a specific inbox by its ID.

```http
GET /v1/inboxes/:id
```

--------------------------------

### skill_signup_with_email usage

Source: https://lumbox.co/docs/browser

Executes a complete signup flow including navigation, email entry, submission, and OTP retrieval.

```python
skill_signup_with_email(
  url="https://example.com/signup",
  inbox_id="inb_abc123",
  wait_timeout=60
)
```

--------------------------------

### Get Email (GET /v1/inboxes/:id/emails/:emailId)

Source: https://lumbox.co/docs/api-reference

Returns the full email object including attachments.

```http
GET /v1/inboxes/:id/emails/:emailId
```

--------------------------------

### Get Current Organization (GET /v1/orgs/me)

Source: https://lumbox.co/docs/api-reference

Retrieves the current organization's details, including counts of inboxes, domains, and API keys.

```http
GET /v1/orgs/me
```

```json
{
  "id": "org_abc123",
  "name": "my-org",
  "inbox_count": 5,
  "domain_count": 1,
  "api_key_count": 2,
  "created_at": "2026-02-27T10:00:00Z"
}
```

--------------------------------

### Get Thread - GET /v1/threads/:threadId

Source: https://lumbox.co/docs/api-reference

Retrieves a specific thread by ID, including all emails in the thread and assigned agents. Returns a 200 response with thread details.

```http
GET /v1/threads/:threadId
```

```json
{
  "thread_id": "thr_abc123",
  "subject": "Your order has shipped",
  "message_count": 3,
  "agents": [
    { "id": "ta_abc", "agent_id": "support-bot", "role": "OWNER", "assigned_at": "..." }
  ],
  "messages": [/* email objects */]
}
```

--------------------------------

### Browser Interaction using Element References

Source: https://lumbox.co/docs/browser

Demonstrates how to use element references from a snapshot to perform actions like typing and clicking.

```python
browser_type(ref="@e2", text="bot@example.com")
browser_type(ref="@e3", text="password123")
browser_click(ref="@e4")
```

--------------------------------

### Get OTP (GET /v1/inboxes/:id/otp)

Source: https://lumbox.co/docs/api-reference

Long-polls for the latest verification code. Query parameters: timeout (default 30, max 120), from, since. Returns the OTP code and related email details.

```http
GET /v1/inboxes/:id/otp
```

```json
{
  "code": "847291",
  "all_codes": ["847291"],
  "from": "noreply@github.com",
  "subject": "Your verification code",
  "expires": "2026-02-27T10:05:00Z",
  "email_id": "eml_abc123"
}
```

--------------------------------

### Deploy web app to Vercel

Source: https://lumbox.co/docs/deployment

Run these commands from the apps/web-new directory to deploy the Next.js app to Vercel. The first command changes to the web app directory, and the second triggers the Vercel deployment.

```bash
cd apps/web-new
vercel
```

--------------------------------

### GET /v1/inboxes

Source: https://lumbox.co/docs/inboxes

Returns all inboxes in your organization.

```APIDOC
## GET /v1/inboxes

### Description
Returns all inboxes in your organization.

### Method
GET

### Endpoint
/v1/inboxes

### Response
#### Success Response (200)
- Returns a list of inboxes.
```

--------------------------------

### Minimal .env Configuration

Source: https://lumbox.co/docs/getting-started

Required environment variables for local Lumbox operation.

```text
DATABASE_URL="postgresql://user:password@localhost:5432/lumbox"
DEFAULT_DOMAIN="lumbox.co"
INBOUND_SECRET="any-random-string"
```

--------------------------------

### Get Email

Source: https://lumbox.co/docs/emails

Retrieve a single email by its ID.

```APIDOC
## GET /v1/emails/:id

### Description
Retrieve a single email by its ID.

### Method
GET

### Endpoint
/v1/emails/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The email ID.

```

--------------------------------

### Create Organization (POST /v1/orgs)

Source: https://lumbox.co/docs/api-reference

Creates a new organization. The response includes an API key that is only shown once; save it immediately.

```http
POST /v1/orgs
```

```json
{ "name": "my-org" }
```

```json
{
  "id": "org_abc123",
  "name": "my-org",
  "api_key": "ak_live_...",
  "message": "Save your API key - it won't be shown again",
  "created_at": "2026-02-27T10:00:00Z"
}
```

--------------------------------

### GET /v1/inboxes/:id

Source: https://lumbox.co/docs/inboxes

Retrieves a specific inbox by its ID.

```APIDOC
## GET /v1/inboxes/:id

### Description
Retrieves a specific inbox by its ID.

### Method
GET

### Endpoint
/v1/inboxes/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The inbox ID.
```

--------------------------------

### Push database schema to Neon

Source: https://lumbox.co/docs/deployment

Run this command from the apps/api directory to push the database schema to Neon. Set the DATABASE_URL environment variable to your Neon connection string.

```bash
cd apps/api && DATABASE_URL="..." bun run db:push
```

--------------------------------

### Create API Key (POST /v1/orgs/me/api-keys)

Source: https://lumbox.co/docs/api-reference

Creates a new API key with specified scopes. The full API key is returned only once in the response.

```http
POST /v1/orgs/me/api-keys
```

```json
{ "name": "production", "scopes": ["inboxes:read", "inboxes:write"] }
```

```json
{
  "id": "ak_id_abc",
  "key_prefix": "ak_live_abc...",
  "api_key": "ak_live_full_key_here",
  "name": "production",
  "scopes": ["inboxes:read", "inboxes:write"]
}
```

--------------------------------

### Create SMTP Config (POST /v1/smtp-configs)

Source: https://lumbox.co/docs/api-reference

Creates a new SMTP configuration. The body must include a provider (one of SMTP, SES, SENDGRID, POSTMARK, RESEND), a name, credentials, and optionally a region and from_email. Setting is_default to true makes it the default outbound provider.

```http
POST /v1/smtp-configs
```

```json
{
  "provider": "SES",
  "name": "production-ses",
  "username": "AKIA...",
  "password": "secret...",
  "region": "us-east-1",
  "from_email": "noreply@mycompany.com",
  "is_default": true
}
```

--------------------------------

### GET /v1/emails

Source: https://lumbox.co/docs/api-reference

Searches across all inboxes in your organization with optional filters.

```APIDOC
## GET /v1/emails

### Description
Searches across all inboxes in your organization with optional filters.

### Method
GET

### Endpoint
/v1/emails

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search subject, body, summary.
- **from** (string) - Optional - Filter by sender (substring).
- **category** (string) - Optional - Filter by category.
- **inbox_id** (string) - Optional - Limit to specific inbox.
- **since** (string) - Optional - ISO timestamp.
- **limit** (number) - Optional - Max results (default: 20, max: 100).

```

--------------------------------

### Create inbox and wait for OTP

Source: https://lumbox.co/docs/introduction

Shows how to initialize the Lumbox client, create an inbox, and wait for an OTP to arrive within 60 seconds. The inbox address is github-bot@lumbox.co, and the OTP is returned as a string.

```typescript
import { Lumbox } from "lumbox";

const client = new Lumbox({ apiKey: "ak_..." });

// Create an inbox
const inbox = await client.createInbox({ name: "github-bot" });
// → github-bot@lumbox.co

// Sign up on GitHub with inbox.address...

// Wait for the OTP (blocks until it arrives)
const otp = await inbox.waitForOtp({ timeout: 60_000 });
// → "847291"
```

--------------------------------

### GET /v1/inboxes/:id/emails/:emailId

Source: https://lumbox.co/docs/api-reference

Returns a full email with attachments.

```APIDOC
## GET /v1/inboxes/:id/emails/:emailId

### Description
Returns a full email with attachments.

### Method
GET

### Endpoint
/v1/inboxes/:id/emails/:emailId

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the inbox.
- **emailId** (string) - Required - The ID of the email.

### Response
#### Success Response (200)
Returns the full email object with attachments.
```

--------------------------------

### GET /v1/credentials/audit

Source: https://lumbox.co/docs/credentials

Retrieves the audit log of every credential access.

```APIDOC
## GET /v1/credentials/audit

### Description
Retrieves the audit log of every credential access.

### Method
GET

### Endpoint
/v1/credentials/audit

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of log entries to return (e.g., 50)

### Response
#### Success Response (200)
- **data** (array) - List of audit log entries
  - **id** (string) - The log entry ID
  - **credential_id** (string) - The credential ID
  - **action** (string) - The action performed (e.g., use_in_browser)
  - **metadata** (object) - Additional metadata (e.g., service, identifier)
  - **created_at** (string) - Timestamp of the action

#### Response Example
{
  "data": [
    {
      "id": "log_abc",
      "credential_id": "cred_abc123",
      "action": "use_in_browser",
      "metadata": { "service": "github.com", "identifier": "bot@example.com" },
      "created_at": "2026-03-15T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Get Email Endpoint

Source: https://lumbox.co/docs/emails

Retrieves details for a specific email by its ID.

```http
GET /v1/emails/:id
```

--------------------------------

### POST /v1/orgs

Source: https://lumbox.co/docs/api-reference

Creates a new organization. Returns the organization details along with an API key that should be saved immediately.

```APIDOC
## POST /v1/orgs

### Description
Creates a new organization. Returns the organization details along with an API key that should be saved immediately.

### Method
POST

### Endpoint
/v1/orgs

### Parameters
#### Request Body
- **name** (string) - Required - The name of the organization.

### Request Example
{
  "name": "my-org"
}

### Response
#### Success Response (201)
- **id** (string) - Organization ID.
- **name** (string) - Organization name.
- **api_key** (string) - The generated API key.
- **message** (string) - Warning to save the API key.
- **created_at** (string) - Creation timestamp.

#### Response Example
{
  "id": "org_abc123",
  "name": "my-org",
  "api_key": "ak_live_...",
  "message": "Save your API key - it won't be shown again",
  "created_at": "2026-02-27T10:00:00Z"
}
```

--------------------------------

### GET /v1/threads/:id/agents

Source: https://lumbox.co/docs/threads

Lists the AI agents assigned to a specific thread.

```APIDOC
## GET /v1/threads/:id/agents

### Description
Lists the AI agents assigned to a specific thread.

### Method
GET

### Endpoint
/v1/threads/:id/agents

### Parameters
#### Path Parameters
- **id** (string) - Required - The thread ID.

### Response
#### Success Response (200)
Returns a list of agents assigned to the thread.

```

--------------------------------

### List Inboxes API Endpoint

Source: https://lumbox.co/docs/inboxes

The GET endpoint to retrieve all inboxes in your organization.

```http
GET /v1/inboxes
```

--------------------------------

### Edit .env configuration

Source: https://lumbox.co/docs/deployment

Environment variables for database, domain, secrets, email provider, and MCP port.

```bash
DATABASE_URL="postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/lumbox?sslmode=require"
DEFAULT_DOMAIN="lumbox.co"
INBOUND_SECRET="generate-a-random-secret"
ENCRYPTION_KEY="generate-32-byte-hex"
DEFAULT_EMAIL_PROVIDER="SES"
AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="..."
AWS_REGION="us-east-1"
MCP_PORT=3002
```

--------------------------------

### Provision an organization via Lumbox CLI

Source: https://lumbox.co/docs/agent-signup

Uses the Lumbox CLI to sign up and create an inbox. The API key is automatically stored in ~/.lumbox/config.json.

```bash
npx lumbox signup --source my-harness
npx lumbox inbox create
```

--------------------------------

### Get OTP

Source: https://lumbox.co/docs/emails

Waits for an email containing an OTP code and returns just the code.

```APIDOC
## GET /v1/inboxes/:id/otp?timeout=60

### Description
Waits for an email containing an OTP code and returns just the code. The simplest way to get a verification code.

### Method
GET

### Endpoint
/v1/inboxes/:id/otp

### Parameters
#### Path Parameters
- **id** (string) - Required - The inbox ID.

#### Query Parameters
- **timeout** (number, default: 30) - Optional - Max seconds to wait.
- **from** (string) - Optional - Filter by sender.

### Response
#### Success Response
- **otp** (string) - The OTP code.
- **email_id** (string) - The ID of the email containing the OTP.
- **from** (string) - The sender of the email.
- **subject** (string) - The subject of the email.

#### Response Example
{
  "otp": "847291",
  "email_id": "eml_xyz789",
  "from": "noreply@github.com",
  "subject": "Your verification code"
}
```

--------------------------------

### Configure Lumbox MCP in .cursor/mcp.json or claude_desktop_config.json

Source: https://lumbox.co/docs/mcp

Configuration for Cursor, Claude Desktop, or Windsurf to connect to the Lumbox MCP server. Place this in `.cursor/mcp.json` or `claude_desktop_config.json`; replace `ak_your_key_here` with your actual API key.

```json
{
  "mcpServers": {
    "lumbox": {
      "url": "https://mcp.lumbox.co/mcp",
      "headers": {
        "Authorization": "Bearer ak_your_key_here"
      }
    }
  }
}
```

--------------------------------

### Login with Namespace

Source: https://lumbox.co/docs/credentials

Specify the namespace when calling login_with_credential to ensure the correct user credentials are used.

```python
login_with_credential(login_url="https://github.com/login", service="github.com", namespace="agent:fred")
```

--------------------------------

### GET /v1/inboxes/:id/emails

Source: https://lumbox.co/docs/api-reference

Lists emails in a specific inbox with optional filtering and pagination.

```APIDOC
## GET /v1/inboxes/:id/emails

### Description
Lists emails in a specific inbox with optional filtering and pagination.

### Method
GET

### Endpoint
/v1/inboxes/:id/emails

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the inbox.

#### Query Parameters
- **limit** (number) - Optional - Max results (default: 20, max: 100).
- **cursor** (string) - Optional - Pagination cursor.
- **from** (string) - Optional - Filter by sender (substring match).
- **category** (string) - Optional - Filter by category.
- **since** (string) - Optional - ISO timestamp - only emails after this.
- **unread** (boolean) - Optional - Only unread emails.

### Response
#### Success Response (200)
- **data** (array) - Array of email objects.
- **cursor** (string) - Next cursor value.
- **has_more** (boolean) - Whether more results exist.

#### Response Example
{
  "data": [/* email objects */],
  "cursor": "next_cursor_value",
  "has_more": true
}
```

--------------------------------

### Add Lumbox MCP via CLI

Source: https://lumbox.co/docs/mcp

Use the claude CLI to add the Lumbox MCP server using npx.

```bash
claude mcp add lumbox --env LUMBOX_API_KEY=ak_your_key_here -- npx -y @lumbox/mcp-server
```

--------------------------------

### Get Thread Details

Source: https://lumbox.co/docs/threads

Retrieve all emails within a specific thread in chronological order.

```http
GET /v1/threads/:id
```

--------------------------------

### Create First Inbox

Source: https://lumbox.co/docs/getting-started

Command to create a new inbox using the API key.

```bash
curl -X POST http://localhost:3000/v1/inboxes \
  -H "X-API-Key: ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "test-inbox"}'
# → { "id": "inb_...", "address": "abc123@lumbox.co", ... }
```

--------------------------------

### List Webhook Deliveries (GET /v1/webhooks/:id/deliveries)

Source: https://lumbox.co/docs/api-reference

Lists delivery attempts for a webhook by its ID.

```http
GET /v1/webhooks/:id/deliveries
```

--------------------------------

### List Inboxes (GET /v1/inboxes)

Source: https://lumbox.co/docs/api-reference

Lists all inboxes for the organization, including email counts and status.

```http
GET /v1/inboxes
```

```json
{
  "data": [
    {
      "id": "inb_abc123",
      "address": "github-bot@lumbox.co",
      "name": "github-signup-bot",
      "status": "ACTIVE",
      "email_count": 12,
      "created_at": "2026-02-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Reverse Proxy (Caddy): browser.yourdomain.com

Source: https://lumbox.co/docs/browser

Caddy reverse proxy configuration for production deployment. Routes browser.yourdomain.com to localhost:3000.

```text
browser.yourdomain.com {
    reverse_proxy localhost:3000
}
```

--------------------------------

### Create Inbox and Long-poll for OTP

Source: https://lumbox.co/docs/for-agents

Create an inbox via POST, then use the long-poll endpoint to wait up to 60 seconds for an OTP.

```bash
# 1. Create an inbox
curl -X POST https://api.lumbox.co/v1/inboxes \
  -H "X-API-Key: $LUMBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
# → { "id": "inb_...", "address": "my-agent@lumbox.co" }

# 2. Use the address wherever an email is required
#    (sign-up form, 2FA config, etc.)

# 3. Long-poll for the OTP - blocks up to 60s
curl "https://api.lumbox.co/v1/inboxes/inb_.../otp?timeout=60" \
  -H "X-API-Key: $LUMBOX_API_KEY"
# → { "otp": "847291", "email_id": "eml_..." }
```

--------------------------------

### GET /v1/inboxes (X-API-Key)

Source: https://lumbox.co/docs/authentication

Retrieve inboxes using X-API-Key authentication. Functionally identical to Bearer.

```APIDOC
## [GET] /v1/inboxes

### Description
Retrieve inboxes using X-API-Key authentication.

### Method
GET

### Endpoint
https://api.lumbox.co/v1/inboxes

### Parameters
#### Headers
- **X-API-Key** (string) - Required - API key (e.g., `ak_your_key_here`)

### Request Example
```
curl https://api.lumbox.co/v1/inboxes \
  -H "X-API-Key: ak_your_key_here"
```

### Response
#### Success Response (200)
- Not specified in source.

#### Response Example
Not specified in source.
```

--------------------------------

### GET /v1/inboxes (Bearer)

Source: https://lumbox.co/docs/authentication

Retrieve inboxes using Bearer authentication. This is the recommended authentication scheme.

```APIDOC
## [GET] /v1/inboxes

### Description
Retrieve inboxes using Bearer authentication.

### Method
GET

### Endpoint
https://api.lumbox.co/v1/inboxes

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with API key (e.g., `Bearer ak_your_key_here`)

### Request Example
```
curl https://api.lumbox.co/v1/inboxes \
  -H "Authorization: Bearer ak_your_key_here"
```

### Response
#### Success Response (200)
- Not specified in source.

#### Response Example
Not specified in source.
```

--------------------------------

### Resource Limits: deploy.resources.limits.memory

Source: https://lumbox.co/docs/browser

Resource limit configuration for production. Steel uses ~1-2GB RAM per active session; set memory limit to 2G.

```text
deploy:
  resources:
    limits:
      memory: 2G
```

--------------------------------

### Authenticate with Bearer Token

Source: https://lumbox.co/docs/authentication

Recommended authentication method compatible with most SDKs and standard OpenAPI tooling.

```bash
curl https://api.lumbox.co/v1/inboxes \
  -H "Authorization: Bearer ak_your_key_here"
```

--------------------------------

### Get OTP Endpoint

Source: https://lumbox.co/docs/emails

Waits for an email containing an OTP code and returns the code directly.

```http
GET /v1/inboxes/:id/otp?timeout=60
```

```json
{
  "otp": "847291",
  "email_id": "eml_xyz789",
  "from": "noreply@github.com",
  "subject": "Your verification code"
}
```
Tokens:
Raw