How to send email from Node.js: API vs SMTP vs Nodemailer

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 is the client library. It is one package with no dependencies of its own, it is generated from the same OpenAPI document the API is served from, and it returns typed bodies rather than unknown.

1. Install the client — Run npm install rasket in the project that will send the mail. The package has no dependencies of its own.
2. Export the key — Create an API key in the dashboard and put it in the environment as RASKET_API_KEY. Never write the key into a source file.
3. Verify a domain — Add the domain you want to send from, publish the DKIM, SPF and DMARC records it generates, and wait for verification to pass. Mail from an unverified domain is refused.
4. Send with an idempotency key — Call emails.send with from, to, subject and html, and pass an idempotencyKey derived from the thing that caused the send — an order id, not a random string.
5. Handle the response — Store the returned email id against your own record. It is the id every later event and every support question is about.
6. Subscribe a webhook — Point an endpoint at the delivery events you care about and verify the signature on every request before you trust the body.

import { Rasket } from "rasket";
const rasket = new Rasket({  apiKey: process.env.RASKET_API_KEY,  userAgent: "acme-billing/1.0",});
const { body: email } = await rasket.emails.send(  {    from: "Acme <billing@acme.example>",    to: ["ronald.williams@example.com"],    subject: "Your receipt",    html: "<p>Thanks for your order.</p>",  },  { idempotencyKey: "receipt-1042" },);
console.log(email.id);

Three details in that sample are worth more than the rest. The key is read from the environment, never written into the file — a key in a repository is a key you will rotate on somebody else’s schedule. userAgent is required: a request with no User-Agent is refused, and what you pass is appended to the SDK’s own, which is what lets support tell your billing worker from your web process. And idempotencyKey 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.

There is nothing in the SDK you cannot do with the fetch built into Node. The API is ordinary HTTP: a bearer token, a JSON body, and an idempotency header when you want one.

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();

Four headers carry the whole contract. Authorization is Bearer and your API key. Content-Type is application/json. User-Agent names your application. Idempotency-Key is optional, and it is the only one of the four that changes what happens when you send the same request twice.

Writing it by hand costs you the typed bodies, the retry policy and the webhook verifier the package bundles. It is the right choice in a runtime where you would rather not add a dependency at all, and it is the right choice for a first experiment, because a curl and this snippet are the same request.

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, and the SDK’s built-in retry policy already backs off on it. A write without an idempotency key is never retried automatically, 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.

import { verify } from "@rasket/webhook-verify";
export async function POST(request: Request): Promise<Response> {  const rawBody = await request.text(); // text(), never json()
  try {    const event = verify(rawBody, request.headers, process.env.RASKET_WEBHOOK_SECRET);    await record(event);    return new Response(null, { status: 200 });  } catch {    return new Response("invalid signature", { status: 400 });  }}

The verifier is a separate package on purpose: it imports node:crypto and nothing else, so an endpoint that only needs to check a signature does not have to install a client. 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.