Agent Quickstart

Give your AI agent its own email address and let it send, receive, and react to messages autonomously.

Last updated 2026-02-23

Why agents need email#

Most agent frameworks treat email as an afterthought — a human has to set up SMTP credentials, configure OAuth, and babysit the whole flow. LobsterMail flips that. Your agent hatches its own inbox, sends and receives messages, and handles replies in a loop — no human in the way.

The agent loop#

Here's a minimal agent that checks for new mail, processes it, and replies:

import { LobsterMail } from "lobstermail";

const lobster = new LobsterMail();

// 1. Hatch an inbox
const inbox = await lobster.inbox.create();
console.log(`Agent inbox: ${inbox.address}`);

// 2. Poll for new messages
async function agentLoop() {
  while (true) {
    const messages = await lobster.inbox.messages(inbox.id, {
      unread: true,
    });

    for (const msg of messages) {
      console.log(`New mail from ${msg.from}: ${msg.subject}`);

      // 3. Process the message (your agent logic here)
      const reply = await processWithLLM(msg.text);

      // 4. Reply
      await lobster.send({
        from: inbox.address,
        to: msg.from,
        subject: `Re: ${msg.subject}`,
        text: reply,
      });

      // 5. Mark as read
      await lobster.inbox.markRead(inbox.id, msg.id);
    }

    // Wait 10 seconds before checking again
    await new Promise((r) => setTimeout(r, 10_000));
  }
}

agentLoop();

Using webhooks instead of polling#

For production agents, webhooks are more efficient than polling. LobsterMail can POST to your server every time a new message arrives.

await lobster.webhook.create({
  inboxId: inbox.id,
  url: "https://your-agent.example.com/webhook",
  events: ["message.received"],
});

See the Webhooks guide for full details.

Framework integrations#

LobsterMail works with any agent framework. Here are the most common patterns:

  • LangChain — Use LobsterMail as a tool in your agent's toolchain
  • CrewAI — Give each crew member their own inbox
  • AutoGen — Register LobsterMail as a function call
  • MCP — Use our MCP Server for zero-code integration with Claude and Cursor

What's next#