An email inbox for TypeScript and Node.js agents

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

Install

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

shell
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
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
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
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 messageWhat it holds
msg.verdictWhat the guard decided, before the message was readable. action is deliver, flag, hold or reject. summary says why in one sentence.
msg.textThe safe view: hidden text removed, instructions aimed at a model replaced by a note, risky links defanged.
msg.withheldtrue 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
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: the package at a glance, and the environment variables it reads.
  • Webhooks: mail.webhooks.verify(rawBody, headers, secret) returns the event, or throws when the signature is wrong.
  • Live events: mail.events.stream() yields events as they happen, with no public endpoint.
  • Pods: mail.pods keeps each of your customers in an isolated workspace.
  • Domains: mail.domains puts agent inboxes on your own domain, on paid plans.
  • API reference: 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

Give your agent an inbox of its own. One call, or one minute in the console.