DEV Community: Omni Genz

Send transactional email with the Brevo API and plain Node.js fetch (no SDK)

Omni Genz — Fri, 30 Oct 2026 09:24:54 +0000

A shorter, code-first version of a guide first published on Omni Genz.

SDKs are handy, but for one or two endpoints they're often more than you need. Brevo's (formerly Sendinblue) REST API is plain JSON over HTTPS, so Node 18+ can talk to it with the built-in fetch. No extra packages.

This post walks through four things: checking your key, sending a simple email, sending with a saved template, and handling errors and rate limits properly.

1. Get a key and keep it out of your code

In Brevo, go to Settings > SMTP & API and create an API key (it starts with xkeysib-). Put it in an environment variable, never in the repo:

export BREVO_API_KEY="xkeysib-..."

Every request sends the key in an api-key header. The base URL is https://api.brevo.com/v3.

Quick sanity check from the terminal before writing any code:

curl -s https://api.brevo.com/v3/account \
  -H "api-key: $BREVO_API_KEY" \
  -H "accept: application/json"

If you get your account details back, the key works. A 401 means the key is wrong, revoked or copied with a stray space.

2. A tiny client

Create brevo.mjs:

// brevo.mjs (Node 18+, no dependencies)
const BASE = "https://api.brevo.com/v3";
const KEY = process.env.BREVO_API_KEY;
if (!KEY) throw new Error("Set BREVO_API_KEY first");

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function brevo(path, { method = "GET", body, retries = 3 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(BASE + path, {
      method,
      headers: {
        "api-key": KEY,
        "accept": "application/json",
        "content-type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    // Rate limited: wait for the window to reset, then try again
    if (res.status === 429 && attempt < retries) {
      const reset = parseInt(res.headers.get("x-sib-ratelimit-reset") || "60", 10);
      await sleep((reset + 2 ** attempt + Math.random()) * 1000);
      continue;
    }

    const text = await res.text();
    const data = text ? JSON.parse(text) : null;

    if (!res.ok) {
      // Brevo errors come back as { code, message }
      const err = new Error(`Brevo ${res.status}: ${data?.message || text}`);
      err.status = res.status;
      err.code = data?.code;
      throw err;
    }
    return data;
  }
}

Two details worth calling out:

Rate limits. When you hit a limit, Brevo returns 429 with an x-sib-ratelimit-reset header (time until the window resets, usually in seconds). The loop waits that long plus a little exponential backoff. Brevo also sends x-sib-ratelimit-limit and x-sib-ratelimit-remaining, which you can log if you send in bulk.
Errors. A 400 body contains a code and a human-readable message, which tells you exactly which field is wrong. Surface it instead of swallowing it.

3. Send a plain transactional email

The endpoint is POST /v3/smtp/email. Without a template, sender, to, subject and some content are needed:

// send.mjs
import { brevo } from "./brevo.mjs";

const result = await brevo("/smtp/email", {
  method: "POST",
  body: {
    sender: { name: "Acme App", email: "no-reply@yourdomain.com" },
    to: [{ email: "jane@example.com", name: "Jane" }],
    subject: "Your login link",
    htmlContent: "<p>Hi Jane, <a href='https://example.com/login'>click here to sign in</a>.</p>",
    textContent: "Hi Jane, sign in here: https://example.com/login",
    tags: ["login-link"],
  },
});

console.log(result); // { messageId: "<...>" }

Run it:

node send.mjs

A 201 response with a messageId means Brevo accepted the message. Keep that ID: it's how you match the email to delivery events later.

Use a sender address on a domain you've added and authenticated in Brevo. Sending "from" an unverified address is the most common reason a first test fails or lands in spam. Always include textContent too, as some clients and spam filters like a plain-text part.

4. Send with a saved template

Hard-coding HTML gets old fast. Build the email in Brevo's template editor, use placeholders like {{ params.firstName }}, and pass values per send:

await brevo("/smtp/email", {
  method: "POST",
  body: {
    templateId: 12, // the ID shown in Brevo's template list
    to: [{ email: "jane@example.com", name: "Jane" }],
    params: { firstName: "Jane", orderId: "A-1042", total: "$48.00" },
    tags: ["order-receipt"],
  },
});

With templateId set, the template's own sender and subject are used, so you can leave those out. params fills in the placeholders.

5. Useful extras on the same endpoint

All of these go in the same JSON body:

replyTo, cc, bcc for routing replies and copies.
attachment: an array of { url } or { content, name } where content is base64.
scheduledAt: an ISO date-time to send later. Brevo answers 202 instead of 201 for scheduled sends, and notes the actual send can lag the requested time by a few minutes.
headers: custom headers. A value in X-Mailin-custom comes back in webhook events, which is handy for passing your own order or user ID through.
messageVersions: send variations of one template (different to and params) in a single call instead of looping.

Here's a small helper for the attachment case:

import { readFile } from "node:fs/promises";

const pdf = await readFile("./invoice-1042.pdf");
await brevo("/smtp/email", {
  method: "POST",
  body: {
    templateId: 12,
    to: [{ email: "jane@example.com" }],
    params: { orderId: "A-1042" },
    attachment: [{ name: "invoice-1042.pdf", content: pdf.toString("base64") }],
    headers: { "X-Mailin-custom": "order:A-1042" },
  },
});

6. Before you ship

Keep the key server-side only. Never call this API from the browser, as anyone could read the key.
Log the messageId with your own record (user, order) so support can trace a missing email.
Check Transactional > Logs in Brevo when a test doesn't arrive. It shows whether the message was delivered, deferred or bounced.
Brevo can disable a key that goes unused for a long time, so if an old integration suddenly returns 401, check the key status first.

Prices, plan limits and the dashboard menus change, so check Brevo's own pages for the current numbers rather than trusting any blog post (including this one).

The full beginner's guide, with key setup screenshots, common errors and limits, is here: Brevo API Explained: A Simple Beginner's Guide.

Send app emails through the Brevo SMTP relay with Node.js (Nodemailer)

Omni Genz — Thu, 29 Oct 2026 09:23:44 +0000

A shorter, code-first version of a guide first published on Omni Genz.

If your app's password resets and order receipts keep vanishing, sending straight from your web server is often the problem. Big inboxes don't trust mail from a random host. An SMTP relay fixes that: your app hands the email to a server built for sending, and the relay delivers it.

Brevo (formerly Sendinblue) includes its SMTP relay on every plan, including the free one (300 emails a day, according to Brevo's pricing page). Here's how to wire it into a Node.js app.

1. Get your SMTP details

In Brevo, go to Settings > SMTP & API > SMTP. You need:

Setting	Value
Host	`smtp-relay.brevo.com`
Port	`587` (try `2525` if your host blocks 587, or `465` for SSL)
Username	The SMTP login shown on that page
Password	An SMTP key, not your Brevo password and not an API key

Generate the SMTP key on the same tab. You only see it once, so put it straight into your secrets manager or .env file.

2. Install Nodemailer

npm install nodemailer dotenv

# .env
BREVO_SMTP_LOGIN=your-login-from-the-smtp-page
BREVO_SMTP_KEY=your-smtp-key
MAIL_FROM="Your App <hello@yourdomain.com>"

3. Create the transport and send

require('dotenv').config();
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp-relay.brevo.com',
  port: 587,
  secure: false, // STARTTLS on 587; set true only for port 465
  auth: {
    user: process.env.BREVO_SMTP_LOGIN,
    pass: process.env.BREVO_SMTP_KEY,
  },
});

async function sendReset(to, link) {
  const info = await transporter.sendMail({
    from: process.env.MAIL_FROM,
    to,
    subject: 'Reset your password',
    text: `Use this link to reset your password: ${link}`,
    html: `<p>Use this link to reset your password:</p><p><a href="${link}">${link}</a></p>`,
  });
  console.log('Queued:', info.messageId);
}

transporter.verify()
  .then(() => sendReset('you@example.com', 'https://example.com/reset/123'))
  .catch(console.error);

transporter.verify() checks the login before you send anything, which saves a lot of guessing.

4. Fix "535 Authentication failed"

This is the error almost everyone hits once. Common causes:

You used smtp-relay.brevo.com as the username. Use the login from the SMTP page.
You used your account password or an API key. Use an SMTP key.
Extra spaces or a line break came along when you pasted the key.
secure: true on port 587, or secure: false on 465. Match them.
The key was switched off. Brevo disables keys that haven't sent a good email in 90 days, so generate a new one.

5. Before you go live

Add and authenticate your sending domain in Brevo (SPF, DKIM and DMARC) and use a from address on that domain. Then send a test to yourself, check inbox and spam, and look under Transactional > Logs in Brevo to see what happened to it.

The full guide, with the step-by-step key setup and the port table, is here: What is an SMTP relay? Brevo SMTP relay setup guide.