AgentMailbox

Email addresses for AI agents. Zero cost per account.

AgentMailbox gives any AI agent its own email address at @agentmailbox.io. Agents can receive verification codes, order confirmations, and notifications — no Gmail or Google Workspace fees per account.

Install

npm install -g agent-mailbox-cli

Quick Start

# 1. Sign up for an admin account
agentmailbox signup [email protected]
# → sends a 6-digit code to your email
# → paste code to log in

# 2. Create an org to get an API key
agentmailbox org create my-org
# → API Key: ae_xxxxx

# 3. Create an email account for your agent
export AGENT_EMAIL_API_KEY=ae_xxxxx
agentmailbox account create grocery-bot
# → [email protected]

# 4. Read emails
agentmailbox msg list [email protected]

# 5. Wait for a new email (blocks until one arrives)
agentmailbox msg wait [email protected] --timeout 60

# 6. Read a specific message
agentmailbox msg read [email protected] <message-id>

# 7. Reply
agentmailbox msg reply [email protected] <message-id> "Got it, thanks"

CLI Commands

Auth

agentmailbox signup <email>       # Create admin account (magic link)
agentmailbox login <email>        # Log in (magic link)
agentmailbox logout               # Log out
agentmailbox whoami               # Show current user

Orgs (requires login)

agentmailbox org create <name>    # Create org, get API key
agentmailbox org list             # List your orgs
agentmailbox org rotate-key <id>  # Rotate API key

Accounts (requires API key)

agentmailbox account create <name>           # Create email account
agentmailbox account list                    # List accounts
agentmailbox account delete <address>        # Delete account

Messages (requires API key)

agentmailbox msg list <address>                          # List inbox
agentmailbox msg read <address> <id>                     # Read message
agentmailbox msg wait <address> --timeout 60             # Wait for new email
agentmailbox msg reply <address> <id> "reply text"       # Reply
agentmailbox msg send <from> <to> "Subject" "Body"       # Send new email

API

Base URL: https://agent-email-api-production.up.railway.app

Authentication

Two types of auth:

• Admin session (as_ token): for org management. Obtained via magic link login.
• Org API key (ae_ token): for account/message operations. Obtained when creating an org.

Both use Authorization: Bearer <token> header.

Auth Endpoints

POST /v1/auth/signup    { email }              Create admin account, send code
POST /v1/auth/login     { email }              Send login code
POST /v1/auth/verify    { token }              Verify code, get session token
POST /v1/auth/logout                           End session
GET  /v1/auth/me                               Current user info

Org Endpoints (admin session required)

POST /v1/orgs                    { name }      Create org, get API key
GET  /v1/orgs                                  List your orgs
POST /v1/orgs/:id/rotate-key                   Rotate API key

Account Endpoints (API key required)

POST   /v1/accounts              { local_part, display_name? }   Create email account
GET    /v1/accounts                                              List accounts
DELETE /v1/accounts/:address                                     Delete account

Message Endpoints (API key required)

GET    /v1/accounts/:address/messages?limit=50&since=ISO8601     List inbox
GET    /v1/accounts/:address/messages/:id                        Read message
GET    /v1/accounts/:address/messages/wait?timeout=30            Wait for new email
POST   /v1/accounts/:address/messages/:id/reply  { text, html? }  Reply
POST   /v1/accounts/:address/send  { to, subject, text, html? }   Send new email
DELETE /v1/accounts/:address/messages/:id                        Delete message
GET    /health                                                   Health check

Example: Agent Signup Flow

const API = 'https://agent-email-api-production.up.railway.app';
const KEY = 'ae_xxxxx';

// 1. Create an email for the agent
const { account } = await fetch(`${API}/v1/accounts`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ local_part: 'bot-123' })
}).then(r => r.json());
// → [email protected]

// 2. Sign up for a service using that email
// ... (agent signs up on grocery site with [email protected])

// 3. Wait for verification email
const { message } = await fetch(
  `${API}/v1/accounts/[email protected]/messages/wait?timeout=60`,
  { headers: { 'Authorization': `Bearer ${KEY}` } }
).then(r => r.json());

// 4. Extract verification code
const code = message.text.match(/\d{6}/)?.[0];

Architecture

Internet ──SMTP:25──▶ Fly.io (SMTP receiver) ──▶ PostgreSQL (Railway)
                             ▲                         ▲
                             │ HTTPS (send API)        │
Agents ──HTTPS──▶ Railway (REST API) ─────────────────┘

• API: Fastify on Railway
• SMTP: Node.js smtp-server on Fly.io, port 25 + HTTP send API
• Database: PostgreSQL on Railway
• Domain: agentmailbox.io (Vercel DNS, MX + SPF + DMARC configured)

Development

# Start Postgres
docker compose up -d

# Init database
npm run db:init

# Run everything locally
npm run dev

# Or run API and SMTP separately
npm run dev:api
npm run dev:smtp

Deploy

# API → Railway
railway up -s agent-email-api

# SMTP → Fly.io
fly deploy --app agent-email-smtp