How to Give Your AI Agent an Email Inbox

Giving an AI agent its own email inbox is the difference between an agent that can notify you and an agent that can actually do email - read the thread, understand the context, draft a reply, and act. This guide walks through exactly how to do it: what an "agent inbox" needs to be, the concrete steps to wire one up, and how to keep a human in control of every send.

What does it mean to give an agent an email inbox?#

Giving an AI agent an email inbox means letting it operate a real, two-way mailbox programmatically: it can read incoming mail, search and thread conversations, draft replies in context, and send (or queue for approval) - all over an authenticated API, scoped to the accounts you allow. It is the inbox an agent lives in, not a one-way pipe for blasting messages.

That distinction matters because most "email APIs" were built for the opposite job: sending transactional mail - receipts, password resets, alerts - one direction, fire and forget. An agent needs the inbound half too. If it cannot read the thread, it cannot reply intelligently. So the first decision is not "which sending API" but "what gives my agent a genuine inbox."

What a real agent inbox needs#

Before the steps, here is the checklist. A mailbox is "agent-ready" when an agent holding one credential can do all of this over HTTP:

• Read. List and filter emails, full-text search, read full bodies and attachments.
• Understand. Walk conversation threads, see who is talking, read contacts and calendar context.
• Act. Draft a reply, compose a new email, or run outreach - in the agent's own copy or AI-generated.
• Stay safe. Be scoped to only the accounts it is allowed to touch, and (ideally) be unable to send without a human approving.
• Self-throttle. Read its own quota and respect rate limits so it never runs away.

Anything missing from that list, you end up building yourself. The point of an agent inbox platform is that all of it already exists.

Step 1: Connect a mailbox#

Start with a real inbox the agent will operate - a support address, a founder inbox, a per-business mailbox. In AutoEmail you connect a business inbox once; from then on it is a managed mailbox with stored threads, full-text search, spam scoring, and AI drafting already running on it. The agent will operate this same inbox a human can also see, which is what keeps agent and human work in one place.

Step 2: Issue the agent a scoped API key#

Your agent authenticates as itself with a single Bearer API key. The key is the security boundary, so it carries two critical properties:

1. An account allowlist - the exact mailboxes this key may read and write. Anything else is invisible to the agent (requests for out-of-scope accounts simply return 404, never leaking that they exist).
2. A mode - whether writes send or only draft. This is the human-in-the-loop switch (Step 4).

In AutoEmail, keys are created in Settings -> API Keys and look like ak_live_.... The plaintext is shown exactly once and stored only as a hash, so treat it like a password and keep it server-side. This API is CORS-closed on purpose: call it from a backend, never from browser JavaScript.

Step 3: Teach the agent to read and act#

Every agent session should start by discovering its own capabilities, then read before it writes. The shape of a session looks like this:

# 1) Who am I, and what can I touch?
curl -s "$BASE/me" -H "Authorization: Bearer $KEY"
# -> { "mode": "human_in_the_loop", "allowedAccounts": [ { "businessId": "...", "email": "support@acme.com" } ] }

# 2) Read the latest mail for an allowed account.
curl -s "$BASE/emails?businessId=$BIZ&pageSize=20" -H "Authorization: Bearer $KEY"

# 3) Search across the agent's accounts.
curl -s "$BASE/search?q=refund%20invoice" -H "Authorization: Bearer $KEY"

# 4) Read one full email + its latest draft.
curl -s "$BASE/emails/$ID" -H "Authorization: Bearer $KEY"

GET /me first is the habit that makes agents robust: it tells the agent whether its writes will send or draft, and which businessIds it can use. From there GET /emails, GET /search, GET /emails/{id}, and GET /threads/{id} give it everything it needs to understand a conversation before replying.

When it is time to act, the agent replies to an existing email or composes a new one - and it can either supply final copy or let the platform generate it:

# Reply with the agent's own copy.
curl -s -X POST "$BASE/emails/$ID/reply" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-$ID-001" \
  -d '{"body":"Your order shipped yesterday - tracking is attached."}'

# Or let AutoEmail write the reply from a brief (uses your voice + knowledge base + lessons).
curl -s -X POST "$BASE/emails/$ID/reply" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"mode":"generate","brief":"Apologize for the delay and ask for the order number.","tone":"warm, concise","send":false}'

The full surface - emails, search, threads, drafts, contacts, calendar, outreach, spam settings, lessons, usage - is documented in the OpenAPI 3.1 spec at /openapi.json and you can try every endpoint live with your own key at /docs. That is the whole point of an agent-ready API: the contract is machine-readable, so an agent (or an MCP server in front of it) can discover and call it.

Step 4: Keep a human in the loop#

Here is the step most "give your agent email" tutorials skip, and the one that matters most. The moment an agent can send, it can send the wrong thing - a wrong price, a wrong commitment, the wrong recipient - confidently and irreversibly. The fix is not better prompts. It is architecture.

In AutoEmail the key's mode decides what a write actually does:

• human_in_the_loop (the safe default): the agent's reply, compose, and outreach calls never send. Each one becomes a pending draft in the same dashboard approval queue a human already uses. A person scans it and sends - or edits first, or declines with feedback that teaches the AI. The agent does all the reading and drafting; the human keeps the final call.
• full_autonomous: writes send immediately. Use this only for low-stakes mail you are comfortable letting fly.

The elegant part: the agent's code does not change between modes. The same POST /emails/{id}/reply produces a send with one key and a draft-for-approval with another. You dial the trust level per key, not per integration. That is the heart of human-in-the-loop AI for email.

Step 5: Let it self-throttle and stay idempotent#

Two final habits make an agent production-grade. First, read your quota so the agent throttles before it hits a wall - GET /usage returns what is left, and every billable write fails fast with 402 (and refunds the unit if the action produced nothing). Second, send an Idempotency-Key on every write so a retry after a network blip replays the original result instead of double-sending. Both are built in; the agent just has to use them.

Putting it together#

The mental model is simple: connect a mailbox, issue a scoped key, read before you write, and keep a human on the send button. Do that and your agent is not a glorified notifier - it is operating a real inbox, safely, with you in control of anything that matters.

For the full architecture, see how AutoEmail works as an email API for AI agents. If you want to expose this inbox through the Model Context Protocol, the MCP email server guide shows the wiring. And for the safety model specifically, human-in-the-loop email for AI agents goes deep.