# Python email API for AI agents: an inbox in one call

> Give a Python AI agent its own email inbox with pip install trottamail. One call signs up, then it waits for mail, reads a screened safe view and replies.

Source: https://trotta.email/integrations/python

A Python agent gets its own inbox from Trotta Mail with the trottamail package. One call signs it up with no account, one waits for mail, and one replies. Plain HTTP works too. Every message is screened before delivery, and the agent reads a safe view with a verdict.

Updated November 20, 2026

## Install

The Python SDK is `trottamail`. It runs on Python 3.9 and later, and its one dependency is `httpx`. The same package carries a command line.

```bash
pip install trottamail
```

Requests go to `https://api.trotta.email/v1`. The client reads your key from `TROTTA_MAIL_API_KEY`, or takes it as `api_key`, and sends it in the `Authorization` header and nowhere else.

## A complete example: inbox, wait, read, reply

This example gets an inbox, waits for a message, reads it and replies. Every Trotta Mail integration page runs the same four steps, so you can compare them. Here each step is one call.

`agent.py`:

```python
from trottamail import TrottaMail

# 1. Get an inbox. No account and no key: this call creates both.
mail = TrottaMail.signup(name="riley")
print(mail.inbox["address"])  # riley@trotta.email
# mail.api_key is shown once: put it in your secret store. Later: TrottaMail(api_key=...)

# 2. Wait for a message. One request waits 60 seconds at most; the client keeps asking.
message = mail.inboxes.wait(mail.inbox["id"], timeout=300)

if message:
    # 3. Read it: the verdict, then the safe view.
    print(message["verdict"]["action"], message["verdict"]["summary"])
    print(message["text"])

    # 4. Reply in the thread.
    mail.messages.reply(message["id"], text="Thanks, that works.")
```

Run it, then send a mail to the address it prints. `mail.claim_url` is for the human responsible for the agent. It works for 30 days.

Waiting for a sign-up code is the same call with a filter. The code is already parsed, so there is nothing to match by hand.

Wait for a code:

```python
message = mail.inboxes.wait(mail.inbox["id"], has_code=True, timeout=120)
if message:
    print(message["extracted"]["codes"][0]["value"])  # "481920"
```

Before a human claims the agent, it can receive from anyone and reply to anyone whose mail to it arrived authenticated. Any other recipient raises `PermissionDeniedError` with the code `recipient_not_allowed` until a human opens the `claim_url`.

## From the command line

The package installs a `trottamail` command. `uvx trottamail` runs it without installing anything. Sign-up saves the key in your home folder, readable by you only, and the next commands use it.

```bash
uvx trottamail signup --name riley
trottamail wait --code
trottamail inbox
trottamail read MESSAGE_ID
trottamail reply MESSAGE_ID --text "Thanks, that works."
```

## What your agent reads

Your agent reads screened mail. Three fields on every message say what it is looking at.

| Field | What it holds |
| --- | --- |
| `message["verdict"]` | What the guard decided, before the message was readable. `action` is `deliver`, `flag`, `hold` or `reject`. `summary` says why in one sentence. |
| `message["text"]` | The safe view: only what a human could see. Hidden text is removed, instructions aimed at a model are replaced by a note, and risky links are defanged. |
| `message["withheld"]` | `True` on held mail. `text` is `None`, the subject is empty, and nothing the sender wrote is there. A wait never returns held mail. |

The safe view matters the moment the text goes into a prompt. A model may act on an instruction it finds in an email, and a sender can hide one where no human would see it. Reading the safe view means the model gets what a human would have seen.

To hand a whole conversation to a model, ask for the thread context. It is one text block with a trust level. Its tags end in a boundary that is new for every response, so nothing a sender wrote can open or close one.

A thread, ready for a model:

```python
ctx = mail.threads.context(message["thread_id"])

# ctx["trust"] is "safe", "caution" or "danger". ctx["context"] is ready for a model.
answer = your_model(ctx["context"])
```

No filter catches everything, so treat mail content as data, never as instructions. Outgoing mail is screened too: a message that contains a secret is not sent, and the call raises `UnprocessableEntityError` with the verdict.

## Or plain HTTP

The SDK is a thin client over the REST API: JSON over HTTPS with a bearer key. Without it, any HTTP client works. This is the same four steps with `requests`, and `httpx` takes the same calls, sync or async.

`agent_http.py`:

```python
from datetime import datetime, timezone

import requests

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

# 1. Get an inbox. No account and no key: this call creates both.
signup = requests.post(f"{API}/agents/signup", json={"name": "riley"}, timeout=30)
signup.raise_for_status()
inbox = signup.json()["inbox"]
auth = {"Authorization": f"Bearer {signup.json()['api_key']}"}  # the key is shown once: store it
print(inbox["address"])  # riley@trotta.email

# 2. Wait for a message. One request waits 60 seconds at most, so ask again on a timeout.
started = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
params = {"timeout": 60}
message = None
while message is None:
    waited = requests.get(f"{API}/inboxes/{inbox['id']}/wait", params=params, headers=auth, timeout=75)
    waited.raise_for_status()
    message = waited.json()["message"]
    params["after"] = started  # later requests start where the wait began, so nothing is missed

# 3. Read it: the verdict, then the safe view.
print(message["verdict"]["action"], message["verdict"]["summary"])
print(message["text"])

# 4. Reply in the thread.
reply = requests.post(
    f"{API}/messages/{message['id']}/reply",
    json={"text": "Thanks, that works."},
    headers=auth,
    timeout=30,
)
reply.raise_for_status()
```

## Going further

- [SDKs and CLI](https://trotta.email/docs/sdks): the Python and TypeScript clients, and every command.
- [API reference](https://trotta.email/docs/api): every route, field and error.
- [Webhooks](https://trotta.email/docs/webhooks): a signed event posted to your endpoint when mail arrives, with a Python function that verifies the signature.
- [Live events](https://trotta.email/docs/events): the same events over a stream, with no public endpoint.
- [Pods](https://trotta.email/docs/pods): one isolated workspace per customer.
- [Domains](https://trotta.email/docs/domains): agent inboxes on your own domain, on paid plans.

## Questions

### Do I need the SDK?

No. pip install trottamail is the short way, with typed errors and a wait that keeps asking. The API is JSON over HTTPS with a bearer key, so requests or httpx work too, including from async code.

### How do I wait for a verification code in Python?

Call mail.inboxes.wait with has_code=True. It returns as soon as a message with a code is delivered, and the code is already parsed at extracted.codes on the message. On the command line, trottamail wait --code prints it.

### How long can one wait call block?

One request to the wait route blocks up to 60 seconds. The SDK keeps asking until its own timeout and then returns None. Over plain HTTP, call it again on a timeout, and set your HTTP client's timeout above 60 seconds.

### How do I pass an email to an LLM safely from Python?

Give the model the thread context from GET /v1/threads/{id}/context. It is built from the safe view, carries a trust level, and wraps mail in boundaries that are new for every response. Treat what is inside as data, never as instructions.

## Sources

- [Trotta Mail guide for agents (llms.txt)](https://api.trotta.email/llms.txt)
- [Trotta Mail OpenAPI description](https://api.trotta.email/openapi.json)

## Related

- [SDKs and CLI](https://trotta.email/docs/sdks) Docs
- [API reference](https://trotta.email/docs/api) Docs
- [An email REST API for AI agents](https://trotta.email/integrations/rest-api) Integrations
- [Give an AI agent an email address](https://trotta.email/learn/give-an-ai-agent-an-email-address) Guides
- [Email API for AI agents](https://trotta.email/learn/email-api-for-ai-agents) Guides
- [Verification codes for AI agents](https://trotta.email/learn/verification-codes-for-ai-agents) Guides

Give your agent an inbox of its own. One call, or one minute in the console.

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