> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/guides/node-js/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

# Node.js SDK

## 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

[![npm](https://img.shields.io/npm/dm/@getbrevo/brevo)](https://www.npmjs.com/package/@getbrevo/brevo)

> **Warning**
>
> Version 6.0 introduces breaking changes versus v5.x. v5.x remains supported and continues to receive wire-compatibility fixes — see the [changelog](/docs/sdks-libraries/node-changelog) for the list of changes and the README for migration steps.

## Requirements

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

## Installation

```bash
npm install @getbrevo/brevo
```

## Quick start

Initialize the client and send your first email:

**`quick-start.ts`**

```typescript title="quick-start.ts"
import { BrevoClient } from '@getbrevo/brevo';

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

const result = await brevo.transactionalEmails.sendTransacEmail({
  subject: 'Hello from Brevo!',
  htmlContent: '<html><body><p>Hello,</p><p>This is my first transactional email.</p></body></html>',
  sender: { name: 'Alex from Brevo', email: 'hello@brevo.com' },
  to: [{ email: 'johndoe@example.com', name: 'John Doe' }],
});

console.log('Email sent. Message ID:', result.messageId);
```

## Configuration

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

**`configuration.ts`**

```typescript title="configuration.ts"
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  timeoutInSeconds: 30,
  maxRetries: 3,
});
```

### 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`**

```typescript title="error-handling.ts"
import { Brevo, BrevoError } from '@getbrevo/brevo';

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

### Error classes

Typed subclasses are namespaced under `Brevo` (e.g. `Brevo.UnauthorizedError`) — only `BrevoError` and `BrevoTimeoutError` are top-level exports.

| Status code | Class                            |
| ----------- | -------------------------------- |
| `400`       | `Brevo.BadRequestError`          |
| `401`       | `Brevo.UnauthorizedError`        |
| `403`       | `Brevo.ForbiddenError`           |
| `404`       | `Brevo.NotFoundError`            |
| `422`       | `Brevo.UnprocessableEntityError` |
| `429`       | `Brevo.TooManyRequestsError`     |
| `500+`      | `Brevo.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`**

```typescript title="retries.ts"
// Client-level
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  maxRetries: 3,
});

// Request-level (overrides client setting)
await brevo.transactionalEmails.sendTransacEmail({ ... }, {
  maxRetries: 0, // Disable retries for this request
});
```

### 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`**

```typescript title="timeouts.ts"
// Client-level
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  timeoutInSeconds: 30,
});

// Request-level (overrides client setting)
await brevo.transactionalEmails.sendTransacEmail({ ... }, {
  timeoutInSeconds: 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`**

```typescript title="request-options.ts"
await brevo.transactionalEmails.sendTransacEmail({ ... }, {
  timeoutInSeconds: 10,
  maxRetries: 1,
  headers: { 'X-Custom-Header': 'custom-value' },
  queryParams: { customParam: 'value' },
});
```

### Abort signal

Cancel in-flight requests using the Web `AbortController` API:

**`abort-signal.ts`**

```typescript title="abort-signal.ts"
const controller = new AbortController();

await brevo.transactionalEmails.sendTransacEmail({ ... }, {
  abortSignal: controller.signal,
});

controller.abort(); // Cancel the request
```

### Raw response

Access response headers and metadata via `.withRawResponse()`:

**`raw-response.ts`**

```typescript title="raw-response.ts"
const { data, rawResponse } = await brevo.transactionalEmails
  .sendTransacEmail({ ... })
  .withRawResponse();

console.log(rawResponse.headers['x-request-id']);
console.log(data.messageId);
```

## Binary responses

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

**`binary-responses.ts`**

```typescript title="binary-responses.ts"
const response = await brevo.inboundParsing.getInboundEmailAttachment(downloadToken);

const stream      = response.stream();
const arrayBuffer = await response.arrayBuffer();
const blob        = await response.blob();
const bytes       = await response.bytes();
```

### Saving binary content

#### Node.js (ReadableStream)

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

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

#### Bun

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

#### Browser

```typescript
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 from the package:

**`typescript-types.ts`**

```typescript title="typescript-types.ts"
import type { Brevo } from '@getbrevo/brevo';

const request: Brevo.SendTransacEmailRequest = {
  subject: 'First email',
  textContent: 'Hello world!',
  sender: { name: 'Bob Wilson', email: 'bob.wilson@brevo.com' },
  to: [{ email: 'sarah.davis@example.com', name: 'Sarah Davis' }],
};
```

## Logging

Configure logging to inspect outgoing requests and responses:

**`logging.ts`**

```typescript title="logging.ts"
import { BrevoClient, logging } from '@getbrevo/brevo';

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

### Custom logger

Integrate with any logging library by implementing the `ILogger` interface:

**`custom-logger.ts`**

```typescript title="custom-logger.ts"
import winston from 'winston';
import { logging } from '@getbrevo/brevo';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [new winston.transports.Console()],
});

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),
};

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

## Custom fetch

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

**`custom-fetch.ts`**

```typescript title="custom-fetch.ts"
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;
  },
});
```

### Common integrations

#### node-fetch

```typescript
import fetch from 'node-fetch';

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

#### undici

```typescript
import { fetch } from 'undici';

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

#### With request ID header

```typescript
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(),
      },
    });
  },
});
```

## 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                                                 | v5.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

**`v3-example.ts`**

```typescript title="v3-example.ts"
// 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: 'bob.wilson@brevo.com' };
message.to = [{ email: 'sarah.davis@example.com', name: 'Sarah Davis' }];

emailAPI.sendTransacEmail(message);
```

**`v5-example.ts`**

```typescript title="v5-example.ts"
// v5.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: 'bob.wilson@brevo.com' },
  to: [{ email: 'sarah.davis@example.com', name: 'Sarah Davis' }],
});
```

## Resources

* [GitHub Repository](https://github.com/getbrevo/brevo-node/tree/main)
* [npm Package](https://www.npmjs.com/package/@getbrevo/brevo)
* [API Reference](https://developers.brevo.com/reference)
* [Support](mailto:support@brevo.com)

> Learn how to integrate the Brevo API into your Node.js and browser applications.

## Docs

- [Node.js SDK Changelog](https://developers.brevo.com/guides/node-js/changelog.md): Release history for the @getbrevo/brevo Node.js SDK.