> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Braze

> How to set up and configure Gradial with Braze for audience analysis, campaign management, content operations, and controlled sends.

## Overview

[Braze](https://www.braze.com) is a customer engagement platform used by enterprise brands to orchestrate personalized, cross-channel communications across email, SMS, push notifications, WhatsApp, and more. Marketing and CRM teams use Braze to build audience segments, design lifecycle journeys in Canvas, manage campaign sends, and deliver real-time personalization at scale.

### Why use Gradial with Braze?

Braze is powerful, but activating it at speed — especially across large content programs — requires coordinating audience logic, creative content, send schedules, and performance analysis in ways that are time-consuming to do manually.

Gradial adds an AI agent layer on top of Braze so your team can:

* **Discover and size audiences in plain language** — ask questions about existing segments, inspect membership trends, and get targeting blueprints without writing queries
* **Manage email templates and content blocks at scale** — generate, update, and review reusable content without navigating the dashboard for each change
* **Orchestrate sends and schedules from chat** — trigger API-triggered campaigns and Canvases, review dry-run previews, and confirm live sends from a single conversation
* **Analyze campaign and Canvas performance on demand** — pull analytics data series and summaries directly into your workflow

## Prerequisites

Before a workspace can use Braze in Gradial:

* The Braze integration must be enabled for your workspace (contact your Gradial representative)
* Only an org admin can add a Braze integration in **Settings → Integrations**
* Your Braze REST API key must have sufficient permissions for the workflows you plan to run

## Setup

<Info>
  If your Braze instance restricts API access by IP, you will need to allowlist Gradial's egress IP addresses before connecting. See [IP Allowlisting](/docs/integrations-administration-and-setup/ip-allowlist) for the full list.
</Info>

### Step 1: Generate a Braze REST API Key

1. Log in to your Braze dashboard
2. Navigate to **Settings** → **API Keys**
3. Click **Create New API Key**
4. Give the key a descriptive name (e.g., `Gradial Integration`)
5. Enable the following permissions at minimum:

| Permission                          | Required | Purpose                                |
| :---------------------------------- | :------- | :------------------------------------- |
| `segments.list`                     | Yes      | Required for connection validation     |
| `segments.data_series`              | Yes      | Segment analytics and trend data       |
| `segments.details`                  | Yes      | Read segment metadata                  |
| `users.export.segment`              | Optional | Export users from a saved segment      |
| `users.export.ids`                  | Optional | Export users by identifier             |
| `users.track`                       | Yes      | Required for connection validation     |
| `campaigns.list`                    | Optional | List campaigns                         |
| `campaigns.details`                 | Optional | Read campaign metadata and analytics   |
| `campaigns.trigger.send`            | Optional | API-triggered campaign sends           |
| `campaigns.trigger.schedule.create` | Optional | Schedule campaign triggers             |
| `campaigns.trigger.schedule.update` | Optional | Update campaign trigger schedules      |
| `campaigns.trigger.schedule.delete` | Optional | Delete campaign trigger schedules      |
| `canvas.list`                       | Optional | List Canvases                          |
| `canvas.details`                    | Optional | Read Canvas metadata and analytics     |
| `canvas.trigger.send`               | Optional | API-triggered Canvas sends             |
| `canvas.trigger.schedule.create`    | Optional | Schedule Canvas triggers               |
| `templates.email.list`              | Optional | List email templates                   |
| `templates.email.info`              | Optional | Read email template details            |
| `templates.email.create`            | Optional | Create email templates                 |
| `templates.email.update`            | Optional | Update email templates                 |
| `content_blocks.list`               | Optional | List content blocks                    |
| `content_blocks.info`               | Optional | Read content block details             |
| `content_blocks.create`             | Optional | Create content blocks                  |
| `content_blocks.update`             | Optional | Update content blocks                  |
| `subscription.status.get`           | Optional | Read subscription group status         |
| `catalogs.get_items`                | Optional | Read catalog items for personalization |

6. Click **Save API Key** and copy the key value

> **Important:** Keep your API key secure. Treat it as a sensitive credential. You can revoke and regenerate it from the Braze API Keys settings page at any time.

### Step 2: Configure the Integration in Gradial

1. In Gradial, navigate to **Settings** → **Integrations**
2. Click **Add Braze Integration**
3. Fill in the connection form:

| Field            | Required | Value                                                            |
| :--------------- | :------- | :--------------------------------------------------------------- |
| Integration Name | Yes      | A label for this connection (e.g., `Production Braze`)           |
| Braze REST Host  | Yes      | Your Braze REST endpoint (e.g., `https://rest.iad-01.braze.com`) |
| Auth Type        | Yes      | `apiKeyHeader`                                                   |
| API Key          | Yes      | The key generated in Step 2                                      |
| Header Name      | Yes      | `Authorization` (default)                                        |
| Prefix           | Yes      | `Bearer` (default)                                               |

4. Click **Save**

> **Note:** Gradial normalizes the Braze REST host and trims any trailing slash. Header Name and Prefix default to `Authorization` and `Bearer` if left blank.

## Testing the Integration

After saving, Gradial validates the connection by:

1. Calling `POST /users/track` with an empty payload to verify auth and general API access
2. Calling `GET /segments/list` to confirm segment read access

Both checks must pass for the integration to show a **Connected** status.

### Common Issues

| Issue                                | Cause                                    | Solution                                                                         |
| :----------------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------- |
| Validation fails after auth succeeds | API key lacks `segments/list` permission | Add `segments.list` permission to the key                                        |
| `unauthorized` error                 | Incorrect API key                        | Verify the key value in Braze API Keys settings                                  |
| Wrong REST host                      | Incorrect Braze cluster                  | Check your Braze instance URL — the cluster is in the subdomain (e.g., `iad-01`) |

### Rotating Credentials

Braze credentials can be updated without rebuilding the connection. Updating the API key preserves the existing host, header settings, and all other connection configuration.

## What Users Can Do in Gradial with Braze

Once set up, the Braze agent is available in chat. Users can ask for audience analysis, campaign reads, content operations, and controlled sends — the agent routes these requests through the Braze toolset.

<AccordionGroup>
  <Accordion title="Audience Discovery and Sizing">
    List and inspect existing segments, read segment trend data, discover audience field names and event names from segment metadata, export users from a saved segment or by identifier, read KPI series (new users, DAU, MAU, uninstalls), and generate a connected-audience blueprint for ad hoc targeting logic.

    **Example prompts:**

    * `What Braze segments do we already have for loyalty members?`
    * `How large is our cart abandoner audience?`
    * `List the events we can use for a checkout re-engagement audience.`
    * `Build the targeting logic for members who abandoned cart in the last 7 days.`

    **Limitation:** Saved segment creation, update, and archive are not supported. When a requested audience does not already exist as a saved segment, the agent produces an API-ready targeting blueprint, but the final saved segment must be created in the Braze dashboard.
  </Accordion>

  <Accordion title="Campaign Reads and API-Triggered Sends">
    List campaigns, read campaign details and analytics, send messages directly, trigger existing API-triggered campaigns, and create, update, or delete trigger schedules.

    Send and schedule actions default to **dry-run preview** behavior. Live execution requires explicit confirmation.

    **Example prompts:**

    * `Show me the analytics for our re-engagement campaign over the last 14 days.`
    * `Prepare a dry run for an API-triggered campaign to our VIP segment.`
    * `Schedule our win-back campaign to send tomorrow at 9 AM local time.`

    **Limitation:** Campaign authoring is not supported. Use the Braze dashboard for creating and editing campaigns; use Gradial for reads, previews, sends, and scheduling.
  </Accordion>

  <Accordion title="Canvas Reads and API-Triggered Sends">
    List Canvases, read Canvas details and analytics, trigger existing Canvases, and create, update, or delete Canvas trigger schedules.

    Trigger sends and schedule mutations default to **dry run**. Live execution requires explicit confirmation.

    **Example prompts:**

    * `List our active Braze Canvases.`
    * `Summarize Canvas performance for our onboarding journey.`
    * `Prepare a dry run to trigger our win-back Canvas for a test audience.`

    **Limitation:** Canvas flow authoring (step design, branching, persistent journey editing) still happens in the Braze dashboard.
  </Accordion>

  <Accordion title="Email Templates and Content Blocks">
    List, read, create, and update email templates and content blocks.

    The content tool supports dry-run previews for create and update actions. Content block names must contain only letters, numbers, dashes, and underscores.

    **Example prompts:**

    * `List our Braze email templates updated this month.`
    * `Create a content block for our spring loyalty sale.`
    * `Update our welcome email template with a shorter subject line.`

    **Limitation:** Template and content-block create endpoints do not support idempotency keys, so a retried create action can produce duplicates.
  </Accordion>

  <Accordion title="Catalog Item Reads">
    List items in a Braze catalog and read specific catalog items. This is read-only and intended for retail personalization workflows where the agent needs to inspect catalog data before generating or validating message content.

    **Example prompts:**

    * `List items in the loyalty_rewards catalog.`
    * `Show me the details for a specific catalog item.`

    **Limitation:** Catalog creation, update, and deletion are not available through the agent toolset.
  </Accordion>

  <Accordion title="Subscription and Governance Checks">
    Read subscription status for a subscription group and read a user's subscription status across groups. Useful for consent validation, channel governance checks, and verifying subscription state before activation.

    **Limitation:** Subscription-state mutation is not exposed through the chat toolset.
  </Accordion>
</AccordionGroup>

## What Still Happens in Braze

The following operations are intentionally out of scope for the current Gradial Braze integration and must be performed in the Braze dashboard:

| Not supported in Gradial              | Workaround                                                                   |
| :------------------------------------ | :--------------------------------------------------------------------------- |
| Saved segment create, update, archive | Build the criteria in Gradial, then save the segment in the Braze dashboard  |
| Full campaign authoring               | Author in Braze, then use Gradial for reads, previews, sends, and scheduling |
| Canvas step and branch authoring      | Design in Braze, then use Gradial for reads and trigger operations           |
| Catalog mutation                      | Manage catalog structure and items in the Braze dashboard                    |
| User deletion                         | Not available through agent tools                                            |
| Subscription mutation                 | Manage in the Braze dashboard                                                |

## Need Help?

Contact your Gradial representative for additional support with your Braze integration.