Give an AI agent its own email inbox

Starter kit

The starter is a Bun and TypeScript app. It receives signed Shipmail webhooks, triages allowed inbound mail with Claude, and writes reply drafts that fail if the conversation moved on. Six recipes reuse the same core for scheduling, follow-ups, meeting briefs, a morning digest, sign-up codes and lead capture. Sending stays off until you turn it on. Get the code from shipmail-to/agent-inbox-starter. Browse the email agent workflow gallery for eight ways to adapt it.

• A Bun webhook server that verifies Shipmail signatures, deduplicates deliveries, and runs a handler per event type on a bounded queue.
• Sender authentication. A message must pass DMARC before the model sees it, so a forged allowlisted address does not get through.
• Shipmail's prompt-injection scan. A flagged or unscanned message goes to a person and never reaches the model.
• A Claude triage agent. It reads reply_text, sorts mail into needs_reply, ignore or escalate, and drafts a reply against the current conversation version.
• Recipes for a meeting scheduler, follow-up drafts on reply.overdue, meeting briefs on calendar.event_starting, a morning digest, agent sign-up codes, and a lead qualifier.
• Examples for the Claude Agent SDK, the OpenAI Agents SDK, the Vercel AI SDK, LangGraph, and an MCP client.

cp .env.example .env.local
bun install --ignore-scripts
bun run dev
bun run webhook:create -- --url https://your-tunnel.example/webhook

bun run sandbox:e2e

Guides for your agent

• Codex: Add the MCP server to the Codex CLI and IDE extension.
• Hermes Agent: Add the MCP server to Nous Research's Hermes Agent.
• OpenClaw: Add the MCP server to OpenClaw with one command.
• LangChain: Load Shipmail tools into a LangChain or LangGraph agent.
• Browser Use: Read sign-up codes and links from a mailbox on your domain.
• Receive email in an AI agent: Duplicate webhooks, threading, spoofed senders and memory.

Connect without the starter kit

Examples

{
  "mcpServers": {
    "shipmail": {
      "url": "https://shipmail.to/api/mcp",
      "headers": { "Authorization": "Bearer sm_live_..." }
    }
  }
}

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": { "SHIPMAIL_API_KEY": "sm_live_..." }
    }
  }
}

import { ShipmailClient } from "shipmail";

const client = new ShipmailClient("sm_live_...");

// Look up the domain id from client.domains.list() or the dashboard.
await client.mailboxes.create({
  domain_id: "d290f1ee-6c54-4b01-90e6-d701748f0851",
  address: "agent",
  password: process.env.AGENT_MAILBOX_PASSWORD,
});

curl -X POST https://shipmail.to/api/v1/messages \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Following up",
    "text": "Thanks for reaching out. Here is what you asked for."
  }'

await client.webhooks.create({
  url: "https://your-agent.example.com/inbound",
  events: ["message.received"],
});

const scan = await client.replyScans.create({
  mailbox_ids: ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  after: new Date(Date.now() - 365 * 86400000).toISOString(),
});

// Poll client.replyScans.get(scan.id) with bounded backoff until completed.
const page = await client.replyScans.listResults(scan.id, { limit: 50 });
const candidate = page.data[0];
if (candidate) {
  // Store candidate.conversation_id. thread_id is deprecated and can be re-threaded.
  const thread = await client.mailboxes.getInboxThread(
    candidate.mailbox_id,
    candidate.conversation_id,
  );
  const text = await yourModelDraftFunction(thread.data);
  const draft = await client.mailboxes.createInboxReplyDraft(
    candidate.mailbox_id,
    candidate.conversation_id,
    { text, expected_version: candidate.version },
  );

  // Apply your approval policy before this call.
  await client.mailboxes.sendInboxReplyDraft(
    candidate.mailbox_id,
    candidate.conversation_id,
    draft.id,
  );
}

Key concepts

Sources and related standards

Use these to compare an agent-owned Shipmail mailbox with MCP servers that work inside an existing account, and with APIs that connect many providers.

• Shipmail AI agent inbox starter kit

  A Bun and TypeScript webhook server you can run, with sender checks, Shipmail's injection scan, Claude triage, stale-safe drafts, six recipes, sandbox injection and agent framework examples.

• Model Context Protocol introduction

  Official MCP documentation for the standard that lets AI applications connect to external tools, data, and workflows.

• Shipmail MCP source repository

  Public source for the official Shipmail MCP server, including package metadata, tool coverage, resources, prompts, and security notes.

• Official MCP Registry entry

  Machine-readable registry listing for the Shipmail MCP server and its npm package.

• Google Gmail MCP server

  Google's official Gmail MCP server, in Developer Preview, for agents that read and draft inside existing Gmail accounts. It cannot send.

• Microsoft Work IQ MCP

  Microsoft's MCP endpoint, in preview, for agents that work on mail and other Microsoft 365 tenant data.

• Nylas MCP server docs

  Nylas documentation for MCP tools across connected email, calendar, contacts, and Notetaker data.

• Atomic Mail

  An agent-owned inbox product built around MCP, JMAP, and REST for autonomous agent workflows.

• AgentMail inbox API

  An inbox API for agents that creates inboxes on demand, on agentmail.to or on a custom domain on paid plans.

Frequently asked questions