# How to give an AI agent an email address

> A hands-on guide: get an address for your AI agent with one call, wait for mail, read it safely and reply, with working Python and TypeScript examples.

Source: https://trotta.email/learn/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 November 20, 2026

## 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](https://trotta.email/learn/agent-identity-email) 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](https://trotta.email/learn/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:

```bash
curl -X POST https://api.trotta.email/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "riley"}'
```

201 Created:

```json
{
  "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:

```python
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:

```typescript
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:

```python
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:

```typescript
// 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](https://trotta.email/learn/email-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.

| Field | What it holds |
| --- | --- |
| `text` | The safe text of the message |
| `extracted_text` | The new part only: no quoted history, no signature |
| `extracted.codes` | Verification codes, already parsed |
| `extracted.verify_links` | Confirmation links |
| `verdict` | What the guard decided (`deliver`, `flag`, `hold`, `reject`) and why |
| `thread_id` | The 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:

```python
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:

```python
answer = your_model(ctx["context"])

requests.post(
    f"{API}/messages/{msg['id']}/reply",
    json={"text": answer},
    headers=auth,
)
```

TypeScript: context and reply:

```typescript
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:

```bash
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](https://trotta.email/docs/domains) and [custom domain email for agents](https://trotta.email/learn/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](https://trotta.email/signup) 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](https://trotta.email/integrations), starting with [ChatGPT](https://trotta.email/integrations/chatgpt) and [Claude](https://trotta.email/integrations/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](https://trotta.email/learn/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.

## Related

- [Quickstart for agents](https://trotta.email/docs) Docs
- [API reference](https://trotta.email/docs/api) Docs
- [ChatGPT](https://trotta.email/integrations/chatgpt) Integrations
- [Python](https://trotta.email/integrations/python) Integrations
- [How an AI agent receives a verification code by email](https://trotta.email/learn/verification-codes-for-ai-agents) Guides
- [Agent hijacking](https://trotta.email/threats/agent-hijacking) Threat library

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

[Get an inbox](https://trotta.email/signup) [Read the docs](https://trotta.email/docs)
