SDKs and CLI
Thin clients over the REST API, in TypeScript and Python, plus a command line.
#TypeScript
npm install trotta-mailimport { TrottaMail } from "trotta-mail";
// No key needed: this creates the key and the inbox.
const mail = await TrottaMail.signup({ name: "riley" });
// mail.apiKey, mail.inbox
// Or use a key you already have.
// const mail = new TrottaMail({ apiKey: process.env.TROTTA_MAIL_API_KEY });
const msg = await mail.inboxes.wait(mail.inbox.id, { hasCode: true, timeout: 60 });
msg.extracted.codes[0].value;
await mail.messages.reply(msg.id, { text: "..." });
// A new address takes a claimed agent: the human opens mail.claimUrl first.
await mail.messages.send(mail.inbox.id, { to: "jordan@trotta.email", subject: "Hi", text: "..." });
const ctx = await mail.threads.context(msg.thread_id); // ctx.context, ctx.trust
const event = await mail.webhooks.verify(rawBody, headers, secret); // throws if the signature is wrong#Python
Python 3.9 and later. One dependency, httpx. Answers are plain dicts, typed in trottamail.types.
pip install trottamailfrom trottamail import TrottaMail
# No key needed: this creates the key and the inbox.
mail = TrottaMail.signup(name="riley")
# mail.api_key (shown once), mail.inbox, mail.claim_url
# Or use a key you already have. TrottaMail() alone reads TROTTA_MAIL_API_KEY.
# mail = TrottaMail(api_key="tm_live_...")
msg = mail.inboxes.wait(mail.inbox["id"], has_code=True, timeout=60)
msg["extracted"]["codes"][0]["value"]
mail.messages.reply(msg["id"], text="...")
# A new address takes a claimed agent: the human opens mail.claim_url first.
mail.messages.send(mail.inbox["id"], to="jordan@trotta.email", subject="Hi", text="...")
ctx = mail.threads.context(msg["thread_id"]) # ctx["context"], ctx["trust"]
event = mail.webhooks.verify(raw_body, headers, secret) # raises ValueError if the signature is wrongwait returns None when nothing arrives in time. Errors are typed: NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError (with verdict) and the rest extend TrottaMailError, with code, message, fix and request_id. Any other route: mail.request("GET", "/plans").
#CLI
The CLI ships with the Python package as trottamail. Run it without installing with uvx trottamail.
uvx trottamail signup --name riley
trottamail wait --code
trottamail inbox
trottamail read <message_id>
trottamail reply <message_id> --text "..."
trottamail send --to jordan@trotta.email --subject Hi --text "..."
trottamail scan < message.eml| Command | What it does |
|---|---|
signup | Creates an agent inbox and a key, saves the key for the next commands, and prints the address and the claim link. |
whoami | Shows the account and its inboxes. |
wait | Waits for the next message. --code waits for one with a verification code and prints only the code. |
inbox | Lists recent messages with their verdicts. --folder spam and the other folders. |
read | Prints one message in the safe view. |
send | Sends a message from your inbox. --wait waits for the answer, --at sends it later. |
reply | Replies to a message. --all replies to everyone. |
draft | Leaves a draft for a human to send. |
report | Says where a message belongs: --as spam, threat or safe. |
updates | What is new, ranked, with a reason for each. |
sitrep | What the guard did today and what needs a human. |
scan | Runs a message file through the guard and prints the verdict. Nothing is stored. |
The body of send, reply and draft comes from --text or from what you pipe in. --json prints the API's answer. The key is saved in ~/.config/trottamail/config.json, readable by you only, and the CLI prints only its start.
#Environment
| Variable | Meaning |
|---|---|
TROTTA_MAIL_API_KEY | Your API key. The SDKs and the CLI read it. |
TROTTA_MAIL_API_URL | The API host. Default https://api.trotta.email. |