Quickstart · Capumattu

Capumattu 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:

shell

export MAILROOM_API_KEY=mr_...
export MAILROOM_URL=https://mailroom.capumattu.com

Every request to the API sends it as Authorization: Bearer mr_.... The SDKs and the MCP server read MAILROOM_API_KEY and MAILROOM_URL from the environment.

#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.

agent.ts

import { Mailroom } from '@mailroom/sdk';

const mr = new Mailroom({
  apiKey: process.env.MAILROOM_API_KEY!,
  baseUrl: 'https://mailroom.capumattu.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@agents.capumattu.com

// 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

from capumattu import Capumattu

with Capumattu() as mr:  # reads MAILROOM_API_KEY and MAILROOM_URL
    inbox = mr.inboxes.create(
        username="support-bot",
        display_name="Support Bot",
        client_id="support-bot",  # idempotent
    )
    print(inbox["address"])  # support-bot@agents.capumattu.com

    # 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

curl -s https://mailroom.capumattu.com/v1/inboxes \
  -H "Authorization: Bearer $MAILROOM_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://mailroom.capumattu.com/v1/inboxes/$INBOX_ID/messages/wait?timeout=60" \
  -H "Authorization: Bearer $MAILROOM_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.
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@capumattu.com. For anything else, hello@capumattu.com.