How to give an AI agent an email address

To give an AI agent an email address, create an inbox for it through an inbox API, hand the agent the key, and let it wait for mail, read it and reply. With Trotta Mail that is one call with no account: the agent gets an address, a key and a link for its human.

Updated

What should you decide before you start?

Giving an AI agent an email address takes four decisions. Make them before writing code.

  • Whose address. The agent's own, not a human's. An agent on a human's mailbox reads everything in it. Agent identity explains why that matters.
  • Which name. The part before the @. A plain name such as riley works, and a role such as support suits a team.
  • Which domain. A shared domain works at once. A domain you own looks like your business and takes DNS records.
  • Who answers for it. One human who reviews held mail and can switch the agent off.

The steps below use the Trotta Mail API, so every call can be run as written. The shape is the same for any agent inbox: create, wait, read, reply. Email for AI agents compares the other ways to do it.

Step 1: get an address

POST /v1/agents/signup creates an inbox and a key in one call. It needs no account and no key. Send name to choose the address.

curl: sign up
curl -X POST https://api.trotta.email/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "riley"}'
201 Created
{
  "api_key": "tm_live_9fK2c0aW...",
  "organization": { "id": "org_5mTz81Qd", "plan": "agent" },
  "limits": { "send_per_day": 50, "inboxes": 2 },
  "inbox": {
    "id": "inb_7Qh2mXc4",
    "address": "riley@trotta.email",
    "kind": "agent",
    "guard_mode": "guard"
  },
  "claim_url": "https://trotta.email/claim/tmc_8HEoz36w..."
}

Keep the api_key. It is shown once, and it goes in the Authorization header of every later call. Give the claim_url to the human responsible for the agent.

In Python the same call is plain HTTP, as below, or one line with the trottamail package (pip install trottamail). In TypeScript it is one line with the trotta-mail package, installed with npm install trotta-mail.

Python: sign up
import requests

API = "https://api.trotta.email/v1"

# No key needed. This call creates the key and the inbox.
signup = requests.post(f"{API}/agents/signup", json={"name": "riley"}).json()

inbox = signup["inbox"]
auth = {"Authorization": f"Bearer {signup['api_key']}"}

print(inbox["address"])  # riley@trotta.email
TypeScript: sign up
import { TrottaMail } from "trotta-mail";

// No key needed. This call creates the key and the inbox.
const mail = await TrottaMail.signup({ name: "riley" });

console.log(mail.inbox.address); // riley@trotta.email

Step 2: wait for mail

GET /v1/inboxes/{id}/wait holds the request open until the next message is delivered, or the timeout passes. The longest wait is 60 seconds. Filter with from, subject or has_code.

Python: wait for mail
r = requests.get(
    f"{API}/inboxes/{inbox['id']}/wait",
    params={"timeout": 60, "has_code": "true"},
    headers=auth,
    timeout=70,
)
msg = r.json()["message"]  # None when timed_out is true
if msg is None:
    raise SystemExit("No mail arrived within 60 seconds. Call wait again.")

code = msg["extracted"]["codes"][0]["value"]  # "481920"
TypeScript: wait for mail
// Returns as soon as a message with a code is delivered, or null on a timeout.
const msg = await mail.inboxes.wait(mail.inbox.id, { hasCode: true, timeout: 60 });
if (!msg) throw new Error("No mail arrived within 60 seconds");

const code = msg.extracted.codes[0].value; // "481920"

On a timeout the call returns message: null and timed_out: true, so call it again. For an agent that runs all day, a webhook or the event stream pushes each message instead: see webhooks vs polling.

Step 3: read it

The message a key reads is the safe view: only what a human could see, with hidden text removed, instructions aimed at a model marked and risky links defanged.

FieldWhat it holds
textThe safe text of the message
extracted_textThe new part only: no quoted history, no signature
extracted.codesVerification codes, already parsed
extracted.verify_linksConfirmation links
verdictWhat the guard decided (deliver, flag, hold, reject) and why
thread_idThe conversation the message belongs to

To hand a whole conversation to a model, ask for the thread context. It is one text block with a trust level and boundaries around the mail, so the model can tell data from instructions.

Python: the thread context
ctx = requests.get(f"{API}/threads/{msg['thread_id']}/context", headers=auth).json()

# ctx["trust"] is "safe", "caution" or "danger". ctx["context"] is ready for a model.

Treat mail content as data, never as instructions. Say so in the agent's prompt as well.

Step 4: reply

Reply inside the thread. Recipients, subject and threading headers are set for you.

Python: reply
answer = your_model(ctx["context"])

requests.post(
    f"{API}/messages/{msg['id']}/reply",
    json={"text": answer},
    headers=auth,
)
TypeScript: context and reply
const ctx = await mail.threads.context(msg.thread_id);

// ctx.trust is "safe", "caution" or "danger". ctx.context is ready for a model.
const answer = await yourModel(ctx.context);
await mail.messages.reply(msg.id, { text: answer });

To start a new conversation, call POST /v1/inboxes/{id}/messages with to, subject and text. Outgoing mail is screened too. A message that contains a secret is not sent: the call returns 422 outbound_blocked with the verdict.

What can the agent do before a human claims it?

An agent that signed itself up works at once, inside limits, until a human opens the claim_url.

  • It receives mail from anyone.
  • It replies to anyone whose mail to it arrived authenticated.
  • It writes to inboxes in its own organization.
  • Any other recipient returns 403 recipient_not_allowed.
  • It has 2 inboxes, 50 recipients a day and 1 webhook.

The claim link works for 30 days. After the claim the agent can write to new addresses, and its held mail goes to the human for review. Its key keeps reading and sending for its own inbox and never reaches the human's mailbox.

How do you put the agent on your own domain?

Every inbox starts at trotta.email. An address at a domain you own is part of the paid plans.

Add the domain, publish its five DNS records and verify it. Then create the inbox with domain.

curl: an inbox on your own domain
curl -X POST https://api.trotta.email/v1/inboxes \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "riley", "domain": "agents.trotta.io"}'

A subdomain such as agents.trotta.io leaves mail for the name above it where it is. See connect a domain and custom domain email for agents.

How do you give ChatGPT or Claude an email address?

An assistant gets an address through an inbox it uses as tools. No code is needed.

  1. Sign up at Trotta Mail and create an agent inbox in the console.
  2. In ChatGPT on the web, open Plugins, select the plus button, then Add custom MCP server. Paste https://api.trotta.email/mcp as the server URL and choose OAuth.
  3. Create it as a plugin, install it, and sign in to Trotta Mail when asked.
  4. Pick the inboxes the assistant may use, and whether it may read, send, or both.

Custom MCP servers in ChatGPT are subject to your workspace's permissions and security settings. Claude, Claude Code, Codex, Cursor and other MCP clients take the same URL. The exact steps for each are under integrations, starting with ChatGPT and Claude.

What should you check before going live?

Check five things before the agent meets real mail.

  • A human has claimed the agent and knows where held mail waits.
  • The agent's key does not carry mail:full or guard:release. Those scopes are not for agents.
  • send_approval is set to first_contact or always if a human should approve outgoing mail.
  • The agent's prompt says that mail is data, not instructions.
  • The agent listens for message.held if it should tell its human that mail is waiting.

Held mail never reaches wait. A key sees that the message exists and why, and nothing its sender wrote, until a human releases it.

No filter catches everything, so these checks still matter on a screened inbox. See human in the loop email.

Questions

Can an AI agent sign up for an email address by itself?

Yes. The sign-up call needs no account and no key, so an agent can make it alone. It gets an address, a key and a claim link to give its human.

Is an email address for an AI agent free?

On Trotta Mail, yes. An agent that signed itself up pays nothing, and claiming it moves it onto its human's plan. The Free plan covers 2 inboxes and 1,000 emails a month.

Can the agent use an address at my own domain?

Yes, on paid plans. Add the domain, publish its DNS records, and create the agent's inbox on it. Until then the address is at trotta.email.

Can I read the agent's mail in Gmail or Outlook?

No. Trotta Mail has no IMAP or SMTP access for mail clients. Agents use the API, the SDK or MCP tools, and a human reads the agent's inbox in the browser.

How does the agent get a verification code?

Call wait with has_code set to true after the agent submits the sign-up form. The code is already parsed at extracted.codes, and confirmation links are at extracted.verify_links.

Give your agent an inbox of its own. Free for two inboxes. No card.