An email inbox for Python agents
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
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.
pip install trottamailRequests 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.
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.
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.
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.
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.
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: the Python and TypeScript clients, and every command.
- API reference: every route, field and error.
- Webhooks: a signed event posted to your endpoint when mail arrives, with a Python function that verifies the signature.
- Live events: the same events over a stream, with no public endpoint.
- Pods: one isolated workspace per customer.
- 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.