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',
  timeout: 30000,      // 30 seconds
  maxRetries: 3        // Default: 2
});

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 customFetcher = async (url: string, options?: RequestInit): Promise<Response> => {
  // Your custom implementation
  return fetch(url, options);
};

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

Using node-fetch:

import fetch from 'node-fetch';
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  fetcher: fetch as any
});

Using undici:

import { fetch } from 'undici';
const brevo = new BrevoClient({
  apiKey: 'your-api-key',
  fetcher: fetch as any
});

With interceptors:

const createFetcherWithInterceptors = () => {
  return async (url: string, options?: RequestInit): Promise<Response> => {
    const modifiedOptions = {
      ...options,
      headers: {
        ...options?.headers,
        'X-Request-ID': generateRequestId()
      }
    };
    const response = await fetch(url, modifiedOptions);
    console.log('Response:', response.status);
    return response;
  };
};

Runtime Compatibility

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

Migration from v3.x

This version includes breaking changes:

Key Changes:

• New client initialization
• Promise-based API
• Improved TypeScript support
• Standardized error handling

Example:

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

v4.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 v4.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