How to Integrate Braze with Your Headless CMS

What is Braze?

Braze is a customer engagement platform for email, push, SMS, in-app messages, Content Cards, and cross-channel journeys built in Canvas. Growth, lifecycle, product, and marketing teams use it to segment audiences, personalize messages, run experiments, and trigger campaigns from customer behavior. It’s commonly used by consumer apps, subscription businesses, retailers, media companies, and financial services teams that send high-volume customer communications.

Why integrate Braze with a headless CMS?

Braze campaigns move fast. A lifecycle team might run a welcome series, three abandoned cart variants, a price-drop push, a localized winback email, and an in-app promo in the same week. If campaign content lives in one place and Braze lives in another, someone ends up copying subject lines, legal disclaimers, offer text, image URLs, and localized strings by hand. That creates avoidable errors, especially when the same promotion has to appear in email, push, web, mobile, and Content Cards.

Connecting Braze to a headless CMS category tool helps, but the quality of the integration depends on the shape of the content. When content is structured as typed fields, Braze can receive exactly what it needs, such as `headline`, `shortMessage`, `offerCode`, `expiresAt`, `locale`, and `audienceSegment`. With Sanity’s AI Content Operating System, that structured content lives in the Content Lake, GROQ selects the fields for each Braze use case, and webhooks or Functions trigger sync logic on publish events. No HTML scraping. No spreadsheet import. No waiting for a nightly batch job.

The trade-off is that you need to model your campaign content upfront and decide which system owns which data. Braze should usually own customer profiles, events, journeys, and message delivery. Sanity should own reusable campaign content, editorial approvals, localized copy, offer metadata, and channel-specific fields. Once that boundary is clear, the integration becomes easier to test and safer for marketing teams to run.

Architecture overview

A typical Sanity and Braze integration starts when an editor publishes campaign content in Sanity Studio. A Sanity webhook listens for publish events on documents like `campaignMessage`, `promotion`, or `localizedOffer`. The webhook payload includes the changed document ID, and a Sanity Function or webhook listener uses `@sanity/client` to fetch the current published version from the Content Lake. The sync layer uses GROQ to select only the fields Braze needs. For example, an email Content Block might need `title`, `preheader`, `body`, `ctaLabel`, and `ctaUrl`, while a Braze Catalog item might need `offerCode`, `discount`, `expiresAt`, `imageUrl`, and `locale`. GROQ can also join referenced documents, such as pulling brand disclaimers, product names, or localized asset URLs into one payload. After mapping the Sanity fields to Braze’s expected format, the Function calls the Braze REST API using your Braze REST endpoint, such as `https://rest.iad-01.braze.com`, and an API key with the right permissions. Common targets include `/content_blocks/update` for reusable message content, `/campaigns/trigger/send` for triggered campaigns, and Braze Catalog endpoints for offer or product-like personalization data. Braze then uses that synced content inside Canvas, campaigns, Liquid personalization, in-app messages, push notifications, email, SMS, or Content Cards delivered to the end user.

Common use cases

Step-by-step integration

1. 1

   Set up Braze access

   Create or confirm your Braze workspace, note your REST endpoint, and create a REST API key with only the permissions you need, such as `content_blocks.update`, `campaigns.trigger.send`, or catalog item permissions. If you’re tracking user behavior from a web app, install the Braze Web SDK with `npm install @braze/web-sdk` and initialize it with your Web SDK API key.

2. 2

   Model campaign content in Sanity Studio

   Create schemas for the content Braze will use. A `campaignMessage` schema might include `title`, `preheader`, `body`, `ctaLabel`, `ctaUrl`, `locale`, `channel`, `brazeContentBlockId`, `publishWindow`, and references to reusable legal text or product content.

3. 3

   Create a GROQ query for the Braze payload

   Write a GROQ query that returns only the fields Braze needs. Include joined references when useful, such as product names, image URLs, offer terms, or market-specific disclaimers. Keep delivery fields separate from editorial-only fields like internal notes.

4. 4

   Add a webhook or Sanity Function

   Create a Sanity webhook that fires on publish events for the relevant document types. Point it at a Sanity Function or your own API route. Functions are a good fit when you want server-side sync logic without running separate infrastructure.

5. 5

   Call the Braze REST API

   Map the Sanity document to the Braze endpoint you’re using. For reusable campaign copy, update a Braze Content Block with `/content_blocks/update`. For triggered sends, call `/campaigns/trigger/send`. For personalization data, sync catalog-like records into Braze Catalogs.

6. 6

   Test the full message path

   Publish a test document in Sanity, confirm the webhook fired, inspect the Braze API response, and preview the message in Braze. Then test the frontend or app experience with the Braze SDK, including user identity, subscription state, locale, and any Liquid variables used in the message.

How Sanity + Braze works

CMS approaches to Braze

Keep building

Explore related integrations to complete your content stack.