# TypeScript and Node.js email API for AI agents

> The trotta-mail npm package gives a TypeScript or Node.js agent its own inbox in one call. Wait for mail, read a screened safe view and reply, fully typed.

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

The trotta-mail npm package gives a TypeScript or Node.js agent its own inbox in one call, with no account and no key to start. Install it, call TrottaMail.signup, then wait for mail, read the screened safe view and reply. It has no dependencies, and every object and error is typed.

Updated November 20, 2026

## Install

The package is `trotta-mail` on npm. It has no dependencies and runs on Node 18 or later, Bun, Deno and Workers.

```bash
npm install trotta-mail
```

A new agent needs no key: `TrottaMail.signup()` creates the inbox and the key in one call. Later, pass the key or set `TROTTA_MAIL_API_KEY` and the client picks it up.

With a key you already have:

```typescript
import { TrottaMail } from "trotta-mail";

const mail = new TrottaMail({ apiKey: process.env.TROTTA_MAIL_API_KEY });
```

## 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 all four are plain method calls, with no model in the loop.

`agent.mjs`:

```typescript
import { TrottaMail } from "trotta-mail";

// 1. Get an inbox. No key needed: this call creates the key and the inbox.
const mail = await TrottaMail.signup({ name: "riley" });
console.log(mail.inbox.address); // riley@trotta.email
console.log(mail.apiKey);        // keep the key, it is shown once
console.log(mail.claimUrl);      // for the human responsible for this agent

// 2. Wait for a message. Resolves as soon as one is delivered, or with null after the timeout.
const msg = await mail.inboxes.wait(mail.inbox.id, { timeout: 120 });
if (!msg) throw new Error("No mail arrived in time.");

// 3. Read it: the verdict, then the safe view.
console.log(msg.verdict.action, msg.verdict.summary);
console.log(msg.text);

// 4. Reply in the thread.
await mail.messages.reply(msg.id, { text: "Thanks, that works." });
```

Run it with `node agent.mjs`, then send a mail to the address it prints. One request can wait 60 seconds at most, so `wait` keeps asking until your `timeout` passes.

Waiting for a sign-up code is the same call with a filter. The code is already parsed.

Wait for a code:

```typescript
const msg = await mail.inboxes.wait(mail.inbox.id, { hasCode: true, timeout: 120 });
console.log(msg?.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. To write to new addresses, a human opens `mail.claimUrl`.

## What your agent reads

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

| On the message | What it holds |
| --- | --- |
| `msg.verdict` | What the guard decided, before the message was readable. `action` is `deliver`, `flag`, `hold` or `reject`. `summary` says why in one sentence. |
| `msg.text` | The safe view: hidden text removed, instructions aimed at a model replaced by a note, risky links defanged. |
| `msg.withheld` | `true` when the guard is holding the message. `text` is `null` and nothing the sender wrote is there. A human releases it. An agent cannot. |

The safe view matters the moment `msg.text` goes into a prompt. A model may follow an instruction it finds in an email, and a sender can hide one in text no human sees. What your model reads from the safe view is 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, and 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:

```typescript
const ctx = await mail.threads.context(msg.thread_id);

// ctx.trust is "safe", "caution" or "danger". ctx.context is ready for a model.
const answer = await yourModel(ctx.context);
await mail.messages.reply(msg.id, { text: answer });
```

No filter catches everything, so treat mail content as data, never as instructions. Outgoing mail is screened too: a refused send throws `UnprocessableEntityError` with the verdict.

## Going further

- [SDKs and CLI](https://trotta.email/docs/sdks): the package at a glance, and the environment variables it reads.
- [Webhooks](https://trotta.email/docs/webhooks): `mail.webhooks.verify(rawBody, headers, secret)` returns the event, or throws when the signature is wrong.
- [Live events](https://trotta.email/docs/events): `mail.events.stream()` yields events as they happen, with no public endpoint.
- [Pods](https://trotta.email/docs/pods): `mail.pods` keeps each of your customers in an isolated workspace.
- [Domains](https://trotta.email/docs/domains): `mail.domains` puts agent inboxes on your own domain, on paid plans.
- [API reference](https://trotta.email/docs/api): every route the client calls.

## Questions

### Does the trotta-mail package need an API key to start?

No. TrottaMail.signup() needs no account and no key. It returns a client that already holds a new inbox and its key, plus a claimUrl for the human responsible for the agent.

### Which runtimes does the TypeScript SDK support?

Node 18 or later, Bun, Deno and Workers. The package has no dependencies and ships its own types.

### How do I wait for a verification email in Node.js?

Call mail.inboxes.wait with hasCode set to true. It resolves as soon as a message with a code is delivered, and the code is at msg.extracted.codes[0].value.

### How are errors reported?

Errors are typed. NotFoundError, PermissionDeniedError, RateLimitError and the rest extend TrottaMailError, and each carries code, fix and requestId. The fix says what to do next.

### Can I use the SDK and the MCP server together?

Yes. Both use the same API key and the same inboxes. Use the SDK for code that runs without a model, and the MCP server when a model should call the tools itself.

## Sources

- trotta-mail on npm
- [Trotta Mail guide for agents (llms.txt)](https://api.trotta.email/llms.txt)

## Related

- [SDKs and CLI](https://trotta.email/docs/sdks) Docs
- [An email REST API for AI agents](https://trotta.email/integrations/rest-api) Integrations
- [Give a Vercel AI SDK agent an email inbox](https://trotta.email/integrations/vercel-ai-sdk) 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 code theft](https://trotta.email/threats/verification-code-theft) Threat library

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)
