---
title: "Braze Connector"
description: "Complete Braze integration guide for syncing customer engagement data, campaigns, and messaging events with Brevo via Tajo."
url: https://tajo.io/docs/connectors/marketing/braze/
markdown: https://tajo.io/docs/connectors/marketing/braze.md
lang: en-US
robots: noindex
---

# Braze Connector

Connector status: Planned Not built yet. Tajo does not run this connector today.

| Source field | Destination field | Sample value |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Connect your Braze engagement platform to Brevo for unified customer profiles, cross-channel campaign orchestration, and consolidated marketing analytics.

## Overview

| Property | Value |
| --- | --- |
| **Platform** | Braze |
| **Category** | Marketing |
| **Setup Complexity** | Moderate |
| **Official Integration** | No |
| **Data Synced** | Customers, Events, Campaigns, Messages |
| **API Type** | REST API |
| **Authentication** | API Key |
| **Base URL** | `https://rest.iad-XX.braze.com` (instance-specific) |

## Features

- **User profile sync** - Bidirectional customer attribute synchronization between Braze and Brevo
- **Campaign event tracking** - Track email opens, clicks, conversions, and unsubscribes
- **Canvas flow data** - Sync multi-step campaign journey data for unified reporting
- **Segment mirroring** - Replicate Braze segments as Brevo lists for cross-platform targeting
- **Push notification events** - Forward push engagement data to Brevo contact timelines
- **Catalog sync** - Synchronize product catalogs for personalized recommendations

## Prerequisites

Before you begin, ensure you have:

1. A Braze account with API access enabled
2. A Braze REST API key with appropriate permissions
3. Your Braze instance URL (e.g., `rest.iad-01.braze.com`)
4. A Brevo account with API access
5. A Tajo account with an active subscription

## Authentication

Braze uses API key authentication. Each API key can be scoped to specific endpoints.

### Creating an API Key

1. Log in to your Braze dashboard
2. Navigate to **Settings** > **API Keys**
3. Click **Create New API Key**
4. Name it “Tajo Integration”
5. Enable the following permissions:

```
users.track
users.export.ids
users.export.segment
campaigns.list
campaigns.data_series
canvas.list
canvas.data_series
segments.list
segments.data_series
email.status
subscription.status.set
catalogs.list_items
```

API Key Security

Store your Braze API key securely. Never expose it in client-side code or public repositories. Tajo encrypts all API credentials at rest using AES-256.

### Connecting to Tajo

```bash
tajo connectors install braze \
  --api-key $BRAZE_API_KEY \
  --instance-url rest.iad-01.braze.com
```

## Configuration

### Basic Setup

```yaml
connectors:
  braze:
    enabled: true
    instance_url: "rest.iad-01.braze.com"
    api_version: "v1"

    sync:
      users: true
      campaigns: true
      canvases: true
      segments: true
      events: true

    lists:
      engaged_users: 10
      dormant_users: 11
```

### Field Mapping

Map Braze user attributes to Brevo contact attributes:

```yaml
field_mapping:
  # Standard fields
  external_id: BRAZE_ID
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Engagement metrics
  total_revenue: TOTAL_REVENUE
  push_opted_in: PUSH_OPTIN
  email_subscribe: EMAIL_STATUS

  # Custom attributes
  loyalty_points: LOYALTY_POINTS
  last_app_version: APP_VERSION
  preferred_language: LANGUAGE
```

## API Endpoints

Tajo integrates with the following Braze REST API endpoints:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/users/track` | POST | Send user attributes, events, and purchases |
| `/users/export/ids` | POST | Export user profiles by external IDs |
| `/users/export/segment` | POST | Export users from a segment |
| `/campaigns/list` | GET | Retrieve list of campaigns |
| `/campaigns/data_series` | GET | Campaign analytics over time |
| `/canvas/list` | GET | Retrieve list of Canvas flows |
| `/canvas/data_series` | GET | Canvas analytics over time |
| `/segments/list` | GET | Retrieve list of segments |
| `/email/status` | POST | Change email subscription status |
| `/subscription/status/set` | POST | Set subscription group status |
| `/catalogs/{catalog_name}/items` | GET | Retrieve catalog items |

## Code Examples

### Initialize Connector

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('braze', {
  apiKey: process.env.BRAZE_API_KEY,
  instanceUrl: 'rest.iad-01.braze.com'
});
```

### Sync User Profiles

```javascript
// Sync Braze users to Brevo contacts
await tajo.connectors.sync('braze', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01',
  batchSize: 50
});

// Check sync status
const status = await tajo.connectors.status('braze');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T10:30:00Z',
//   usersCount: 45200,
//   campaignsTracked: 28,
//   eventsProcessed: 125000
// }
```

### Track Custom Events

```javascript
// Forward Braze events to Brevo
await tajo.connectors.handleEvent('braze', {
  type: 'user.event',
  payload: {
    external_id: 'user_12345',
    name: 'product_viewed',
    properties: {
      product_id: 'SKU-789',
      category: 'electronics',
      price: 299.99
    }
  }
});
```

### Export Segment Data

```javascript
// Export a Braze segment and create a Brevo list
const result = await tajo.connectors.exportSegment('braze', {
  segmentId: 'segment_abc123',
  targetList: 15,
  includeAttributes: ['email', 'first_name', 'last_name', 'total_revenue']
});

console.log(`Exported ${result.count} users to Brevo list 15`);
```

## Rate Limits

Braze enforces rate limits based on your plan and instance:

| Plan | Rate Limit | Burst Limit |
| --- | --- | --- |
| **Starter** | 250,000 requests/hour | N/A |
| **Pro** | 250,000 requests/hour | N/A |
| **Enterprise** | Custom | Custom |

The `/users/track` endpoint has a default limit of 50,000 requests per minute. Tajo automatically handles rate limiting with exponential backoff.

Batch Requests

Tajo batches up to 75 user attributes, 75 events, and 75 purchases per `/users/track` request to maximize throughput within rate limits.

## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
| --- | --- | --- |
| 401 Unauthorized | Invalid or expired API key | Regenerate API key in Braze dashboard |
| Users not syncing | Incorrect instance URL | Verify your Braze instance URL (e.g., iad-01, iad-02) |
| Missing attributes | API key scope too narrow | Add required permissions to API key |
| Rate limit exceeded | Too many concurrent requests | Reduce batch size or sync frequency |
| Events delayed | Large export queue | Use incremental sync instead of full export |

### Debug Mode

```yaml
connectors:
  braze:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### Test Connection

```bash
tajo connectors test braze
# ✓ API connection successful
# ✓ User export accessible
# ✓ Campaign data readable
# ✓ Segment list accessible
# ✓ Event tracking operational
```

## Best Practices

1. **Use incremental syncs** - Avoid full exports; sync only changed records since last sync
2. **Batch user updates** - Group attribute changes to minimize API calls
3. **Scope API keys narrowly** - Only enable the permissions your integration needs
4. **Monitor rate limits** - Set up alerts before hitting Braze rate limits
5. **Map external IDs consistently** - Use the same identifier across Braze and Brevo
6. **Test in sandbox first** - Use a Braze test workspace before production deployment

## Security

- **API Key Authentication** - Scoped API keys with granular permissions
- **HTTPS Only** - All API communication encrypted via TLS 1.2+
- **IP Allowlisting** - Optional IP restriction for API access in Braze
- **Encrypted Storage** - API credentials encrypted at rest in Tajo
- **Audit Logging** - All API calls logged for compliance review

## Related Resources

- [Customer.io Connector](https://tajo.io/docs/connectors/marketing/customerio)
- [Iterable Connector](https://tajo.io/docs/connectors/marketing/iterable)
- [Customer Sync Skill](https://tajo.io/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/docs/contact-management)

## Open-Source Implementation Map

This section is derived from official or public repository material discovered for the Braze connector. Use it as the engineering companion to the setup guide above: it shows where the API surface lives, what implementation assets exist, and how Tajo should translate them into reliable Brevo sync behavior.

### Repository Snapshot

| Repository | Commit | Languages / formats | Files |
| --- | --- | --- | --- |
| [braze-community/braze-specification](https://github.com/braze-community/braze-specification) | 0b0856e | TypeScript (22), JSON (9), YAML (6), Markdown (3), github/codeowners (1), gitignore (1) | 47 |

### Integration Shape

```mermaid
graph LR
  Source["Braze API / repository"] --> Auth["Auth and scopes"]
  Source --> Objects["Objects, events, and schemas"]
  Auth --> Tajo["Tajo connector runtime"]
  Objects --> Tajo
  Tajo --> Brevo["Brevo contacts, attributes, lists, campaigns"]
  Tajo --> Ops["Backfill, cursor, retries, logs"]
```

### What To Reuse

- braze-specification
- Braze API specification:
- - OpenAPI spec
- - Postman collection
- See the original Postman collection.

### Tajo Revamp Checklist

- Keep authentication setup aligned with the vendor docs and the public repository’s current API shape.
- Map primary resources into explicit Tajo sync objects with stable external IDs.
- Prefer cursor-based or updated-at incremental sync where the API exposes it; otherwise document the fallback.
- Treat webhook handlers as idempotent and replay-safe, especially for order, contact, ticket, and campaign events.
- Capture pagination, rate limits, retry headers, and partial-failure behavior in connector smoke tests.
- Keep examples small and runnable against sandbox or test-mode accounts.

### Sources

- [braze-community/braze-specification](https://github.com/braze-community/braze-specification)
- [Vendor documentation](https://www.braze.com/docs/api/basics/)