{"id":12907,"library":"braze-api","title":"Braze API Client for Node.js","description":"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]","status":"active","version":"2.13.2","language":"javascript","source_language":"en","source_url":"https://github.com/braze-community/braze-node","tags":["javascript","braze","api","rest","node","appboy","typescript"],"install":[{"cmd":"npm install braze-api","lang":"bash","label":"npm"},{"cmd":"yarn add braze-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add braze-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for instantiating the Braze API client. Supports both ES Modules and CommonJS. Use named import for clarity when possible.","wrong":"const Braze = require('braze-api')","symbol":"Braze","correct":"import { Braze } from 'braze-api'"},{"note":"TypeScript interface for the overall payload sent to the `/messages/send` endpoint, providing type safety for API request bodies. [5, 7, 8]","symbol":"IMessagesSendRequest","correct":"import type { IMessagesSendRequest } from 'braze-api'"},{"note":"TypeScript interface for the email message object, typically nested within a larger request payload like `IMessagesSendRequest`, defining email-specific properties. [16]","symbol":"IEmailMessage","correct":"import type { IEmailMessage } from 'braze-api'"}],"quickstart":{"code":"import { Braze } from 'braze-api';\n\nconst BRAZE_API_URL = process.env.BRAZE_API_URL ?? 'https://rest.iad-01.braze.com';\nconst BRAZE_API_KEY = process.env.BRAZE_API_KEY ?? '';\nconst BRAZE_APP_ID = process.env.BRAZE_APP_ID ?? 'your_app_id'; // Obtain from Braze dashboard\nconst EXTERNAL_USER_ID = process.env.EXTERNAL_USER_ID ?? 'user_123';\nconst EMAIL_TEMPLATE_ID = process.env.EMAIL_TEMPLATE_ID ?? 'your_email_template_id'; // Obtain from Braze dashboard\n\nasync function sendEmail() {\n if (!BRAZE_API_KEY) {\n console.error('BRAZE_API_KEY environment variable is not set.');\n return;\n }\n\n const braze = new Braze(BRAZE_API_URL, BRAZE_API_KEY);\n\n try {\n const response = await braze.messages.send({\n external_user_ids: [EXTERNAL_USER_ID],\n messages: {\n email: {\n app_id: BRAZE_APP_ID,\n from: 'Company Name ',\n email_template_id: EMAIL_TEMPLATE_ID,\n // Alternatively, provide 'subject' and 'body' instead of 'email_template_id'\n // subject: 'Welcome to our service!',\n // body: '

Hello!

Welcome to our platform.

'\n }\n }\n });\n console.log('Email sent successfully:', response);\n } catch (error) {\n console.error('Failed to send email:', error);\n }\n}\n\nsendEmail();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Verify your Braze dashboard's REST endpoint and API key. Store credentials securely using environment variables or a secrets manager. [2, 4, 14]","message":"Incorrect 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]","severity":"gotcha","affected_versions":">=2.0.0"},{"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]","message":"Braze 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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]","message":"Braze 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]","severity":"gotcha","affected_versions":">=2.0.0"},{"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]","message":"When 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]","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Invalid or missing API Key provided for authentication. [2]","error":"Braze API Error: 401 Unauthorized"},{"fix":"For ES Modules (recommended): `import { Braze } from 'braze-api';`. For CommonJS: `const { Braze } = require('braze-api');`.","cause":"Incorrect import or require statement when trying to instantiate the `Braze` client class in your JavaScript/TypeScript environment.","error":"TypeError: Braze is not a constructor"},{"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]","cause":"The Braze REST endpoint URL (`BRAZE_API_URL`) is incorrect, misspelled, or there's a network connectivity issue preventing DNS resolution. [2, 14]","error":"Error: getaddrinfo ENOTFOUND rest.your-braze-region.braze.com"},{"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]","cause":"The request payload sent to a Braze API endpoint is missing a required field or contains improperly formatted data. [5]","error":"Braze API Error: 400 Bad Request - Required field 'external_user_ids' missing."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}