Quickstart: an inbox for your agent

Give an agent a real email address it can read and reply to. From key to first agent reply in about ten minutes.

If you just signed up, the console wizard has already created a workspace, a first mailbox and a key for you — skip to step 3. This page shows the same thing from the API, with a policy attached.

export MAILGENTIC_KEY="cfx_..."       # account admin key, from Console → API keys
export API="https://api.mailgentic.ai"
curl "$API/v1/tenants" -H "Authorization: Bearer $MAILGENTIC_KEY"   # → TENANT_ID (your default workspace)
curl "$API/v1/domains" -H "Authorization: Bearer $MAILGENTIC_KEY"   # → DOMAIN_ID (shared domains are listed first)

1. Create an inbox

An inbox lives on an inbound-enabled domain. The fastest start is the shared agents.mailgentic.ai domain Mailgentic operates for you — it is already in your domain list; bring your own later by verifying its MX record.

curl -X POST "$API/v1/tenants/$TENANT_ID/inboxes" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "'$DOMAIN_ID'",
    "local_part": "support",
    "display_name": "Support Agent",
    "policy": {
      "dlp": "enforce",
      "max_send_per_hour": 100,
      "require_approval_on_taint": true
    }
  }'

{ "inbox": { "id": "INBOX_ID", "address": "support@agents.mailgentic.ai", "status": "active", "provider": "native", "…": "…" } }

The policy block is Agent Shield: here the agent may send 100 messages an hour, secrets and PII are blocked from outbound bodies, and replies on threads flagged as injection or phishing are held for a human.

2. Give the agent its own key

Mint a key pinned to this one inbox. It can read and send in that inbox and nothing else, so a compromised agent cannot reach other tenants or inboxes.

curl -X POST "$API/v1/api-keys" \
  -H "Authorization: Bearer $MAILGENTIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-agent", "inbox_id": "'$INBOX_ID'", "scopes": ["read", "send"]}'
export AGENT_KEY="cfx_..."

3. Receive mail

Send a test email to support@agents.mailgentic.ai. Mailgentic authenticates it (SPF, DKIM, DMARC), runs Agent Shield over it, threads it and stores it. Then read it:

curl "$API/v1/inboxes/$INBOX_ID/messages?folder=inbox&unread=true" \
  -H "Authorization: Bearer $AGENT_KEY"

{
  "messages": [{
    "id": "MESSAGE_ID",
    "thread_id": "THREAD_ID",
    "direction": "in",
    "from": "customer@example.net",
    "subject": "I need help",
    "text": "I need help with my order.",
    "verdict": "clean",
    "auth": {"spf": "pass", "dkim": "pass", "dmarc": "pass"},
    "folder": "inbox",
    "read": false
  }]
}

Every inbound message carries a Shield verdict: clean, suspicious, spam, blocked or unauthenticated. Treat anything other than clean as untrusted input, and never feed those bodies to the model as instructions.

Rather than polling, stream events:

curl -N "$API/v1/inboxes/$INBOX_ID/events" -H "Authorization: Bearer $AGENT_KEY"

event: message.received
data: {"id":1843,"type":"message.received","data":{"inbox_id":"INBOX_ID","message_id":"MESSAGE_ID"}}

4. Reply as the agent

curl -X POST "$API/v1/inbox-messages/$MESSAGE_ID/reply" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks — we are on it. Your order ships tomorrow."}'

{ "message_id": "OUT_ID", "queued": 1, "thread_id": "THREAD_ID", "inbox_message_id": "SENT_COPY_ID" }

The reply stays in the thread, always goes out From the inbox address (so DKIM alignment holds), and passes through the same quotas and suppression list as any other send. If policy holds it, you get { "held": true, "approval_id": "…", "reason": "dlp" } instead, and a human approves or rejects it in the console or via POST /v1/approvals/{id}/approve.

That is the loop: receive → reason → reply.

5. Run the mailbox

The inbox is a complete mailbox you drive over the API — no UI required:

# Folders with counts
curl "$API/v1/inboxes/$INBOX_ID/folders" -H "Authorization: Bearer $AGENT_KEY"
# File a message
curl -X POST "$API/v1/inbox-messages/$MESSAGE_ID/move" -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" -d '{"folder": "archive"}'
# Search
curl "$API/v1/inboxes/$INBOX_ID/search?q=invoice" -H "Authorization: Bearer $AGENT_KEY"

Full details in Inboxes. The same inbox is also reachable over IMAP and SMTP and as an MCP tool set.