Node.js SDK | Brevo API Documentation

Overview

The Brevo Node.js SDK (@getbrevo/brevo) is a TypeScript-first client library for the Brevo API. It provides:

A unified BrevoClient with namespaced service clients
Full TypeScript types with IDE autocomplete
Promise-based async/await API
Automatic retries with exponential backoff
Custom fetch support for any runtime
Structured error handling with typed error classes

Version 4.0 is a full rewrite and is not backwards compatible with the v3.x SDK. The legacy v3.x SDK (@getbrevo/brevo@^3.0.1) will continue to receive critical security updates but no new features. We recommend migrating to v4.x for new and existing projects.

Requirements

Node.js 18+
Also compatible with: Vercel, Cloudflare Workers, Deno v1.25+, Bun 1.0+, React Native

Installation

$ npm install @getbrevo/brevo

Quick start

Initialize the client and send your first email:

quick-start.ts

1 import { BrevoClient } from '@getbrevo/brevo';
2 
3 const brevo = new BrevoClient({ apiKey: 'your-api-key' });
4 
5 const result = await brevo.transactionalEmails.sendTransacEmail({
6   subject: 'Hello from Brevo!',
7   htmlContent: '<html><body><p>Hello,</p><p>This is my first transactional email.</p></body></html>',
8   sender: { name: 'Alex from Brevo', email: 'hello@brevo.com' },
9   to: [{ email: 'johndoe@example.com', name: 'John Doe' }],
10 });
11 
12 console.log('Email sent. Message ID:', result.messageId);

Configuration

Pass options to the constructor to configure timeout, retries, and other settings:

configuration.ts

1 const brevo = new BrevoClient({
2   apiKey: 'your-api-key',
3   timeoutInSeconds: 30,
4   maxRetries: 3,
5 });

Constructor options

Option	Type	Default	Description
`apiKey`	`string`	Required	Your Brevo API key
`timeoutInSeconds`	`number`	`60`	Default request timeout in seconds
`maxRetries`	`number`	`2`	Maximum retry attempts on retryable errors
`baseUrl`	`string`	`null`	Override the default API base URL
`fetch`	`typeof fetch`	`null`	Custom fetch implementation
`headers`	`Record<string, string>`	`null`	Additional default headers sent with every request
`logging`	`LogConfig \| Logger`	`null`	Logging configuration

Error handling

The SDK throws typed error classes based on HTTP status codes:

error-handling.ts

1 import {
2   BrevoError,
3   UnauthorizedError,
4   TooManyRequestsError,
5 } from '@getbrevo/brevo';
6 
7 try {
8   await brevo.transactionalEmails.sendTransacEmail({ ... });
9 } catch (err) {
10   if (err instanceof UnauthorizedError) {
11     console.error('Invalid API key');
12   } else if (err instanceof TooManyRequestsError) {
13     const retryAfter = err.rawResponse.headers['retry-after'];
14     console.error(`Rate limited. Retry after ${retryAfter}s`);
15   } else if (err instanceof BrevoError) {
16     console.error(`API error ${err.statusCode}:`, err.message);
17   }
18 }

Error classes

Status code	Class
`400`	`BadRequestError`
`401`	`UnauthorizedError`
`403`	`ForbiddenError`
`404`	`NotFoundError`
`422`	`UnprocessableEntityError`
`429`	`TooManyRequestsError`
`500+`	`InternalServerError`

All BrevoError instances expose:

statusCode — HTTP status code
message — Error message
body — Parsed response body
rawResponse — Raw response with headers

Retries

Automatic retries with exponential backoff are enabled by default (2 retries). Configure at the client or request level:

retries.ts

1 // Client-level
2 const brevo = new BrevoClient({
3   apiKey: 'your-api-key',
4   maxRetries: 3,
5 });
6 
7 // Request-level (overrides client setting)
8 await brevo.transactionalEmails.sendTransacEmail({ ... }, {
9   maxRetries: 0, // Disable retries for this request
10 });

Retry behavior

Retryable status codes: 408, 429, 500, 502, 503, 504
Backoff schedule: ~1s, ~2s, ~4s (exponential with jitter)
Rate limit headers: Respects Retry-After response header

Timeouts

Default timeout is 60 seconds. Configure at the client or request level:

timeouts.ts

1 // Client-level
2 const brevo = new BrevoClient({
3   apiKey: 'your-api-key',
4   timeoutInSeconds: 30,
5 });
6 
7 // Request-level (overrides client setting)
8 await brevo.transactionalEmails.sendTransacEmail({ ... }, {
9   timeoutInSeconds: 10,
10 });

Recommended timeout values

Use case	Timeout
Standard API calls	`30–60s` (default)
Quick operations	`10–15s`
Bulk operations	`120–300s`
Real-time / low-latency	`5–10s`

Request options

All service methods accept a request options object as the final argument:

request-options.ts

1 await brevo.transactionalEmails.sendTransacEmail({ ... }, {
2   timeoutInSeconds: 10,
3   maxRetries: 1,
4   headers: { 'X-Custom-Header': 'custom-value' },
5   queryParams: { customParam: 'value' },
6 });

Abort signal

Cancel in-flight requests using the Web AbortController API:

abort-signal.ts

1 const controller = new AbortController();
2 
3 await brevo.transactionalEmails.sendTransacEmail({ ... }, {
4   abortSignal: controller.signal,
5 });
6 
7 controller.abort(); // Cancel the request

Raw response

Access response headers and metadata via .withRawResponse():

raw-response.ts

1 const { data, rawResponse } = await brevo.transactionalEmails
2   .sendTransacEmail({ ... })
3   .withRawResponse();
4 
5 console.log(rawResponse.headers['x-request-id']);
6 console.log(data.messageId);

Binary responses

Endpoints that return binary content (e.g., attachment downloads) expose multiple consumption methods:

binary-responses.ts

1 const response = await brevo.inboundParsing.getInboundEmailAttachment(downloadToken);
2 
3 const stream      = response.stream();
4 const arrayBuffer = await response.arrayBuffer();
5 const blob        = await response.blob();
6 const bytes       = await response.bytes();

Saving binary content

Node.js (ReadableStream)

1 import { createWriteStream } from 'fs';
2 import { Readable } from 'stream';
3 import { pipeline } from 'stream/promises';
4 
5 const stream = response.stream();
6 await pipeline(Readable.fromWeb(stream), createWriteStream('path/to/file'));

Bun

1 await Bun.write('path/to/file', response.stream());

Browser

1 const blob = await response.blob();
2 const url = URL.createObjectURL(blob);
3 const a = document.createElement('a');
4 a.href = url;
5 a.download = 'filename';
6 a.click();
7 URL.revokeObjectURL(url);

TypeScript types

All request and response types are exported from the package:

typescript-types.ts

1 import type { Brevo } from '@getbrevo/brevo';
2 
3 const request: Brevo.SendTransacEmailRequest = {
4   subject: 'First email',
5   textContent: 'Hello world!',
6   sender: { name: 'Bob Wilson', email: 'bob.wilson@brevo.com' },
7   to: [{ email: 'sarah.davis@example.com', name: 'Sarah Davis' }],
8 };

Logging

Configure logging to inspect outgoing requests and responses:

logging.ts

1 import { BrevoClient, logging } from '@getbrevo/brevo';
2 
3 const brevo = new BrevoClient({
4   apiKey: 'your-api-key',
5   logging: {
6     level: logging.LogLevel.Debug,
7     logger: new logging.ConsoleLogger(),
8   },
9 });

Custom logger

Integrate with any logging library by implementing the ILogger interface:

custom-logger.ts

1 import winston from 'winston';
2 import { logging } from '@getbrevo/brevo';
3 
4 const winstonLogger = winston.createLogger({
5   level: 'info',
6   format: winston.format.json(),
7   transports: [new winston.transports.Console()],
8 });
9 
10 const logger: logging.ILogger = {
11   debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
12   info:  (msg, ...args) => winstonLogger.info(msg, ...args),
13   warn:  (msg, ...args) => winstonLogger.warn(msg, ...args),
14   error: (msg, ...args) => winstonLogger.error(msg, ...args),
15 };
16 
17 const brevo = new BrevoClient({
18   apiKey: 'your-api-key',
19   logging: { level: logging.LogLevel.Debug, logger },
20 });

Custom fetch

Override the default fetch implementation for any runtime or to add request interceptors:

custom-fetch.ts

1 const brevo = new BrevoClient({
2   apiKey: 'your-api-key',
3   fetch: async (url, options) => {
4     console.log('→', url);
5     const response = await fetch(url, options);
6     console.log('←', response.status);
7     return response;
8   },
9 });

Common integrations

node-fetch

1 import fetch from 'node-fetch';
2 
3 const brevo = new BrevoClient({
4   apiKey: 'your-api-key',
5   fetch: fetch as typeof globalThis.fetch,
6 });

undici

1 import { fetch } from 'undici';
2 
3 const brevo = new BrevoClient({
4   apiKey: 'your-api-key',
5   fetch: fetch as typeof globalThis.fetch,
6 });

With request ID header

1 import { randomUUID } from 'crypto';
2 
3 const brevo = new BrevoClient({
4   apiKey: 'your-api-key',
5   fetch: async (url, options) => {
6     return fetch(url, {
7       ...options,
8       headers: {
9         ...options?.headers,
10         'X-Request-ID': randomUUID(),
11       },
12     });
13   },
14 });

Available services

The BrevoClient exposes the following service namespaces:

Property	Description
`transactionalEmails`	Send emails, manage templates, blocked contacts and domains
`transactionalSms`	Send SMS messages and view delivery statistics
`transactionalWhatsApp`	Send WhatsApp messages and view event reports
`smsTemplates`	Manage SMS templates
`contacts`	Manage contacts, lists, folders, attributes and segments
`emailCampaigns`	Create and manage email marketing campaigns
`smsCampaigns`	Create and manage SMS marketing campaigns
`whatsAppCampaigns`	Create and manage WhatsApp campaigns and templates
`companies`	Manage CRM companies
`deals`	Manage CRM deals and pipelines
`tasks`	Manage CRM tasks
`notes`	Manage CRM notes
`files`	Upload and manage CRM files
`conversations`	Manage conversation messages and automated messages
`ecommerce`	Manage products, categories, orders and attribution
`coupons`	Manage coupon collections and coupons
`payments`	Create and manage payment requests
`event`	Track custom events
`webhooks`	Manage webhooks
`senders`	Manage senders and IPs
`domains`	Manage and authenticate domains
`account`	Retrieve account information and activity logs
`inboundParsing`	Retrieve inbound email events and attachments
`customObjects`	Manage custom object records
`externalFeeds`	Manage external RSS feeds
`masterAccount`	Manage sub-accounts and groups (enterprise)
`user`	Manage users and permissions
`process`	Retrieve background process status
`program`	Manage loyalty programs
`balance`	Manage loyalty balances and transactions
`reward`	Manage loyalty rewards and vouchers
`tier`	Manage loyalty tiers and tier groups

Migration from v3.x

Key changes

Area	v3.x	v4.x
Client	`new TransactionalEmailsApi()` per resource	`new BrevoClient({ apiKey })` unified
Auth	`(api as any).authentications.apiKey.apiKey = "..."`	Constructor option
API style	Class-based with setters	Promise-based with inline objects
TypeScript	Partial	Full, exported types
Retries	Not built-in	Automatic with exponential backoff

Migration example

1 // v3.x
2 import { TransactionalEmailsApi, SendSmtpEmail } from '@getbrevo/brevo';
3 
4 let emailAPI = new TransactionalEmailsApi();
5 (emailAPI as any).authentications.apiKey.apiKey = 'xkeysib-xxx';
6 
7 let message = new SendSmtpEmail();
8 message.subject = 'First email';
9 message.textContent = 'Hello world!';
10 message.sender = { name: 'Bob Wilson', email: 'bob.wilson@brevo.com' };
11 message.to = [{ email: 'sarah.davis@example.com', name: 'Sarah Davis' }];
12 
13 emailAPI.sendTransacEmail(message);