Brevo Node.js SDK

Website • API Reference • Support

Installation

npm install @getbrevo/brevo

Quick Start

import { BrevoClient } from '@getbrevo/brevo';

const brevo = new BrevoClient({
  apiKey: 'your-api-key',
});

const result = await brevo.transactionalEmails.sendTransacEmail({
  subject: "Hello",
  textContent: "Hello world!",
  sender: { name: "Sender", email: "[email protected]" },
  to: [{ email: "[email protected]" }]
});

console.log('Email sent:', result);

Configuration

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

Constructor options

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | Required (unless auth is provided) | Your Brevo API key | | auth | AuthProvider | null | Custom auth provider (OAuth, dynamic tokens, key rotation). Mutually exclusive with apiKey. | | 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 specific error types based on HTTP status codes.

import { BrevoError, UnauthorizedError, TooManyRequestsError } from '@getbrevo/brevo';

try {
  await brevo.transactionalEmails.sendTransacEmail({...});
} catch (err) {
  if (err instanceof UnauthorizedError) {
    console.error('Invalid API key');
  } else if (err instanceof TooManyRequestsError) {
    const retryAfter = err.rawResponse.headers['retry-after'];
    console.error(`Rate limited. Retry after ${retryAfter} seconds`);
  } else if (err instanceof BrevoError) {
    console.error(`API Error ${err.statusCode}:`, err.message);
  }
}

Error Types:

• 400 - BadRequestError
• 401 - UnauthorizedError
• 403 - ForbiddenError
• 404 - NotFoundError
• 422 - UnprocessableEntityError
• 429 - TooManyRequestsError
• 500+ - InternalServerError

All BrevoError instances provide:

• statusCode: HTTP status code
• message: Error message
• body: Parsed error response body
• rawResponse: Raw response with headers

Retries

Automatic retries with exponential backoff are enabled by default (2 retries).

// Client-level
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  maxRetries: 3
});

// Request-level
await brevo.transactionalEmails.sendTransacEmail({...}, {
  maxRetries: 5
});

Retryable status codes: 408, 429, 500, 502, 503, 504

• Exponential backoff: ~1s, ~2s, ~4s (with jitter)
• Respects Retry-After header for rate limits
• Can be disabled per request with maxRetries: 0

Timeouts

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

// Client-level
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  timeoutInSeconds: 30
});

// Request-level
await brevo.transactionalEmails.sendTransacEmail({...}, {
  timeoutInSeconds: 10
});

Recommended values:

• Standard API calls: 30-60s (default)
• Quick operations: 10-15s
• Bulk operations: 120-300s
• Real-time: 5-10s

Request Options

Additional Headers

await brevo.transactionalEmails.sendTransacEmail({...}, {
  headers: {
    'X-Custom-Header': 'custom-value'
  }
});

Query Parameters

await brevo.transactionalEmails.sendTransacEmail({...}, {
  queryParams: {
    'customParam': 'value'
  }
});

Abort Signal

const controller = new AbortController();
await brevo.transactionalEmails.sendTransacEmail({...}, {
  abortSignal: controller.signal
});
controller.abort();

Raw Response

const { data, rawResponse } = await brevo.transactionalEmails.sendTransacEmail({...})
  .withRawResponse();

console.log(rawResponse.headers['X-My-Header']);

Binary Responses

const response = await brevo.inboundParsing.getInboundEmailAttachment(...);

// Choose one:
const stream = response.stream();
// const arrayBuffer = await response.arrayBuffer();
// const blob = await response.blob();
// const bytes = await response.bytes();

Node.js (ReadableStream):

import { createWriteStream } from 'fs';
import { Readable } from 'stream';
import { pipeline } from 'stream/promises';

const stream = response.stream();
const nodeStream = Readable.fromWeb(stream);
await pipeline(nodeStream, createWriteStream('path/to/file'));

Bun:

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

Browser:

const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);

TypeScript Types

All request and response types are exported.

import { BrevoClient } from '@getbrevo/brevo';

const request: Brevo.SendTransacEmailRequest = {
  subject: "First email",
  textContent: "Hello world!",
  sender: { name: "Bob Wilson", email: "[email protected]" },
  to: [{ email: "[email protected]", name: "Sarah Davis" }]
};

Logging

import { BrevoClient, logging } from '@getbrevo/brevo';

const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  logging: {
    level: logging.LogLevel.Debug,
    logger: new logging.ConsoleLogger(),
    silent: false
  }
});

import winston from 'winston';

const winstonLogger = winston.createLogger({...});

const logger: logging.ILogger = {
  debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
};

Custom Fetch Client

Override the default fetch implementation for advanced use cases.

const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  fetch: async (url, options) => {
    console.log('→', url);
    const response = await fetch(url, options);
    console.log('←', response.status);
    return response;
  },
});

Using node-fetch:

import fetch from 'node-fetch';

const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  fetch: fetch as typeof globalThis.fetch,
});

Using undici:

import { fetch } from 'undici';

const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  fetch: fetch as typeof globalThis.fetch,
});

With a request ID header:

import { randomUUID } from 'crypto';

const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  fetch: async (url, options) => {
    return fetch(url, {
      ...options,
      headers: {
        ...options?.headers,
        'X-Request-ID': randomUUID(),
      },
    });
  },
});

Runtime Compatibility

• Node.js 18+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Upgrading from v5.x

v6 is a major release. Most breaking changes come from an internal effort at Brevo to make endpoints, parameters and models more self-descriptive — so names, shapes and required fields convey intent without needing to cross-reference external docs (both for developers and for AI agents working against the Brevo API).

v5.x remains supported. If you need to hold on v5 temporarily, pin it:

npm install @getbrevo/brevo@^5.0

Breaking changes

Companies — getCompanies filter parameter renamed

// v5
await brevo.companies.getCompanies({ filters: 'foo' });

// v6
await brevo.companies.getCompanies({ 'filters[attributes.name]': 'foo' });

The old filters name still compiles but the filter is silently dropped server-side and you get an unfiltered list. Audit every call site.

Events — createBatchEvents payload shape

// v5
await brevo.event.createBatchEvents([{ /* event */ }]);

// v6
await brevo.event.createBatchEvents({ events: [{ /* event */ }] });

Balance — getActiveBalancesApi response & parameter rename

• Response type replaced: BalanceLimit → GetLoyaltyBalanceProgramsPidActiveBalanceResponse.
• Parameters renamed from snake_case to camelCase: contact_id → contactId, balance_definition_id → balanceDefinitionId, sort_field → sortField.

Balance — getContactBalances requires balanceDefinitionId

CRM — getCrmTasktypes returns an array (GetCrmTasktypesResponseItem[]).

Model fields removed: GetWebhook.channel, GetProcessResponseInfo.export, GetEventsList.events[].source, GetExtendedCampaignOverview.utmIDActive (replaced by utmID: number).

Model fields renamed: ConversationsMessage.File.filename → name, .url → link; SendTransacSms.tag is now string | string[].

Now-required fields: GetContactDetails.whatsappBlacklisted, Note.text, Task.date.

Added

• BrevoClient accepts a new auth option for custom AuthProvider injection (existing apiKey continues to work unchanged).
• New optional fields and filters across contacts.createContact, contacts.updateContact, emailCampaigns.getEmailCampaigns, ecommerce.getProducts, and several other endpoints.

Migration from v3.x

v3.x:

import { TransactionalEmailsApi, SendSmtpEmail } from "@getbrevo/brevo";

let emailAPI = new TransactionalEmailsApi();
(emailAPI as any).authentications.apiKey.apiKey = "xkeysib-xxx";

let message = new SendSmtpEmail();
message.subject = "First email";
message.textContent = "Hello world!";
message.sender = { name: "Bob Wilson", email: "[email protected]" };
message.to = [{ email: "[email protected]", name: "Sarah Davis" }];

emailAPI.sendTransacEmail(message);

v6.x:

import { BrevoClient } from '@getbrevo/brevo';

const brevo = new BrevoClient({
  apiKey: 'xkeysib-xxx',
});

await brevo.transactionalEmails.sendTransacEmail({
  subject: "First email",
  textContent: "Hello world!",
  sender: { name: "Bob Wilson", email: "[email protected]" },
  to: [{ email: "[email protected]", name: "Sarah Davis" }],
});

[!WARNING] 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 v6.x.

Contributing

This library is generated programmatically. Changes made directly to the library would be overwritten. Please open an issue first to discuss changes.

Contributions to this README are always welcome!

Support

• API Reference
• GitHub Issues
• Email Support