agentisend

agentisend

AgentiSend is a transactional email API for AI agents and the products they run inside. Every API key carries a send budget, a preflight call runs every gate without sending, a refusal names the call that repairs it, and one request pauses every sender. Node 20 or newer, ESM, no runtime dependencies.

npm install agentisend

An agent that sends, and can be stopped

import { AgentiSend } from 'agentisend';

const mail = new AgentiSend(process.env.AGENTISEND_API_KEY);

const message = {
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Your receipt',
  text: 'Thanks. The details are attached to your account.',
};

// Runs every gate (domain, budget, loop guard, suppression, content) and sends nothing.
const check = await mail.emails.preflight(message);
if (!check.ok) throw new Error(`${check.error?.code}: ${check.error?.fix}`);

// The key this agent holds was created with a budget. Past it, the send is refused
// with `agent_budget_exceeded` and a `fix` that says to wait for the reset: raising a
// budget is a person's decision, made in the console, and the key cannot make it.
const { id } = await mail.emails.send(message, { idempotencyKey: `receipt/${message.to}` });
console.log(id);

The idempotency key is derived from the thing being done, never from the moment: a retry after a timeout replays the first send instead of mailing someone twice.

Give the agent its own key, with a ceiling

const owner = new AgentiSend(process.env.AGENTISEND_API_KEY); // your key, never the agent's

const key = await owner.apiKeys.create({ name: 'support-agent', permission: 'sending_access' });
// Lower the number and keep the key's window: a key may only tighten a limit, and
// 50 a day would be more than a new Free key's 1,000 a month.
await owner.limits.update(key.id, { budget_per_period: 50, rate_ceiling_per_minute: 10 });

const agent = new AgentiSend(key.token); // holds only its own key

POST /limits/keys/{id}/kill stops that key immediately; POST /limits/kill-all stops every key on the account. Both are one request from anywhere, and both write an audit row.

What a refusal looks like

Errors throw AgentiSendError, which carries code, message, fix and docsUrl; on a 429 it also carries retryAfterSeconds. A looping agent that sends the same message to the same person a fourth time inside the window reads approval_required: nothing was delivered, the send waits in an approval queue for a person, and fix says so.

try {
  await agent.emails.send(message);
} catch (err) {
  if (err instanceof AgentiSendError) console.error(err.code, err.fix);
}

Coming from Resend

agentisend/compat-resend exports a Resend class covering the email, domain, key, contact, segment, topic, broadcast, template, suppression, automation and webhook methods, with the same { data, error } return shape, so most of a migration is the import line. Where AgentiSend is stricter, the shim warns on stderr instead of changing what it does. A member with no AgentiSend counterpart answers not_supported rather than being undefined. See Migrating from Resend for what differs.

Everything else

The full client (emails, domains, webhooks, apiKeys, limits, templates, contacts, broadcasts, trust), the CLI and the MCP server are documented at agentisend.com/docs. The MCP server is https://api.agentisend.com/mcp; the API contract is agentisend.com/openapi.json. This package re-exports @agentisend/sdk-node.

The command line

This package installs the agentisend command. npx agentisend doctor runs it once without installing anything; npm i -g agentisend keeps it on your path. It reads the key from AGENTISEND_API_KEY, and agentisend --help lists every command.