# Quickstart

Source: https://agentboxd.com/docs/quickstart

> Get an API key, create an inbox, and read your first email in about five minutes.

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](https://agentboxd.com/login) with your email. You get a workspace, and on the [API keys](https://agentboxd.com/app/api-keys) page you can create a key. It starts with `mr_` and is shown once, so store it right away:

shell:

```bash
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](https://agentboxd.com/docs/cli) (`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`.

agent.ts:

```ts
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.' });
}

```

agent.py:

```python
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:

```bash
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](https://agentboxd.com/app/inboxes) to see the SPF, DKIM and DMARC results and every field the API returns.

## Next steps

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

Stuck? Write to [support@agentboxd.com](mailto:support@agentboxd.com). For anything else, [hello@agentboxd.com](mailto:hello@agentboxd.com).