braze-api

library2.13.2jsnpmunverified

The `braze-api` library provides a community-maintained Node.js client for interacting with the Braze customer engagement platform's REST API. It allows developers to track user events, send targeted messages (email, push, in-app), export data, manage campaigns and canvases, and interface with other core Braze functionalities. The current stable version is 2.13.2 (as of November 2025), with frequent patch and minor releases, indicating active development. A key differentiator is its comprehensive TypeScript type definitions, which are derived from Braze's official Postman collection [3, 14], offering strong type safety for API requests and responses. While not officially endorsed by Braze, Inc. [3, 14], it aims to provide a robust, well-typed abstraction over the direct REST calls, simplifying integration for Node.js applications and supporting modern JavaScript features since Node.js 14. [4]

communication aws

npm install braze-api

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BRAZE-API

braze-api

communicationjavascriptv2.13.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Braze

✓ import { Braze } from 'braze-api'

✗ const Braze = require('braze-api')

The primary class for instantiating the Braze API client. Supports both ES Modules and CommonJS. Use named import for clarity when possible.

IMessagesSendRequest

✓ import type { IMessagesSendRequest } from 'braze-api'

TypeScript interface for the overall payload sent to the `/messages/send` endpoint, providing type safety for API request bodies. [5, 7, 8]

IEmailMessage

✓ import type { IEmailMessage } from 'braze-api'

TypeScript interface for the email message object, typically nested within a larger request payload like `IMessagesSendRequest`, defining email-specific properties. [16]

This quickstart initializes the Braze client and sends a transactional email to a user identified by `external_user_id` using a pre-configured email template. It demonstrates basic client instantiation and calling a messaging endpoint.

import { Braze } from 'braze-api'; const BRAZE_API_URL = process.env.BRAZE_API_URL ?? 'https://rest.iad-01.braze.com'; const BRAZE_API_KEY = process.env.BRAZE_API_KEY ?? ''; const BRAZE_APP_ID = process.env.BRAZE_APP_ID ?? 'your_app_id'; // Obtain from Braze dashboard const EXTERNAL_USER_ID = process.env.EXTERNAL_USER_ID ?? 'user_123'; const EMAIL_TEMPLATE_ID = process.env.EMAIL_TEMPLATE_ID ?? 'your_email_template_id'; // Obtain from Braze dashboard async function sendEmail() { if (!BRAZE_API_KEY) { console.error('BRAZE_API_KEY environment variable is not set.'); return; } const braze = new Braze(BRAZE_API_URL, BRAZE_API_KEY); try { const response = await braze.messages.send({ external_user_ids: [EXTERNAL_USER_ID], messages: { email: { app_id: BRAZE_APP_ID, from: 'Company Name <company@example.com>', email_template_id: EMAIL_TEMPLATE_ID, // Alternatively, provide 'subject' and 'body' instead of 'email_template_id' // subject: 'Welcome to our service!', // body: '<html><body><h1>Hello!</h1><p>Welcome to our platform.</p></body></html>' } } }); console.log('Email sent successfully:', response); } catch (error) { console.error('Failed to send email:', error); } } sendEmail();

Debug

Known issues

gotchaThis package is community-maintained and not officially endorsed or supported by Braze, Inc. [3, 14] Enterprise users requiring official support or specific SLAs should be aware of this distinction.

fix

Ensure your organization's support strategy accounts for using a community-maintained client or consider direct API integration if official vendor support is paramount.

affects: >=2.0.0

gotchaIncorrect Braze API URL (REST endpoint) or API Key can lead to authentication errors or requests being sent to the wrong regional instance. Endpoints are region-specific (e.g., `rest.iad-01.braze.com`, `rest.fra-01.braze.eu`). [2, 14]

fix

Verify your Braze dashboard's REST endpoint and API key. Store credentials securely using environment variables or a secrets manager. [2, 4, 14]

affects: >=2.0.0

gotchaBraze API endpoints have rate limits, typically 250,000 requests per hour per workspace for most endpoints. [4, 7] High-volume requests without proper throttling or exponential backoff can lead to API errors (e.g., 429 Too Many Requests) and temporary IP blocking.

fix

Implement client-side rate limiting, batch requests when possible (up to 50 recipients per `/messages/send` request), and use exponential backoff for retries on transient API errors. [4, 7]

affects: >=2.0.0

gotchaBraze API Keys provide extensive access to your Braze account. Exposing them in client-side code, public repositories, or insecure configurations can lead to data breaches and unauthorized access. [2, 4]

fix

Always store API keys securely (e.g., environment variables, secret managers) and never commit them to version control. Restrict key permissions to the minimum necessary actions. [4]

affects: >=2.0.0

gotchaWhen using `/messages/send` with `external_user_ids`, the recipient must already exist in Braze. This endpoint does not create new user profiles. [7, 8, 9]

fix

To create new users or ensure user existence before sending, use the `/users/track` endpoint first, or consider using API-triggered campaigns where user creation might be handled differently. [7, 8]

affects: >=2.0.0

Errors

Common errors & fixes

Braze API Error: 401 Unauthorized

Invalid or missing API Key provided for authentication. [2]

fix

Ensure the `BRAZE_API_KEY` is correct and has the necessary permissions configured in your Braze dashboard. Check for leading/trailing spaces or typos.

TypeError: Braze is not a constructor

Incorrect import or require statement when trying to instantiate the `Braze` client class in your JavaScript/TypeScript environment.

fix

For ES Modules (recommended): `import { Braze } from 'braze-api';`. For CommonJS: `const { Braze } = require('braze-api');`.

Error: getaddrinfo ENOTFOUND rest.your-braze-region.braze.com

The Braze REST endpoint URL (`BRAZE_API_URL`) is incorrect, misspelled, or there's a network connectivity issue preventing DNS resolution. [2, 14]

fix

Verify `BRAZE_API_URL` against the official Braze documentation for your specific instance (e.g., `https://rest.iad-01.braze.com`). Check network proxy or firewall settings if applicable. [2, 14]

Braze API Error: 400 Bad Request - Required field 'external_user_ids' missing.

The request payload sent to a Braze API endpoint is missing a required field or contains improperly formatted data. [5]

fix

Consult the Braze API documentation for the specific endpoint you are calling (e.g., `/messages/send`) to ensure all required fields are present and correctly formatted in your request payload. [5, 6, 8]

Upgrade

Version history

2.13.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/braze-community/braze-node ↗

packagehttps://www.npmjs.com/package/braze-api ↗

homepagehttps://www.braze.com ↗