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.
Overview
Braze 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-integrationfeature flag 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
If your Braze instance restricts API access by IP, you will need to allowlist Gradial’s egress IP addresses before connecting. See IP Allowlisting for the full list.
Step 1: Generate a Braze REST API Key
- Log in to your Braze dashboard
- Navigate to Settings → API Keys
- Click Create New API Key
- Give the key a descriptive name (e.g.,
Gradial Integration) - 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 |
- 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
- In Gradial, navigate to Settings → Integrations
- Click Add Braze Integration
- 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) |
- Click Save
Note: Gradial normalizes the Braze REST host and trims any trailing slash. Header Name and Prefix default toAuthorizationandBearerif left blank.
Testing the Integration
After saving, Gradial validates the connection by:- Calling
POST /users/trackwith an empty payload to verify auth and general API access - Calling
GET /segments/listto confirm segment read access
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.Audience Discovery and Sizing
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.
Campaign Reads and API-Triggered Sends
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.
Canvas Reads and API-Triggered Sends
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.
Email Templates and Content Blocks
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.
Catalog Item Reads
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.
Subscription and Governance Checks
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.
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 |