InboxAPI

An account with a unique, personal email address is created automatically on first run. Your AI can then:

- Send emailsto any address
- Receive emailsat its own inbox
- Reply toandforwardemails
- Searchemails by keyword
- Read full threadsof conversation

- This is your agent's personal email— InboxAPI gives your AI agent its own email address for personal use. It is not a transactional email service — don't use it for bulk sending, marketing, or application notifications.
- Weekly send limit— Each account can send to up to five unique email addresses per week. This resets weekly.
- Check your spam folder— Each agent gets its own subdomain, and new subdomains don't have email reputation yet. Early messages may land in your recipient's spam or junk folder. Adding your agent's email address to your contacts or allowlist helps. Delivery improves over time as recipients interact with your agent's emails.
- Attachments— Send attachments via CLI subcommands using--attachment(local files) or--attachment-ref(server-side attachments by ID).
- HTML email support— CLI subcommands support HTML emails with--html-bodyor--html-body-file.
- Owner verification— Link your email to your agent's account withverify_ownerto enable account recovery and remove trial restrictions. Recommended as a first step after setup.

Run the same install command to update to the latest version:

The CLI also checks for updates automatically when running in proxy mode and installs them in the background.

Just start the proxy — an account is created automatically on first run

On first run with no saved credentials, the CLI auto-creates an account with a generated name (e.g.brooding-fluffy-owl) and authenticates. No manual setup needed.

Credentials are stored in your system config directory and automatically injected into tool calls. The CLI checks multiple locations so it can pick up credentials created by AI agents:

- ~/Library/Application Support/inboxapi/credentials.json(macOS primary)
- ~/.config/inboxapi/credentials.json(Linux primary / macOS fallback)
- ~/.local/inboxapi/credentials.json(fallback, used by some AI agents)

Starts the STDIO proxy. Reads JSON-RPC messages from stdin, forwards them to the InboxAPI endpoint, and streams SSE responses to stdout. If no credentials are found, an account is automatically created with a generated name.

inboxapi proxy inboxapi proxy --endpoint https://custom-endpoint.example.com/mcp inboxapi proxy --claim-secret ibx...

Runninginboxapiwith no subcommand also starts the proxy.--claim-secretis used only when credentials do not exist and the proxy auto-creates an account on a custom domain.

Manually creates an account with a chosen name and stores access credentials locally. Not required for basic usage sinceproxyhandles account creation automatically.

inboxapi login inboxapi login --name myaccount inboxapi login --endpoint https://custom-endpoint.example.com/mcp inboxapi login --name myaccount --claim-secret ibx...

Claims a custom-domain primary mailbox for the current account using a custom domain claim secret. The old generated mailbox remains receive-enabled but cannot send.

inboxapi custom-domain-claim --secret ibx... --email-address myaccount@example.com

Displays the currently authenticated account and endpoint.

Deletes stored credentials. Interactively offers to back up first, then asks for confirmation before deleting.

Backs up credentials to a specified folder.

Restores credentials from a backup folder. Validates backup integrity and offers to back up existing credentials before overwriting.

Installs InboxAPI skills for AI coding agents. SupportsClaude Code,Codex CLI,Gemini CLI, andOpenCode. Auto-detects installed agents and prompts for confirmation, or use flags for non-interactive installation.

inboxapi setup-skills # Auto-detect agents, interactive prompt inboxapi setup-skills --all # Install for all 4 agents inboxapi setup-skills --claude --codex # Install for specific agents inboxapi setup-skills --force # Overwrite existing skills and hooks

For agents with shell access, CLI subcommands are the simplest way to use InboxAPI — no MCP, JSON-RPC, or base64 knowledge needed.

inboxapi send-email --to user@example.com --subject "Hello" --body "Hi there" inboxapi send-email --to user@example.com --subject "Report" --body "See attached" --attachment ./report.pdf inboxapi send-email --to user@example.com --subject "Fwd" --body "See attached" --attachment-ref 9f0206bb-... inboxapi send-email --to "a@b.com, c@d.com" --subject "Hi" --body "Hello" --cc "cc@b.com" --priority high inboxapi send-email --to user@example.com --subject "Newsletter" --body-file ./body.txt --html-body-file ./newsletter.html inboxapi send-email --to user@example.com --subject "Screenshot" --body-file ./body.txt --html-body-file ./email-with-inline-image.html

Supports--bodyor--body-file,--html-bodyor--html-body-file,--cc,--bcc,--priority,--attachment(local files, repeatable), and--attachment-ref(server-side attachment IDs, repeatable).--from-nameis deprecated and ignored; InboxAPI enforces the authenticated account identity.

Prefer--body-fileand--html-body-filefor complex HTML, templates, or large generated payloads such as inline base64 images. File-backed bodies are validated as UTF-8 text, normalized to\nline endings, and capped at 20 MiB before the request is sent.

inboxapi get-emails --limit 5 inboxapi get-emails --limit 5 --human

inboxapi get-email "<message-id>"

Archives (soft-deletes) a received email by message ID. It prompts for confirmation by default, and scripted or piped use must pass--force.archive-emailis available as an alias fordelete-email.

inboxapi delete-email "<message-id>" inboxapi delete-email "<message-id>" --force inboxapi archive-email "<message-id>" --force

inboxapi search-emails --subject "invoice" --limit 10

inboxapi get-attachment abc123 # prints signed URL as JSON inboxapi get-attachment abc123 --output ./file.pdf # downloads to file

inboxapi send-reply --message-id "<msg-id>" --body "Thanks!" inboxapi send-reply --message-id "<msg-id>" --body-file ./reply.txt --html-body-file ./reply.html

send-replyauto-preserves original thread recipients for multi-recipient conversations. Use--reply-allto force reply-all, and use--ccwhen you need to add new CC recipients beyond the original thread.

inboxapi forward-email --message-id "<msg-id>" --to recipient@example.com --note "FYI"

inboxapi help # CLI-focused help with examples

All CLI commands support the--humanflag for human-readable output instead of JSON.

InboxAPI CLI also works as an MCP STDIO transport. Point your MCP client at theinboxapibinary:

Claude Desktop(claude_desktop_config.json):

{ "mcpServers": { "inboxapi": { "command": "inboxapi" } } }

Add globally (available in all projects):

claude mcp add inboxapi inboxapi -s user

Add system-wide (available in all directories):

gemini mcp add inboxapi inboxapi --scope user

- Location:Global
- MCP server name:inboxapi
- MCP server type:Local
- Command to run:inboxapi

InboxAPI includes skills — slash commands and guided workflows — for multiple AI coding agents. Install them with:

inboxapi setup-skills # Auto-detect and install inboxapi setup-skills --all # Install for all agents

Skills are installed to agent-specific directories:

Thesetup-skillscommand also installs three hooks for Claude Code that run automatically:

cargo build # Build debug binary cargo build --release # Build release binary cargo test # Run tests cargo fmt # Format code

Why not just give my agent access to my Gmail or Outlook?

Security— Gmail/Outlook OAuth gives your agent access to your entire inbox (medical, financial, legal, personal). A prompt injection in any inbound email could manipulate an agent with access to all of it. InboxAPI gives your agent its own isolated inbox with trust classification and datamarking on every message.

Identity— When your agent sends from your Gmail, recipients can't tell who they're talking to. Replies go to your inbox, mixed with your real mail. InboxAPI gives your agent its own personal address — clear separation between you and your agent.

Practicality— Gmail/Outlook APIs aren't MCP-native. You'd need middleware, OAuth plumbing, and custom integration. InboxAPI works out of the box with any MCP client.

How is this different from AWS SES, SendGrid, or Resend?

Those are sending APIs — you build email infrastructure on top of them. InboxAPI gives your agent a complete email identity: send, receive, search, reply, and forward. There's nothing to configure and no infrastructure to manage.

How is this different from AgentMail or a1base?

We built our own email stack from the ground up. We don't wrap SES, Postfix, or any third-party sending service. Your agent's mail goes through infrastructure we operate directly.

Yes. No credit card, no trial period, no usage tiers. We're working on paid plans with additional features, but the core experience will always be free.

Account creation requires proof-of-work. Each account can only email 5 unique external email addresses per week. Daily send quotas and rate limiting are enforced on every account. These constraints are structural — they're not policies, they're how the system works.

Every inbound email includes a trust classification — trusted, agent, unverified, or suspicious — based on whether the sender is in your addressbook and whether their email passes authentication checks. This helps your agent decide how cautiously to handle each message. Emails from other InboxAPI agents are flagged separately so your agent knows to check with you before acting on them.

Additionally, untrusted email content is automatically transformed using spotlighting (datamarking) — whitespace is replaced with a unique marker character so your agent can clearly distinguish email data from its own instructions. This reduces the success rate of prompt injection attacks embedded in emails from ~50% to under 3%.

Outbound emails are scanned for authentication tokens and credentials. If your agent accidentally tries to send an email containing a JWT or access token, the message is rejected before it leaves the platform. This prevents agents from being tricked into leaking sensitive data via email. Additionally, all recipient addresses in send, reply, and forward operations are validated against RFC 5322 — malformed addresses are rejected before delivery.

The same send limits apply to all outbound email — recipient caps, quotas, and rate limiting work the same regardless of who's on the receiving end.

Will my agent's emails land in spam?

Maybe at first. Each agent gets a brand-new subdomain, and new senders don't have reputation yet. Recipients may need to check their spam folder for the first few emails. Over time, as your agent sends legitimate mail and recipients interact with it, delivery improves.

Why email instead of a native agent protocol like A2A?

Email reaches the entire existing internet — billions of people and businesses already use it. A2A requires both sides to implement the protocol. When your agent needs to reach someone outside its own ecosystem, email is the universal option. Agents will likely need both.

Why email instead of WhatsApp, Telegram, or other messaging apps?

Scalability— You can programmatically create hundreds of email addresses. WhatsApp, Telegram, and Signal all require phone numbers and verification. Scaling past a handful of accounts is impractical, often against terms of service, and sometimes impossible without physical SIM cards.

No gatekeeping— Email is the only communication channel where you can create an identity without a phone number, government ID, or approval from a platform owner. No single company controls who gets an email address.

Open protocol— Email is federated and vendor-neutral. WhatsApp, Discord, and Telegram are proprietary — they can revoke API access, ban bot accounts, or change the rules at any time. Email can't be shut off by one company.

ToS compliance— Most messaging platforms explicitly prohibit automated accounts or have strict approval processes (WhatsApp Business API requires business verification, Telegram restricts bot-to-bot messaging). Email has no such restrictions — automated sending is a first-class use case.

Universal reach— Messaging channels are siloed. Your Telegram bot can't reach a WhatsApp user. Email reaches anyone with an email address — which is effectively everyone.