Getting Started

LobsterMail is email infrastructure built for autonomous AI agents. It lets agents self-provision inboxes, receive and send email, and stay protected from prompt injection attacks — all through a simple SDK.

Install#

npm install @lobsterkit/lobstermail

Using Claude Code, Cursor, or another AI coding tool? You don't need the SDK — see Integrations for one-line MCP setup.

Quick Example#

The fastest way to get started is with LobsterMail.create(). If no API token is found, the SDK automatically signs up for a free account and persists the token for future use.

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

const lm = await LobsterMail.create();

// Human-readable address — tries "my-agent", falls back to variations
const inbox = await lm.createSmartInbox({ name: 'My Agent' });

console.log(inbox.address); // my-agent@lobstermail.ai

const emails = await inbox.receive();
for (const email of emails) {
  console.log(email.subject, email.preview);
}

Tip: createSmartInbox() generates a clean, meaningful address from your agent's name and automatically handles collisions by trying variations (e.g. my-agent, my-agent1, m-agent, …). If you don't need a readable name, createInbox() gives you a random address like lobster-xxxx@lobstermail.ai.

What Just Happened#

1. Auto-signup — The SDK created a free account and stored your API token at ~/.lobstermail/token.
2. Smart inbox — A human-readable @lobstermail.ai address was provisioned from your agent's name, with automatic collision handling.
3. Polling — receive() returned any emails already delivered to the inbox.

Core Concepts#

• Inboxes are disposable or long-lived email addresses your agent controls.
• Emails are returned with built-in security metadata and injection risk scoring.
• Tokens follow the format lm_sk_test_* (test) or lm_sk_live_* (live) and authenticate all requests.

Next Steps#

• Integrations — Connect via Claude Code, Cursor, Openclaw, the Node.js SDK, or the REST API.
• Agent Quickstart — Walk through a full agent workflow: provision an inbox, sign up for a service, and extract a verification code.
• MCP Server — Give your agent email tools with zero code using the Model Context Protocol.
• Receiving Emails — Real-time delivery, filtering, and pagination.
• Sending Emails — Compose and send from your inboxes.
• Webhooks — Get notified in real time when emails arrive.
• Custom Domains — Use your own domain instead of @lobstermail.ai.
• Security and Injection — How LobsterMail protects agents from prompt injection in email content.