lumbox

Email for AI agents. Create inboxes, receive OTPs, extract verification codes — all via API.

Install

npm install lumbox

Quick Start

import { Lumbox } from "lumbox";

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

// Create an inbox
const inbox = await client.createInbox({ name: "github-bot" });
// → [email protected]

// Sign up on any service with inbox.address...

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

Auth header

The SDK sends Authorization: Bearer ak_... by default. The legacy X-API-Key header still works server-side. Raw HTTP example:

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

Inbox-scoped API keys

Mint a key that can only ever touch one inbox:

const created = await client.inboxes.apiKeys.create(inbox.id, { name: "ci-bot" });
console.log(created.api_key); // shown once

await client.inboxes.apiKeys.list(inbox.id);
await client.inboxes.apiKeys.delete(inbox.id, created.id);

Features

• OTP extraction — verification codes parsed automatically
• Long-poll — waitForEmail() and waitForOtp() block until arrival
• Send/reply/forward — full outbound email support
• Custom domains — DKIM, SPF, DMARC verification
• Zero dependencies — uses native fetch

API

new Lumbox({ apiKey, baseUrl? })

Create a client. baseUrl defaults to https://api.lumbox.co.

client.createInbox({ name?, domain? })

Returns an Inbox object with .address, .id, and convenience methods.

inbox.waitForOtp({ timeout?, from? })

Blocks until an email with an OTP arrives. Returns { code, email_id, from, subject }.

inbox.waitForEmail({ timeout?, from?, subject? })

Blocks until any email arrives.

inbox.listEmails()

List all emails in the inbox.

client.addDomain(domain)

Add a custom domain. Returns DNS records to configure.

Full API docs: docs.lumbox.co

License

MIT