Agentboxd

Real email inboxes for AI agents. Create an address with one API call, send and reply from it, block until the next email arrives, and pull the one-time code or magic link out of a sign-up email.

This repository holds the open-source clients for the hosted Agentboxd API:

Package	Install	Source
TypeScript / Node client	npm install agentboxd	sdk/
Command line	npx agentboxd --help	sdk/src/cli/
MCP server (Claude Desktop, Claude Code, Cursor, ...)	npx -y @agentboxd/mcp	mcp/
Python client (sync + async)	Coming soon to PyPI; install from sdk-python/ meanwhile	sdk-python/
Example agents and guide code		examples/
Agent skill (Claude Code, Cursor, Codex, OpenClaw, ...)	npx skills add agentboxd/skills	agentboxd/skills

What you get

• Real addresses on homingbox.net or your own domain, with SPF, DKIM and DMARC handled.
• Mail as clean JSON: extracted_text holds only the new text of a reply, without quoted history or signatures; attachments, threads and authentication results are all there.
• Wait instead of poll: messages.wait() long-polls until the next matching email arrives.
• Verification codes and magic links extracted from sign-up and login emails, with a confidence score.
• Temporary inboxes that delete themselves (and their mail) after a TTL you choose.
• Signed webhooks for message.received and friends, plus a verifier in each SDK.
• Untrusted-input handling: messages that fail SPF/DMARC or look like prompt injection are labelled, and the MCP server marks every result that contains email content.

60-second quickstart

Get an API key from the dashboard (Free plan, no card), then:

export AGENTBOXD_API_KEY=mr_...

TypeScript

import { Agentboxd } from 'agentboxd';

const mr = new Agentboxd(); // reads AGENTBOXD_API_KEY
const inbox = await mr.inboxes.create({ client_id: 'my-agent' }); // idempotent on client_id
console.log(inbox.address);

const since = new Date().toISOString();
// ...sign up somewhere with inbox.address...
const v = await mr.messages.waitForVerification(inbox.id, { since, timeout: 60 });
console.log(v?.code ?? v?.link);

Python

from agentboxd import Agentboxd

with Agentboxd() as mr:  # reads AGENTBOXD_API_KEY
    inbox = mr.inboxes.create(client_id="my-agent")
    msg = mr.messages.wait(inbox["id"], timeout=60)
    if msg:
        mr.messages.reply(inbox["id"], msg["id"], text="Got it, thanks!")

MCP (Claude Code)

The hosted connector needs no API key: you sign in and choose what the client may do.

claude mcp add --transport http agentboxd https://mcp.agentboxd.com/mcp

Or run the server locally with a key:

claude mcp add agentboxd -e AGENTBOXD_API_KEY=mr_... -- npx -y @agentboxd/mcp

Then ask: "Create an inbox, sign up for the newsletter at example.com with it, and tell me the confirmation link." Config snippets for Claude Desktop, Cursor and other clients are in mcp/README.md.

Docs

• Quickstart · API reference
• Verification codes · Webhooks · Temporary inboxes · Custom domains
• MCP server · TypeScript SDK · Python SDK
• Machine-readable: llms.txt

Examples

• examples/echo-agent.ts: registers a webhook and replies to every email with a short summary. Needs a public URL for the webhook (e.g. a tunnel): AGENTBOXD_API_KEY=mr_... AGENTBOXD_BASE_URL=https://api.agentboxd.com ECHO_WEBHOOK_URL=https://<your-tunnel>/webhook npm run echo-agent
• examples/deepseek-agent/: a tool-calling agent that signs up for things and triages an inbox, with the email-is-untrusted guardrails wired in.

npm install          # dev tooling for the examples (tsx, vitest)
npm run echo-agent
npm run deepseek-agent -- --demo signup

Repository layout

sdk/          TypeScript client (npm: agentboxd), zero runtime dependencies
mcp/          MCP server (npm: @agentboxd/mcp); inlines the TypeScript client at build time
sdk-python/   Python client (PyPI: agentboxd, coming soon)
examples/     Example agents using the TypeScript client

The Agentboxd API server itself is not part of this repository.

Contributing and security

Issues and pull requests are welcome: see CONTRIBUTING.md. Please report security problems privately as described in SECURITY.md, not in public issues.

License

MIT