Agent Quickstart

LobsterMail is designed for AI agents that operate without a human in the loop. This guide walks through a complete agent workflow: self-provisioning an inbox, signing up for an external service, and extracting a verification code from the confirmation email.

Token Resolution#

When you call LobsterMail.create(), the SDK resolves your API token in this order:

1. Explicit — Pass a token directly: LobsterMail.create({ token: 'lm_sk_live_...' })
2. Environment variable — LOBSTERMAIL_TOKEN
3. Token file — ~/.lobstermail/token
4. Auto-signup — If none of the above exist, the SDK signs up for a free account and writes the token to ~/.lobstermail/token.

This means an agent can start from zero with no configuration at all.

Token Persistence#

After auto-signup the token is written to ~/.lobstermail/token. Subsequent calls to LobsterMail.create() will read it from disk, so your agent reuses the same account across runs.

To disable persistence, pass { persistToken: false }:

const lm = await LobsterMail.create({ persistToken: false });

Full Example: Verification Email Flow#

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({
  name: 'My Agent',
  org: 'Acme',
});

console.log(`Inbox ready: ${inbox.address}`);

// Your agent signs up for a third-party service using inbox.address
// ... (call the service's signup API here)

// Wait for the verification email (returns instantly when it arrives)
const email = await inbox.waitForEmail({
  filter: { from: 'noreply@service.com' },
  timeout: 60000,
});

// Get the email body with injection-safe boundary markers
const content = email.safeBodyForLLM();
console.log(content);

// Extract the verification code (your LLM or a regex can do this)
const code = content.match(/\d{6}/)?.[0];
console.log(`Verification code: ${code}`);

Key Points#

• createSmartInbox() generates a meaningful address from your agent's name and handles collisions automatically. Falls back to a random address if all variations are taken.
• waitForEmail() uses server-side long-polling for near-instant delivery — it returns within milliseconds of the email arriving, not seconds. Returns null if the timeout is reached.
• filter accepts from (exact match) and subject (substring match for strings, pattern match for RegExp) fields.
• safeBodyForLLM() returns the email body wrapped in boundary markers that help LLMs distinguish email content from their own instructions. See the Security guide for details.

MCP Server (Zero Code)#

If your agent supports the Model Context Protocol (MCP), you can use the LobsterMail MCP server instead of writing code. Add this to your MCP configuration:

{
  "mcpServers": {
    "lobstermail": {
      "command": "npx",
      "args": ["@lobsterkit/lobstermail-mcp"]
    }
  }
}

This gives your agent tools like create_inbox, wait_for_email, check_inbox, send_email, and more — no SDK code required. The MCP server handles auto-signup and token persistence automatically.

Billing & Early-Bird Promotion#

New accounts start at the Anonymous tier (free, receive-only, 30-day inbox expiry). To unlock sending and higher limits, subscribe to a paid tier via Stripe.

The first 1,000 accounts to subscribe to the Builder tier ($9/mo) get a 90-day free trial. Your card is collected during checkout but not charged until the trial ends. After 90 days the subscription renews at $9/mo — cancel anytime via the billing portal.

To check eligibility and claim the promotion:

1. GET /v1/account — check the promo field for "status": "available"
2. POST /v1/billing/checkout with {"tier": 2} — returns a Stripe Checkout URL
3. Complete the checkout (card required, not charged during trial)
4. GET /v1/account — promo.status is now "claimed", tier is "builder"

Note: The promotion requires completing the Stripe Checkout session. Simply calling the checkout endpoint is not enough — the returned URL must be opened and payment setup completed to activate the trial.

Environment Variables#

Next Steps#

• Receiving Emails — Advanced polling, filtering, and pagination.
• Security and Injection — Understand how LobsterMail protects your agent from malicious email content.