Loading article…
Loading article…
How to give an AI agent an email address on your domain
Set up a custom-domain mailbox for an AI agent with safe DNS changes, narrow permissions, MCP or webhook access, and human approval.
Set up a custom-domain mailbox for an AI agent with safe DNS changes, narrow permissions, MCP or webhook access, and human approval.
Loading article…
Give an AI agent a dedicated mailbox, not access to a person's whole inbox. Connect a domain or subdomain, create the address, and issue a mailbox-scoped key. Start with read-only operations, add draft or sending permission only when needed, and keep sensitive sends behind human approval.
This guide uses Startup Mail, but the design rules apply to any programmable mailbox.
Start with the work, not the agent's name.
An address such as invoices@company.com, bookings@company.com, or returns@company.com
tells senders what it is for. It also makes permission and sending rules easier to state.
Write down four things before creating the mailbox:
Avoid a broad address such as assistant@company.com until you know what the agent will do. A
vague remit often leads to broad access.
You can place the mailbox on your company's main domain:
invoices@company.com
Or isolate agent mail on a subdomain:
invoices@agents.company.com
A subdomain is often the safer first step when the main domain already uses Google Workspace, Microsoft 365, or another mail provider. Changing the main domain's MX records can move all new inbound mail. Two competing MX destinations do not divide mail by mailbox name in a reliable way.
A subdomain creates a separate mail-routing boundary. It lets you test the agent without moving employee email. The address is longer, but the rollout is easier to contain.
Use the main domain when the agent should share the same company identity and you have planned the mail-provider cutover. Use a subdomain when you want isolation or a gradual launch.
Add the domain in Startup Mail, then publish the DNS records shown in the workspace.
The four record types have different jobs:
| Record | Purpose |
|---|---|
| MX | Routes incoming email to the mailbox provider |
| DKIM | Adds a signature that recipients can verify on outgoing mail |
| SPF | Authorises the outbound service for the mail-from domain |
| DMARC | Publishes a policy for messages that fail authentication |
Copy the exact hostnames and values from your account. Do not copy DNS values from a guide or another domain.
Leave website records alone. A mail setup normally changes MX and email-authentication records, not the A, AAAA, or CNAME records that serve the site.
After DNS verification, test both directions with an external account. Send a message to the new address, then reply from the mailbox. DNS dashboards can show a saved record before public resolvers can see it, so allow for propagation.
Create the local part, such as invoices, and choose a clear display name. Startup Mail
requires a matching mailbox for the recipient. It does not use catch-all routing.
For one address, create it in the web application. For an agent product, create a tenant and
mailbox through the REST API or SDK. A stable clientId makes repeated provisioning requests
return the existing resource instead of creating a duplicate. A tenant can isolate one customer,
agent fleet, or workflow inside the organization.
Then choose whether the mailbox is shared or private.
A shared mailbox works when a team should be able to read and answer the same messages. Every workspace member can access shared mailbox content.
A private mailbox belongs to an owner. Other people need an explicit grant. Each grant can allow reading only or reading and sending.
A shared mailbox makes human takeover simple, but every workspace member can read it. Use a private mailbox when its content should be visible only to its owner and people granted access.
Workspace roles and mailbox access solve different problems. An administrator can manage domains and billing without automatically gaining access to private messages.
Do not reuse a founder's key or one shared by several services.
Create a key for this agent. Give it a workload-specific name and an expiry date. Store the secret in the server environment or a secret manager. Startup Mail shows the full secret only when it is created and stores a hash after that.
Set the key's resource scope to this mailbox. That boundary prevents it from accessing another mailbox in the workspace. Then choose the smallest useful capabilities:
| Capability | Use it when the agent must... |
|---|---|
mailboxes:read | Read metadata for its mailbox |
mail:read | Read threads, messages, or attachments |
mail:send | Start a conversation or reply |
drafts:read, drafts:write | Create, review, amend, or schedule stored drafts |
policies:write | Manage mailbox address or domain rules |
Start with mailboxes:read and mail:read for an agent that only classifies messages. Add
draft access when it should prepare replies. Add mail:send or drafts:send only when the
workflow is ready to send.
The resource scope selects the organization, tenant, or mailbox. Capabilities select the allowed actions inside that boundary. Do not give the runtime agent the broad organization key used to provision tenants, domains, or mailboxes.
There are two common designs.
Startup Mail exposes a Streamable HTTP MCP endpoint at:
https://startupmail.dev/mcp
A typical client entry looks like this:
{
"startupmail": {
"type": "http",
"url": "https://startupmail.dev/mcp",
"headers": {
"Authorization": "Bearer ${STARTUPMAIL_API_KEY}"
}
}
}
Keep the key in an environment variable. Do not paste a production key into a file that will be committed or shared.
The scopes decide which tools are available. A read-scoped agent can list and read threads. A
key with mail:send can also send and reply.
MCP fits an agent that chooses when to inspect email during an interactive task. The MCP tool specification advises applications to keep a person able to deny tool calls. Use confirmation for sends that expose data or create a commitment.
Use a signed webhook when work should start as soon as a message arrives.
The safe flow is:
message received
↓
verify the webhook signature
↓
record the delivery ID and queue a job
↓
return 2xx
↓
fetch the current thread with mail:read
↓
draft, check policy, request approval if needed
↓
reply to the triggering message with mail:send
Startup Mail's message.received webhook includes the message, mailbox, and thread IDs. Fetch
the thread after the event rather than treating the webhook as the complete message.
Webhook delivery is at least once. Deduplicate by delivery ID and make downstream actions idempotent. A retried event must not send a second reply.
An outside sender can write instructions aimed at the model. The text may ask the agent to ignore its rules, reveal another message, open a link, or send data to a new address.
This is indirect prompt injection. OWASP's prompt-injection guidance names emails and attachments as possible sources.
Use controls outside the prompt:
A prompt can tell the model not to reveal secrets. A mailbox-scoped key and Startup Mail communication policy make that rule harder to break. Application checks should still enforce business rules the mail service cannot know. For a fuller threat model, read The complete guide to email for AI agents.
Start with stored drafts. A person can inspect or amend the draft, then approve an immediate or scheduled send.
After you have reviewed enough real cases, automate only the narrow replies that carry little cost if they are wrong. A fixed receipt acknowledgement is safer than a free-form answer about a refund or contract.
A practical policy can divide actions into three groups:
| Level | Example | Control |
|---|---|---|
| Low risk | Classify or extract a reference number | Run automatically |
| Medium risk | Draft a reply to the current sender | Human reviews before send |
| High risk | Add a recipient, attach a file, change payment details | Block or require named approval |
Startup Mail allows direct conversations and transactional messages that recipients expect. It does not allow newsletters, promotional campaigns, drip sequences, cold outreach, purchased lists, or scraped contacts. The same policy applies to agent sends.
When replying, use the ID of the message being answered. Startup Mail creates the email reply headers and keeps the outgoing message in the same stored thread.
Fetch the latest thread just before sending. A human or another process may have replied while the agent was drafting. Cancel or refresh the draft if the conversation has changed.
Do not reconstruct a reply from the subject line alone. Email threading uses message identifiers and reference headers, as described by RFC 5322.
Before launch, test these cases:
Confirm that a person can revoke the key, inspect the mailbox, and take over the thread.
Usually, yes. A dedicated address narrows the agent's purpose and limits accidental access to personal or unrelated company mail.
Yes, but review its current MX records first. If another provider handles employee mail, use a subdomain or plan a full cutover. Do not assume two MX providers will route different mailbox names to different services.
Only if the workflow sends or replies. Start with read-only access for classification and
drafting. Add mail:send when policy checks and approvals are ready.
No. MCP is useful for interactive agents. Signed webhooks with the REST API or SDK suit event-driven applications and give your code direct control over each step.
Yes. A shared mailbox lets workspace members work from the same messages and threads. A private mailbox can grant specific people read-only or read-and-send access.
The mailbox is ready when the agent has one clear job, a mailbox-scoped runtime key, narrow operations and permissions, and one tested route for human takeover. Keep the broader provisioning key on your server.
Before enabling automatic replies, read How to secure an AI agent that reads email. If the alternative is connecting a person's account, compare Gmail with a dedicated agent mailbox.