SDK Quickstart

Node.js

Install

npm install lumbox

Create Inbox → Wait for OTP → Reply

import { Lumbox } from "lumbox";

const client = new Lumbox({
  apiKey: "ak_your_key_here",
  baseUrl: "http://localhost:3000", // or https://api.lumbox.co
});

// Create a disposable inbox
const inbox = await client.createInbox({ name: "github-signup" });
console.log(`Email: ${inbox.address}`);
// → github-signup@trylumbox.com

// ... use inbox.address to sign up on a platform ...

// Wait for the verification email (blocks up to 60s)
const email = await inbox.waitForEmail({
  from: "github.com",
  timeout: 60,
});
console.log(`Got email: ${email.subject}`);

// Or just get the OTP code directly
const otp = await inbox.waitForOtp({
  from: "github.com",
  timeout: 60,
});
console.log(`OTP: ${otp.code}`);
// → "847291"

// Send a reply
await inbox.reply({
  email_id: email.id,
  text: "Thanks for the code!",
});

// Clean up
await inbox.delete();

waitForOtp resolves to { code, all_codes, from, subject, expires, email_id }. When no code arrives, the API returns 408; the SDK retries it up to maxRetries times (default 2) and then throws.

Search Across Inboxes

const results = await client.searchEmails({
  query: "invoice",
  from: "stripe.com",
});

for (const email of results.data) {
  console.log(`${email.from.address}: ${email.subject}`);
}

Custom Domain

// Add domain
const domain = await client.addDomain("mycompany.com");
console.log("Configure these DNS records:", domain.dns_records);

// After configuring DNS...
const verified = await client.verifyDomain(domain.id);
console.log(`Status: ${verified.status}`); // → "ACTIVE"

// Create inbox on custom domain
const support = await client.createInbox({
  name: "support",
  domain: "mycompany.com",
  local_part: "support",
});
// → support@mycompany.com

Python

Install

pip install lumbox

Create Inbox → Wait for OTP

from lumbox import Lumbox

client = Lumbox(
    api_key="ak_your_key_here",
    base_url="http://localhost:3000",
)

# Create inbox
inbox = client.create_inbox(name="github-signup")
print(f"Email: {inbox.address}")

# Wait for OTP (blocks up to 60s)
otp = inbox.wait_for_otp(sender="github.com", timeout=60)
print(f"OTP: {otp['code']}")

# Clean up
inbox.delete()

The Python SDK does not wrap sending. Send with POST /v1/inboxes/:id/send, shown under Plain HTTP below.

With LangChain

pip install "lumbox[langchain]"

from lumbox import create_langchain_tools

tools = create_langchain_tools(api_key="ak_your_key_here")
# Returns LangChain tools for create_inbox, wait_for_email, get_otp, etc.

Plain HTTP (curl)

No SDK needed - the REST API is straightforward:

API="http://localhost:3000"
KEY="ak_your_key_here"

# Create inbox
curl -X POST "$API/v1/inboxes" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"test"}'

# Wait for OTP (blocks up to 30s)
curl "$API/v1/inboxes/inb_abc123/otp?timeout=30&from=github.com" \
  -H "X-API-Key: $KEY"

# Send email
curl -X POST "$API/v1/inboxes/inb_abc123/send" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@example.com",
    "subject": "Hello",
    "text": "Sent by an AI agent"
  }'

SDK Quickstart

On this page