braze-api

Node.js library for Braze. See docs and demo. The types are from Braze's Postman collection.

Quick Start

import { Braze } from 'braze-api'

const braze = new Braze('YOUR_API_URL', 'YOUR_API_KEY')

await braze.messages.send({
  external_user_ids: ['your_external_user_id'],
  messages: {
    email: {
      app_id: 'your_app_id',
      from: 'Company <company@example.com>',
      email_template_id: 'your_email_template_id',
    },
  },
})

Documentation

• TypeDoc
• Braze API Guide
• Braze's Postman collection

Prerequisites

• Node.js
• Braze account

Installation

NPM:

npm install braze-api

Yarn:

yarn add braze-api

Usage

The package needs to be configured with your account's REST endpoint and API key:

const { Braze } = require('braze-api')

const braze = new Braze('YOUR_API_URL', 'YOUR_API_KEY')

The same can be done with ES Modules:

import { Braze } from 'braze-api'

const braze = new Braze('YOUR_API_URL', 'YOUR_API_KEY')

API URL

Use the REST endpoint provisioned to your account when you log in to the dashboard:

API Key

The API key can be created in your Braze dashboard.

API Methods

The library supports the following Braze API endpoints. Pull requests are welcome!

Campaigns

• <input disabled="" type="checkbox"> /campaigns/data_series
• <input checked="" disabled="" type="checkbox"> /campaigns/details
• <input checked="" disabled="" type="checkbox"> /campaigns/list
• <input disabled="" type="checkbox"> /sends/data_series

Canvas

• <input disabled="" type="checkbox"> /canvas/data_series
• <input disabled="" type="checkbox"> /canvas/data_summary
• <input disabled="" type="checkbox"> /canvas/details
• <input checked="" disabled="" type="checkbox"> /canvas/list

Catalogs

• <input disabled="" type="checkbox"> DELETE /catalogs/{catalog_name}/items
• <input disabled="" type="checkbox"> PATCH /catalogs/{catalog_name}/items
• <input disabled="" type="checkbox"> POST /catalogs/{catalog_name}/items
• <input disabled="" type="checkbox"> PUT /catalogs/{catalog_name}/items/
• <input disabled="" type="checkbox"> DELETE /catalogs/{catalog_name}/items/{item_id}
• <input checked="" disabled="" type="checkbox"> GET /catalogs/{catalog_name}/items/{item_id}
• <input checked="" disabled="" type="checkbox"> GET /catalogs/{catalog_name}/items
• <input disabled="" type="checkbox"> PATCH /catalogs/{catalog_name}/items/{item_id}
• <input disabled="" type="checkbox"> POST /catalogs/{catalog_name}/items/{item_id}
• <input disabled="" type="checkbox"> PUT /catalogs/{catalog_name}/items/{item_id}
• <input disabled="" type="checkbox"> DELETE /catalogs/{catalog_name}
• <input checked="" disabled="" type="checkbox"> GET /catalogs
• <input disabled="" type="checkbox"> POST /catalogs

Content Blocks

• <input checked="" disabled="" type="checkbox"> /content_blocks/list
• <input checked="" disabled="" type="checkbox"> /content_blocks/info
• <input checked="" disabled="" type="checkbox"> /content_blocks/create
• <input checked="" disabled="" type="checkbox"> /content_blocks/update

Custom Events

• <input disabled="" type="checkbox"> /events/list
• <input disabled="" type="checkbox"> /events/data_series

Email List

• <input disabled="" type="checkbox"> /email/hard_bounces
• <input disabled="" type="checkbox"> /email/unsubscribes
• <input checked="" disabled="" type="checkbox"> /email/blacklist
• <input disabled="" type="checkbox"> /email/status
• <input checked="" disabled="" type="checkbox"> /email/bounce/remove
• <input checked="" disabled="" type="checkbox"> /email/spam/remove

Email Templates

• <input checked="" disabled="" type="checkbox"> /templates/email/list
• <input checked="" disabled="" type="checkbox"> /templates/email/info
• <input checked="" disabled="" type="checkbox"> /templates/email/create
• <input checked="" disabled="" type="checkbox"> /templates/email/update

KPI

• <input disabled="" type="checkbox"> /kpi/new_users/data_series
• <input disabled="" type="checkbox"> /kpi/dau/data_series
• <input disabled="" type="checkbox"> /kpi/mau/data_series
• <input disabled="" type="checkbox"> /kpi/uninstalls/data_series

News Feed

• <input disabled="" type="checkbox"> /feed/data_series
• <input disabled="" type="checkbox"> /feed/details
• <input disabled="" type="checkbox"> /feed/list

Purchases

• <input disabled="" type="checkbox"> /purchases/product_list
• <input disabled="" type="checkbox"> /purchases/quantity_series
• <input disabled="" type="checkbox"> /purchases/revenue_series

Preference Center

• <input disabled="" type="checkbox"> /preference_center/v1/{preferenceCenterExternalId}/url/{userId}
• <input disabled="" type="checkbox"> /preference_center/v1/list
• <input disabled="" type="checkbox"> /preference_center/v1/{preferenceCenterExternalId}
• <input disabled="" type="checkbox"> /preference_center/v1
• <input disabled="" type="checkbox"> /preference_center/v1/{preferenceCenterExternalId}

Schedule Messages

• <input checked="" disabled="" type="checkbox"> /messages/scheduled_broadcasts
• <input checked="" disabled="" type="checkbox"> /messages/schedule/delete
• <input checked="" disabled="" type="checkbox"> /canvas/trigger/schedule/delete
• <input checked="" disabled="" type="checkbox"> /campaigns/trigger/schedule/delete
• <input checked="" disabled="" type="checkbox"> /messages/schedule/create
• <input checked="" disabled="" type="checkbox"> /campaigns/trigger/schedule/create
• <input checked="" disabled="" type="checkbox"> /messages/schedule/update
• <input checked="" disabled="" type="checkbox"> /campaigns/trigger/schedule/update
• <input checked="" disabled="" type="checkbox"> /canvas/trigger/schedule/create
• <input checked="" disabled="" type="checkbox"> /canvas/trigger/schedule/update

SCIM

• <input disabled="" type="checkbox"> DELETE /scim/v2/Users/{id}
• <input disabled="" type="checkbox"> GET /scim/v2/Users?filter={userName@example.com}
• <input disabled="" type="checkbox"> GET /scim/v2/Users/{id}
• <input disabled="" type="checkbox"> POST /scim/v2/Users
• <input disabled="" type="checkbox"> PUT /scim/v2/Users/{id}

Segments

• <input checked="" disabled="" type="checkbox"> /segments/list
• <input checked="" disabled="" type="checkbox"> /segments/data_series
• <input checked="" disabled="" type="checkbox"> /segments/details

Send Messages

• <input checked="" disabled="" type="checkbox"> /sends/id/create
• <input checked="" disabled="" type="checkbox"> /messages/send
• <input checked="" disabled="" type="checkbox"> /transactional/v1/campaigns/{{CAMPAIGN_ID}}/send
• <input checked="" disabled="" type="checkbox"> /campaigns/trigger/send
• <input checked="" disabled="" type="checkbox"> /canvas/trigger/send

Sessions

• <input disabled="" type="checkbox"> /sessions/data_series

SMS

• <input disabled="" type="checkbox"> /sms/invalid_phone_numbers
• <input disabled="" type="checkbox"> /sms/invalid_phone_numbers/remove

Subscription Groups

• <input checked="" disabled="" type="checkbox"> /subscription/status/get
• <input checked="" disabled="" type="checkbox"> /subscription/user/status
• <input checked="" disabled="" type="checkbox"> /subscription/status/set
• <input checked="" disabled="" type="checkbox"> /v2/subscription/status/set

User Data

• <input checked="" disabled="" type="checkbox"> /users/export/global_control_group
• <input checked="" disabled="" type="checkbox"> /users/export/ids
• <input checked="" disabled="" type="checkbox"> /users/export/segment
• <input checked="" disabled="" type="checkbox"> /users/external_ids/remove
• <input checked="" disabled="" type="checkbox"> /users/external_ids/rename
• <input checked="" disabled="" type="checkbox"> /users/alias/new
• <input checked="" disabled="" type="checkbox"> /users/delete
• <input checked="" disabled="" type="checkbox"> /users/identify
• <input checked="" disabled="" type="checkbox"> /users/track
• <input checked="" disabled="" type="checkbox"> /users/alias/update
• <input checked="" disabled="" type="checkbox"> /users/merge

Live Activity

• <input disabled="" type="checkbox"> /messages/live_activity/update

Contributing

Contributions are welcome! Check out the guide. 👋

License

MIT

Changelog

2.11.1 (2025-06-26)

Bug Fixes

• added missing android_priority type on messages (4d057dd)
• added missing apns_priority type on messages (#950) (5aec854)

2.11.0 (2025-04-30)

Features

• campaigns: add campaigns.details (GET /campaigns/details) (030dd5e), closes #888

2.10.1 (2024-10-05)

Continuous Integration

• github: publish package to npm registry with provenance (de0f0be)

2.10.0 (2024-07-25)

Features

• add segments (list/details/analytics) (79692e0)

2.9.1 (2024-07-11)

Documentation

• add content blocks endpoints to the readme checklist (#652) (fab0513)

2.9.0 (2024-07-11)

Features

• add support for content block post methods (create/update) (f9e4a69)

2.8.0 (2024-05-29)

Features

• add apple and android push object types (b87d7c5)

2.7.1 (2024-04-25)

Bug Fixes

• types: make app_id optional on PurchaseObject (1a07029), closes #600

2.7.0 (2024-03-20)

Features

• add canvas.list() (d72f65b)

2.6.0 (2024-02-09)

Features

• user data endpoint /users/alias/update implementation (368e9aa)

2.5.6 (2023-10-06)

Bug Fixes

• add missing field in users/export/ids (db9d43a)

2.5.5 (2023-09-26)

Build System

• package: bump @types/node-fetch from 2.6.4 to 2.6.6 (c9fbf96)

2.5.4 (2023-08-26)

Build System

• deps: bump node-fetch from 2.6.13 to 2.7.0 (#359) (7fcd106)

2.5.3 (2023-08-22)

Build System

• deps: bump node-fetch from 2.6.12 to 2.6.13 (#351) (66a910f)

2.5.2 (2023-08-05)

Documentation

• change organization and repository name (329372d)

2.5.1 (2023-08-02)

Bug Fixes

• buildParams: use brackets for arrays (f66d284)
• subscription/user/status: set correct return type (21a88d6)

2.5.0 (2023-07-31)

Features

• campaigns: add campaigns.list (GET /campaigns/list) (75edaf5)

2.4.1 (2023-07-30)

Bug Fixes

• messages: fix GET /messages/scheduled_broadcasts (9ba55b5)
• subscription: fix GET /subscription/user/status (67cb4c0)

2.4.0 (2023-07-29)

Features

• types: export types (86d85ae)

2.3.1 (2023-07-29)

Documentation

• readme: check off recently added API methods (59501df)

2.3.0 (2023-07-27)

Features

• email-templates: add list, get, create and update (f65b0d4)

2.2.2 (2023-07-18)

Bug Fixes

• package: fix "module" field in package.json (efc54f8)

2.2.1 (2023-06-30)

Build System

• deps: bump node-fetch and @types/node-fetch (#288) (355feaf)

2.2.0 (2023-06-23)

Features

• allow calls to /users/merge endpoint (dc07e48)

2.1.1 (2023-06-21)

Bug Fixes

• subscription.status.get pass undefined body instead of empty object (e73d1b1)

2.1.0 (2023-06-16)

Features

• module: add ECMAScript modules (ESM) support (e8eebac)

2.0.1 (2023-04-20)

Bug Fixes

• correct typing of users track returned errors (3ebb2bb)

2.0.0 (2023-03-29)

⚠ BREAKING CHANGES

• catalog list items: catalogs.synchronous.items now returns a generator instead of an array

Features

• catalog list items: return generator instead of array (3a847bd)

Bug Fixes

• catalog items: add pagination (b29081b)

1.32.0 (2023-03-27)

Features

• catalogs: add a few catalog listing endpoints (ca39474)

1.31.0 (2023-03-23)

Features

• content blocks: add list and get (ef2e2fe)

1.30.0 (2022-09-10)

Features

• add email spam remove (a53a6a9)

1.29.0 (2022-09-05)

Features

• add email bounce remove (2f3f812)

1.28.0 (2022-09-04)

Features

• add email blacklist (989e9bd)

1.27.0 (2022-09-02)

Features

• add subscription user status (f1c8a6a)

1.26.0 (2022-08-28)

Features

• add subscription status get (558bb68)

1.25.0 (2022-08-22)

Features

• add v2 subscription status set (0989e12)

1.24.0 (2022-08-21)

Features

• add subscription status set (566afb0)

1.23.0 (2022-08-21)

Features

• add messages scheduled_broadcasts (38eddf2)

1.22.0 (2022-08-21)

Features

• add messages schedule update (52b67bb)

1.21.0 (2022-08-20)

Features

• add messages schedule delete (881b9c1)

1.20.0 (2022-08-20)

Features

• add messages schedule create (d3c4fd8)

1.19.0 (2022-08-16)

Features

• add canvas trigger schedule update (45de80b)

1.18.0 (2022-08-15)

Features

• add canvas trigger schedule delete (efb6522)

1.17.0 (2022-08-14)

Features

• add canvas trigger schedule create (84585a6)

1.16.0 (2022-08-14)

Features

• add campaigns trigger schedule update (5029418)

1.15.0 (2022-08-14)

Features

• add campaigns trigger schedule delete (0339cbb)

1.14.0 (2022-08-13)

Features

• add campaigns trigger schedule create (a5d3972)

1.13.0 (2022-08-13)

Features

• add users export Global Control Group (cc6947b)

1.12.0 (2022-08-09)

Features

• add users export segment (b1e0fd5)

1.11.0 (2022-08-07)

Features

• add users export ids (e22be59)

1.10.0 (2022-08-07)

Features

• add users external_ids remove (dcb8408)

1.9.0 (2022-08-06)

Features

• add users external_ids rename (0341e52)

1.8.0 (2022-08-03)

Features

• add sends id create (73b60d6)

1.7.0 (2022-08-01)

Features

• add canvas trigger send (3cf3725)

1.6.0 (2022-07-31)

Features

• add users delete (9095dd0)

1.5.0 (2022-07-31)

Features

• add users alias new (f67af70)

1.4.0 (2022-07-31)

Features

• add users identify (8b4a1f8)

1.3.0 (2022-07-21)

Features

• add user track (d785dc4), closes #8

1.2.0 (2022-07-10)

Features

• add Braze transactional campaigns send (3346562)

1.1.0 (2022-07-05)

Features

• add Braze campaigns trigger send (01d8e49)

1.0.1 (2022-07-04)

Documentation

• fix README.md (435cfd0)

1.0.0 (2022-07-04)

Features

• add Braze messages send (1b6c80d)