Send email from Node.js with an email API

To send email from Node.js you have to hand the message to something that will deliver it. Node has no mail transport of its own — there is no fs.writeMail — so every answer is a choice about what sits between your process and the recipient’s mailbox provider.

There are three, and they are easy to confuse because two of them are the same thing wearing different clothes. A Node.js email API is an HTTPS endpoint: you POST a JSON message and get back an id. SMTP is the protocol mail servers have spoken since RFC 5321, and you can open a socket and speak it yourself. Nodemailer is the package almost everyone reaches for when they mean the second one: it is an SMTP client with a friendly message builder on top.

The important distinction is not the protocol. It is what the thing on the other end does for you. A relay takes bytes and forwards them. A sending platform verifies your domain, signs the message, keeps a suppression list so you do not mail an address that already bounced, records what happened, and tells you about it.

The three approaches differ in how much of the work is yours. This is the shape of the trade, with the last row the one most people actually decide on.

None of this makes Nodemailer a bad package. It is a very good SMTP client. It is simply not a sending platform, and a great many outages have started with a team assuming it was one.

The shortest path today is the fetch built into Node. The API is ordinary HTTP: a bearer token, a JSON body, and an idempotency header, with nothing to install.

const response = await fetch("https://api.rasket.com/emails", {  method: "POST",  headers: {    authorization: `Bearer ${process.env.RASKET_API_KEY}`,    "content-type": "application/json",    "user-agent": "acme-billing/1.0",    "idempotency-key": "receipt-1042",  },  body: JSON.stringify({    from: "Acme <billing@acme.example>",    to: ["ronald.williams@example.com"],    subject: "Your receipt",    html: "<p>Thanks for your order.</p>",  }),});
if (!response.ok) {  throw new Error(`send failed: ${String(response.status)}`);}
const email = await response.json();console.log(email.id);

Four headers carry the whole contract. Authorization is Bearer and your API key, read from the environment and never written into the file — a key in a repository is a key you will rotate on somebody else’s schedule. Content-Type is application/json. User-Agent is required: a request with no User-Agent is refused, and naming your application is what lets support tell your billing worker from your web process. And Idempotency-Key is derived from the thing that caused the send — the order — rather than generated fresh, which is the difference between a retry that is safe and a retry that sends a second receipt.

Coming soon: the rasket package is not published yet. When it is, it will wrap this same request with typed bodies generated from the API’s OpenAPI document, a retry policy and the webhook verifier. Until then, the fetch above is the whole of a send, and a curl of the same request is the quickest first experiment.

SMTP is not obsolete, and saying so would be a sales pitch rather than an engineering claim. It is the protocol every message eventually travels over, and there are three situations where speaking it directly from Node is the right answer.

• You already run a mail server. If there is a relay inside your network that handles authentication, queueing and retries, pointing Nodemailer at it is less work than adding an external dependency.
• The mail never leaves the building. Internal notifications to an internal relay have no deliverability problem to solve, because there is no external reputation involved.
• You are porting something that already works. A working SMTP integration you are not being asked to improve is not a bug.

For reference, this is what the Nodemailer version of the same send looks like.

import nodemailer from "nodemailer";
const transport = nodemailer.createTransport({  host: "smtp.example.com",  port: 587,  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },});
await transport.sendMail({  from: "Acme <billing@acme.example>",  to: "ronald.williams@example.com",  subject: "Your receipt",  html: "<p>Thanks for your order.</p>",});

Compare it with the API sample above and notice what is missing rather than what is different. There is no id to store. There is nothing that will tell you, four hours later, that the message bounced. If the address was already known to be dead, the message goes out anyway. Those gaps are not Nodemailer’s fault — they are on the other side of the socket — but they are yours to fill.

A network call that times out has not necessarily failed. The request may have arrived, the message may have been accepted, and only the response may have been lost. Retrying blindly is how one order becomes three receipts.

An Idempotency-Key is what makes the retry safe. Send the same key with the retry and a repeat is recognised as a repeat: the original response comes back, marked as a replay, and no second message is sent. The window is 24 hours. Derive the key from the event that caused the send — an order id, an invoice number, a password-reset request id — so that two attempts to send the same thing produce the same key, and two different things never do. Read the idempotency guide for the exact semantics.

The rate limit is ten requests a second per team, across every endpoint. You do not have to guess where you are in the window, because every response says:

ratelimit-limit: 10ratelimit-remaining: 7ratelimit-reset: 1

Pace a bulk job off ratelimit-remaining rather than off a sleep you tuned once on a quiet afternoon. If you do go over, the answer is a 429 carrying how long to wait in retry-after: wait that long, then send the same request with the same Idempotency-Key. Never retry a write that carries no key, which is the correct default: at-most-once matters more than a saved round trip.

A 200 from the send endpoint means the message was accepted, not that it arrived. What happened next — delivered, delayed, bounced, complained, opened, clicked — reaches you as a signed webhook. This is the part that has no equivalent in the Nodemailer path, and it is usually the reason a team moves.

Three headers travel with every delivery:

• svix-id — the event’s own id, stable across replays. Deduplicate on it.
• svix-timestamp — Unix seconds. Anything more than five minutes out is refused.
• svix-signature — one or more signatures; any one matching is enough, which is what makes a secret rotation survivable.

Verify before you trust, and verify against the bytes that arrived rather than a body your framework has already parsed and re-serialised — a re-serialised body is a different string, and a different string has a different signature.

// npm install svix — the scheme is Svix-compatible, so the official package verifies it.import { Webhook } from "svix";
const wh = new Webhook(process.env.RASKET_WEBHOOK_SECRET);
export async function POST(request: Request): Promise<Response> {  const rawBody = await request.text(); // text(), never json()
  try {    const event = wh.verify(rawBody, Object.fromEntries(request.headers));    await record(event);    return new Response(null, { status: 200 });  } catch {    return new Response("invalid signature", { status: 400 });  }}

The scheme is Svix-compatible, so the official svix package verifies our deliveries as they are; @rasket/webhook-verify, our own zero-dependency verifier, follows when it is published. Events can arrive more than once and can arrive out of order, so treat your handler as a fold over a stream rather than a state machine with an expected sequence. The events guide lists every event and its payload.