Loading article…
Loading article…
The complete guide to email for AI agents
Learn how to give an AI agent a real mailbox with scoped access, durable threads, safe sending, webhooks, MCP tools, and human review.
Learn how to give an AI agent a real mailbox with scoped access, durable threads, safe sending, webhooks, MCP tools, and human review.
Loading article…
An AI agent needs more than the power to send email. It needs an address, a mailbox, conversation history, and clear limits on what it may read or do.
A safer design treats the agent as a new team member with narrow access. Give it a dedicated mailbox and key, start with read-only permission, and require human approval before sensitive replies. Before launch, verify every mailbox the key can see. Add more freedom only after the workflow proves reliable.
There are three common setups. A send-only agent sends alerts or requested reports. An email-processing agent receives messages through a webhook or API. A mailbox agent has a persistent identity, reads complete conversations, and replies in the same thread.
The third setup supports ongoing conversations, but it also carries the most risk. An incoming email is untrusted input. A reply is an external action made under your company's name.
A mailbox gives the agent a durable address such as invoices@company.com or
bookings@company.com. New messages remain available after the first event has fired.
Replies stay tied to the conversation.
This matters because email work rarely ends with one message. A vendor may answer two days later. A customer may change the subject line. A teammate may reply before the agent acts. The agent needs current state, not a single copied payload.
In Startup Mail, the mailbox is the source of truth. The same messages and threads are available in the web inbox, REST API, SDKs, and MCP tools. Signed webhooks notify an application when that state changes. A human and an agent can therefore work from the same record.
MCP, webhooks, and a REST API solve different parts of the job.
The Model Context Protocol, or MCP, lets a compatible agent discover and call a small set of tools. Startup Mail provides tools to list mailboxes and threads, read a thread, send a new message, and reply to a message.
MCP suits an agent that decides when it needs email as part of a wider task. The available tools depend on the API key's capabilities. A read-only key cannot expose sending tools.
MCP does not remove the need for approval. The MCP tool specification recommends keeping a person able to deny tool calls. That is especially important when a tool sends mail, shares private information, or commits the company to an action.
A webhook tells your application that something happened. For example, a
message.received event can start a triage job as soon as mail arrives.
Treat the webhook as a notification. Verify its signature, record the delivery ID, queue the work, and return a successful response quickly. Then fetch the current thread with a read-scoped key.
Webhook delivery can happen more than once. Your handler must be idempotent, which means that processing the same delivery twice does not create two tickets, two payments, or two replies.
Use the REST API or an SDK when your application owns the workflow. It can provision an inbox, fetch the thread, ask a model for a draft, hold that draft for review, and send only after policy checks pass. Keep provisioning credentials on the server.
Do not share one broad API key across several agents.
Create one key for each workload. Give it a clear name and an expiry date. Store it in a server-side secret manager or environment variable. Review its last-used time and revoke it when the agent is retired.
First choose a resource boundary. An organization key can manage the whole workspace, a tenant key stays inside one customer or agent fleet, and a mailbox key can access only one inbox. Give the runtime agent a mailbox-scoped key unless it genuinely manages a tenant.
Then choose its capabilities:
| Capability | What it permits |
|---|---|
mailboxes:read | Read metadata for the scoped mailbox |
mail:read | Read threads and download attachments |
mail:send | Send new mail and reply |
drafts:read, drafts:write | Review, create, amend, and schedule drafts |
policies:write | Manage address and domain allow or block rules |
Most agents do not need every capability. A classifier may need mail:read but not mail:send.
Sending a stored draft requires drafts:send.
Resource scope limits which inboxes the key can reach. Capabilities select the actions allowed inside that resource boundary. Use a mailbox-scoped key for a single agent instead of reusing a broad organization key.
An email can contain instructions aimed at the agent rather than the human recipient. A sender might tell it to ignore its policy, reveal private data, open a link, or forward another customer's message.
This is indirect prompt injection. The OWASP prompt-injection guidance lists email content and attachments as common sources of hostile instructions.
Do not try to solve this with a sentence in the system prompt. Use several controls:
A model can suggest a recipient. Your application should decide whether that recipient is allowed.
A useful policy states what the agent may send, to whom, and under which conditions.
A support agent might reply only to the sender of an open thread. It might block new outbound conversations, bank-detail changes, large refunds, and messages containing secrets.
Apply the policy outside the model. Startup Mail mailbox policies can allow or block an address or domain for sending, receiving, or replies. Application code and human review should still enforce business rules such as refund limits and contract approval.
Startup Mail supports direct and transactional messages that recipients expect. It does not permit newsletters, promotional campaigns, drip sequences, cold outreach, purchased lists, or scraped contacts. An agent follows the same sending rules as a person.
Not every message needs approval. The cost of a mistake should set the threshold.
Classification and data extraction can often run automatically. Startup Mail can keep a reply as a stored draft until a person reviews or amends it, then send it immediately or at a scheduled time. Adding recipients, sending attachments, sharing customer data, changing payment details, or agreeing to business terms should pause for review.
The approval screen should show the original thread, proposed recipients, attachments, and final message. Do not ask a reviewer to approve a summary without the source.
A reply should continue the existing conversation rather than start a message with the same
subject. Standard email uses Message-ID, In-Reply-To, and References headers to link
replies. RFC 5322 describes these fields.
With Startup Mail, the agent replies to a specific message ID. The service creates the reply headers and associates the sent message with the stored thread.
Thread state helps the agent avoid repeated questions and stale replies. Fetch the current thread just before drafting or sending. Another person or process may have responded since the webhook arrived.
Startup Mail sanitizes HTML, displays it in a restricted frame, and blocks remote resources in the web inbox. Raw MIME and attachments are stored in private object storage. Downloads still require workspace and mailbox permission.
Those controls protect the mailbox, but they do not make content safe for an agent. Treat attachments as untrusted even after spam and virus checks pass. Do not execute macros, scripts, or embedded commands. Extract only the file types and fields the workflow needs. Put document processing in an isolated environment with strict resource limits.
Avoid sending a whole mailbox or attachment archive to a model when one message or page is enough. Data minimization lowers privacy risk and reduces the chance that irrelevant hostile content reaches the agent.
Email and webhook delivery are asynchronous. Two events can arrive close together. A webhook can be retried. A human can reply while an agent is drafting.
Use these safeguards:
Startup Mail returns 202 Accepted when a send enters its delivery process. That is not proof
that the recipient's server accepted the message. Track delivery state when the workflow needs
a firm outcome.
Before letting an agent read or send company email, check that:
Use a shared mailbox when a team should be able to inspect and answer the same mail, such as
support@. Use a private mailbox when the content belongs to one owner and access must be
granted person by person. In either case, give the agent a mailbox-scoped key with only the
operations and permissions it needs.
No. MCP is useful when a compatible agent should discover and call email tools. Webhooks and a REST API often fit event-driven or tightly controlled application workflows better.
Yes, but automatic sending should be limited to narrow, low-risk cases. Apply recipient, content, and business rules in code. Require human approval when a reply shares sensitive data or creates a commitment.
The sound test is simple: if the agent acts on an email, can a person see what it saw, stop the action, and take over the same thread? If not, the workflow needs stronger controls.
For the setup steps, read How to give an AI agent an email address. For event processing, read Inbound email webhook vs persistent mailbox. For a focused threat model, read How to secure an AI agent that reads email. If you are deciding whether to connect an existing account, read Gmail vs a dedicated agent mailbox.