Quickstart

Homingbox, the Agentboxd email product, gives an AI agent a real email address. You create an inbox with one API call; mail sent to it is received on our own mail server, checked, cleaned up and handed to your agent.

#Get an API key

Sign in with your email. You get a workspace, and on the API keys page you can create a key. It starts with mr_ and is shown once, so store it right away:

export AGENTBOXD_API_KEY=mr_...
export AGENTBOXD_BASE_URL=https://api.agentboxd.com

Every request to the API sends it as Authorization: Bearer mr_.... The SDKs, the command line and the MCP server read AGENTBOXD_API_KEY and AGENTBOXD_BASE_URL from the environment (the older names MAILROOM_API_KEY and MAILROOM_URL still work as fallbacks).

Prefer a terminal? The command line (npx agentboxd login, then npx agentboxd inboxes create) gives you an address with no code.

#Create an inbox and wait for mail

Pick a username or let us choose a readable one. Passing a client_id makes the call idempotent: running it again returns the same inbox instead of making a new one. The TypeScript SDK installs with npm install agentboxd and the Python SDK with pip install agentboxd.

import { Agentboxd } from 'agentboxd';

const mr = new Agentboxd({
  apiKey: process.env.AGENTBOXD_API_KEY!,
  baseUrl: 'https://api.agentboxd.com',
});

// Idempotent on client_id: run it twice, get the same inbox back.
const inbox = await mr.inboxes.create({
  username: 'support-bot',
  display_name: 'Support Bot',
  client_id: 'support-bot',
});
console.log(inbox.address); // support-bot@homingbox.net

// Wait for the next email (long-poll, up to 60 s). No public URL needed.
const msg = await mr.messages.wait(inbox.id, { timeout: 60 });
if (msg) {
  console.log(msg.extracted_text); // the new part of the reply only
  await mr.messages.reply(inbox.id, msg.id, { text: 'Thanks, on it.' });
}

from agentboxd import Agentboxd

with Agentboxd() as mr:  # reads AGENTBOXD_API_KEY and AGENTBOXD_BASE_URL
    inbox = mr.inboxes.create(
        username="support-bot",
        display_name="Support Bot",
        client_id="support-bot",  # idempotent
    )
    print(inbox["address"])  # support-bot@homingbox.net

    # Wait for the next email (long-poll, up to 60 s). None on timeout.
    msg = mr.messages.wait(inbox["id"], timeout=60)
    if msg:
        print(msg["extracted_text"])  # the new part of the reply only
        mr.messages.reply(inbox["id"], msg["id"], text="Thanks, on it.")

curl -s https://api.agentboxd.com/v1/inboxes \
  -H "Authorization: Bearer $AGENTBOXD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"support-bot","display_name":"Support Bot","client_id":"support-bot"}'

# Wait up to 60 s for the next inbound email
curl -s "https://api.agentboxd.com/v1/inboxes/$INBOX_ID/messages/wait?timeout=60" \
  -H "Authorization: Bearer $AGENTBOXD_API_KEY"

#Send it an email

Write to the new address from Gmail or Outlook. The wait call above returns as soon as the message lands, with extracted_text holding just what you wrote, no quoted history or signature.

Open the inbox in the dashboard to see the SPF, DKIM and DMARC results and every field the API returns.

#Next steps

• Verification codes: let an agent sign up for a service and read the code.
• Webhooks: get a signed POST when mail arrives instead of polling.
• MCP server: give Claude Desktop, Claude Code or Cursor an inbox with no code, and the agent skill that tells them how to use it.
• Command line: inboxes, mail, sign-up codes and live events from a terminal or a script.
• Contacts and memory and Knowledge: give your agent context about who is writing and how you answer.
• API reference: every endpoint, parameter and error.

Stuck? Write to support@agentboxd.com. For anything else, hello@agentboxd.com.