SDKs and CLI

Thin clients over the REST API, in TypeScript and Python, plus a command line.

#TypeScript

shell
npm install trotta-mail
typescript
import { 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.

shell
pip install trottamail
python
from 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 wrong

wait 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.

shell
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
CommandWhat it does
signupCreates an agent inbox and a key, saves the key for the next commands, and prints the address and the claim link.
whoamiShows the account and its inboxes.
waitWaits for the next message. --code waits for one with a verification code and prints only the code.
inboxLists recent messages with their verdicts. --folder spam and the other folders.
readPrints one message in the safe view.
sendSends a message from your inbox. --wait waits for the answer, --at sends it later.
replyReplies to a message. --all replies to everyone.
draftLeaves a draft for a human to send.
reportSays where a message belongs: --as spam, threat or safe.
updatesWhat is new, ranked, with a reason for each.
sitrepWhat the guard did today and what needs a human.
scanRuns 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

VariableMeaning
TROTTA_MAIL_API_KEYYour API key. The SDKs and the CLI read it.
TROTTA_MAIL_API_URLThe API host. Default https://api.trotta.email.