How do I send email from Node.js?

Send email from Node.js by installing the agentisend package, constructing a client with a key from POST /api-keys, and calling emails.send. That call is POST /emails; it returns the message id at once, and delivery happens after. The block below is the one in the repository README, and it is executed against the live API on every build, so a sample that stops working fails the build rather than your first send.

import { AgentiSend } from 'agentisend';

const agentisend = new AgentiSend(process.env.AGENTISEND_API_KEY);
const { id } = await agentisend.emails.send({
  from: 'you@yourdomain.com',
  to: 'someone@example.com',
  subject: 'Hello from AgentiSend',
  text: 'Ten minutes, start to sent.',
});
console.log(id);

Install and configure

npm install agentisend

The client reads the key you pass it. Every guide, like the blocks on this page, reads it from the environment on the server and never ships it to the browser. Create the key with POST /api-keys and permission sending_access for a service that only sends. The from address has to be on a domain you have verified with POST /domains; until then, send to an address ending in @simulator.agentisend.com, which costs nothing and reaches nobody, or read How do I test email sending without delivering anything?.

Errors carry the fix

Every refusal throws AgentiSendError, with code, message, fix, docsUrl, status and retryable, and retryAfterSeconds when the API sent a wait.

import { AgentiSend, AgentiSendError } from 'agentisend';

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

try {
  await agentisend.emails.send({ from: 'nope', to: 'someone@example.com', subject: 'x', text: 'y' });
} catch (err) {
  if (err instanceof AgentiSendError) {
    console.error(err.code, err.fix);
    if (!err.retryable) throw err; // waiting cannot help
  }
}

That send fails with invalid_from_address. The catalogue message is "The from field is not a valid address." and the fix is Use a plain address or "Name <addr@domain>" format in POST /emails. retryable is false, so stop. When it is true, retryAfterSeconds says how long to wait.

Send the same request twice

Pass idempotencyKey in the options object, the second argument to emails.send. The same key with the same body replays the first response instead of sending twice, and the header behind it is remembered for 7 days. idempotencyKey('welcome-email', 'user_123'), exported by the package, builds the <what>/<which> shape from the thing being done, never from the time.

import { AgentiSend, idempotencyKey } from 'agentisend';

const agentisend = new AgentiSend(process.env.AGENTISEND_API_KEY);
await agentisend.emails.send(payload, { idempotencyKey: idempotencyKey('welcome-email', 'user_123') });

Frameworks

One runnable file per framework, each executed against a real API on every build: Next.js with a route handler and a Server Action, Express with one POST route, and Hono, whose one file runs on edge runtimes, Deno, Bun and Node. The Quickstart has the same first send in Node, Python and curl, with the domain and key steps before it.

Next

• Quickstart
• Send email from Next.js
• Send email from Express
• Email for AI agents