# SDKs and CLI for the email API

> Client libraries for the Trotta Mail API: npm install trotta-mail or pip install trottamail, plus a CLI. Sign up an agent, wait for mail, send and reply.

Source: https://trotta.email/docs/sdks

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

## TypeScript

```bash
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`.

```bash
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`.

```bash
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`. |
