---
name: braze-implementation-qa
description: Implements and tests Braze so the right profile enters a Canvas, gets the right message and stops on time. Covers external_id, changeUser and logout, aliases and merges, /users/track partial failures and rate limits, API-triggered versus action-based entry, re-eligibility, send-time rechecks, frequency caps, subscription groups, quiet hours and the Global Control Group. Diagnoses a missing or unwanted message gate by gate and writes a synthetic Canvas test plan. Use when setting up or reviewing a Braze integration, Canvas not sending, users not entering a Canvas, users entered but nothing was sent, sent to the wrong people or twice, exit criteria not working, a user did not get a Braze email, push or SMS, /users/track errors or 429s, duplicate anonymous and known profiles, action-based vs API-triggered, a Braze MCP Canvas audit, a Braze launch review, or a Braze QA checklist or Canvas test plan.
license: CC-BY-4.0
metadata:
  tier: free
  category: lifecycle-messaging
  version: "0.2.0"
  last_reviewed: "2026-10-17"
  status: reviewed
---

# Braze implementation QA

Makes a Braze implementation provable: the right person reaches the right profile, enters the right Canvas once, is rechecked before each consequential message, and is suppressed for a reason someone can name. The outputs are an identity contract, a trigger contract per Canvas, a Canvas control sheet, a synthetic test plan with evidence, and for incidents a diagnosis that names the first failing gate.

The rule: a send count, a Canvas entry or an HTTP 201 proves nothing about one customer. Release needs evidence for the intended sends and the intended suppressions.

## When to use

- Setting up Braze, adding an SDK platform, a backend sender, CDI or a reverse ETL sync.
- A Canvas sends to nobody, to the wrong people, twice, or after someone completed, cancelled or unsubscribed.
- Users entered a Canvas but received nothing, or one named user did not get an email, push or SMS.
- `/users/track` returns `errors`, 400s or 429s, or duplicate anonymous and known profiles appear.
- A launch review or a request for a Braze QA checklist or Canvas test plan.

Use something else when (most are planned skills; the fallback applies when one is not installed):

- The journey is not specified yet: journey-spec-and-qa. Fallback: collect the journey spec fields under Inputs and continue.
- List segments, nested array attributes or phone numbers through the REST API: braze-api-segments-and-attributes. Fallback: the ownership rule in identity-and-ingestion.md, payload shapes read live.
- Preference centres or caps that span several senders: preferences-caps-and-suppression. Fallback: record this workspace's controls and flag the cross-sender gap.
- Warehouse to Braze sync contracts: reverse-etl-and-audiences. Fallback: apply step 2 to the sync.
- Connecting the Braze MCP server: marketing-mcp-setup. Fallback: Braze's MCP setup page in `sources.yaml`.
- Any write through MCP or the API: agent-write-safety.
- Measuring lift with holdouts: incrementality-test-design. Fallback: record control group settings only.
- Deliverability (domain authentication, IP warming, inbox placement) belongs to the email delivery owner.

## Inputs

Read first if they exist:

- `martech-context/stack.md`: workspaces, REST cluster, SDK platforms and versions, every system that writes to Braze, owners.
- `martech-context/tracking-plan/`: event contracts for every Canvas trigger and exit event.
- `martech-context/data-dictionary.md`: which system owns each custom attribute.
- `martech-context/decisions.md`: consent basis, cap policy, control group decisions.

Then gather:

- The journey spec: outcome, unit (person, account or object such as an order), entry, every stop reason, re-entry policy, channels, delays.
- Every write path into Braze: SDKs with versions, backend `/users/track` senders, CDI, reverse ETL, CSV imports, partner integrations. For each: identifier used, event names, attributes written.
- Canvas configuration. The MCP Canvas tools and `GET /canvas/details` return metadata, step structure and message content only. Entry audience, entry controls, exit criteria, delays, delivery validations and send settings are read in the dashboard.
- Workspace settings: frequency capping rules, quiet hours, Global Control Group percentage and exclusion tags, subscription groups.
- A test workspace with its own API key (Braze recommends separate environments), or written approval to run a restricted duplicate Canvas in production after the containment checklist in the test plan reference.
- For an incident: the affected test profile's external_id, expected versus observed behaviour, timestamps with timezone, and whether one person or many are affected.

Access rules:

- Diagnosis reads use a REST key created with read permissions only (for example `users.export.ids`, `canvas.details`, `canvas.data_series`; names checked 2026-10-17, verify live). Test writes use a separate key created in the test workspace only. Braze key permissions cannot be edited after creation.
- Keys stay in the user's environment. The agent drafts each call and the user runs it, or the agent reads the key from an environment variable without printing it. Only the named fields come back into the conversation.
- For real customers, `fields_to_export` never includes email or phone. The user looks up the profile and reports states and timestamps, not contact details.

Outputs are proposed, then written after approval: identity contract to `data-dictionary.md`; trigger contract, control sheet and test plan to `tracking-plan/<journey>.md`; cap, control group, consent and accepted-risk decisions to `decisions.md`.

## Procedure

Pick the mode first:

- Incident (missing, unwanted or doubled message): go to step 8 now and capture perishable evidence in the first reply. Deliverable: diagnosis report.
- Launch review of one Canvas: steps 3 to 7, plus 1 and 2 if any write path changed since the last review. Deliverable: control sheet and test plan with results.
- New implementation: steps 1 to 7. Deliverable: identity contract, trigger contracts, control sheets, test plan.

### 1. Write the identity contract

- One external_id per person, identical in SDKs, backend and imports. Braze recommends random UUIDs and advises against email addresses, usernames, visible profile IDs and incrementing numbers.
- Call `changeUser` when the user logs in or is otherwise identified, on every platform. Never call it at logout and never assign a shared default ID.
- Logout uses `logout()` or `unregisterPush()` where the SDK version supports them. A successful `logout()` disables the SDK: turn it back on before the next login (`enableSDK()` then `initialize()` on Web, `enableSDK()` on Android, `enabled = true` on Swift) and re-register push. Never call either straight after push registration.
- Build the identity specimen (anonymous use, signup, second device, logout, shared-device switch, reinstall, backend-first profile) with every test profile and device in an internal group with User Events recording on. Braze documents that a backend-first profile loses the SDK's anonymous pre-signup data.
- `/users/identify` attaches aliases; `/users/merge` combines duplicates, removes the source and has no documented undo: draft it and stop for approval.

Detail and the specimen: [references/identity-and-ingestion.md](references/identity-and-ingestion.md).

### 2. Make every write observable

- `/users/track` can return `"message": "success"` with an `errors` array while processing the other objects. Each sender logs every object-level rejection (source record ID, identifier type, payload version, attempt time, code). Request-level `request_status_*` and `invalid_group_id` entries are not rejections. No raw personal data in general logs.
- On 429, wait the seconds in `X-RateLimit-Retry-After`. Braze documents `X-RateLimit-Reset` both as epoch seconds and as seconds remaining, so when only it is present, read a value under 1,000,000,000 as seconds remaining and a larger one as epoch time. Cap retries.
- A 5xx or timeout is an unknown outcome. Braze stores every event object as a new event, so check the business key ledger (and `group_id` status, if used) before retrying events and purchases.
- Requests are processed asynchronously and not in guaranteed order: send an attribute and the event that depends on it in one request.
- An omitted `_update_existing_only` creates a profile for an unknown external_id, so a malformed ID creates an orphan instead of an error.
- Read back a sample with `/users/export/ids`, not a warehouse copy, which can lag.

### 3. Choose one authoritative trigger per Canvas

- Both entry types pass the triggering data as context, so per-event data does not decide. API-triggered (`/canvas/trigger/send`) when the profile may not exist yet, the producer must dedupe by business key, or the event is not otherwise needed in Braze. Pass the business key in `context` and keep a sender ledger keyed on business key plus Canvas.
- Action-based when the event is already logged for segmentation and marketing must change the trigger without a release.
- An API trigger leaves no event on the profile; if the producer also logs it for segments or exits, never wire that event as an action trigger too.
- Known traps: `send_to_existing_only` defaults to true; a paused Canvas can return 201 with a `notice`; the dashboard entry audience still applies to API triggers; an entry audience filtered on the trigger's own data can race it; backdated timestamps make delays fire early; a backfill using the live event name enters live Canvases.

Detail: [references/canvas-entry-exit-and-eligibility.md](references/canvas-entry-exit-and-eligibility.md).

### 4. Set entry, exit and re-eligibility from the journey unit

- Once ever per person: re-entry off. Entry without a message still uses up eligibility.
- Once per object: re-entry on, each exit event matched to its entry on the object ID with "Personalize value", so finishing order A does not stop order B.
- Cooling period per person: re-eligibility window at least as long as the longest path through the Canvas.
- "Limit entrance volume": expected daily entries from the producer ledger plus a stated margin, with an alert when hit. Verify live whether excess entries are dropped; if so, record dropped business keys for a deliberate re-trigger.
- One exception event per stop reason. Exit segments are evaluated when a step completes, so time-critical stops use exception events.

### 5. Recheck eligibility after every wait

- A Message step advances the user when the message is sent, capped, aborted, unreachable or fails validation. Every later message must make sense if the earlier one never arrived.
- Before each consequential message after a delay: "Validate audience at message send" with an explicit exit-or-advance choice, Audience Paths or a Decision Split.
- Per-object journeys need object-scoped rechecks: matched exits, or a send-time lookup keyed on the context object ID (Catalog or Connected Content with `abort_message`). Never a profile attribute that several objects overwrite.
- Freshness rule: a field used in a recheck must update faster than the shortest delay before it.
- Delay traps: a personalised date already in the past exits the user; a profile without a timezone falls back to company time.

### 6. Record the delivery controls and their failure signatures

- Frequency caps: calendar days in the user's timezone, most restrictive rule wins, in-app messages and Content Cards neither count nor get capped. A capped Canvas step advances the user.
- Subscriptions: email "subscribed" is the default, not evidence of opt-in. SMS, WhatsApp and LINE need a subscription group. Check for anything sending to unsubscribed users.
- Quiet hours: per Canvas abort or "Send at next available time". Workspace quiet hours (early access) abort API-triggered and API campaigns by default; the default for API-triggered Canvases is not documented, so read the Canvas's own setting.
- Global Control Group: only API campaigns and tag exclusions bypass it, not API-triggered campaigns or Canvases. A percentage change reshuffles irreversibly; Braze advises at most monthly.
- Rate limiting: capped users are not replaced; messages delayed 72 hours or more are aborted.

Detail: [references/delivery-controls.md](references/delivery-controls.md).

### 7. Run the synthetic test plan before launch

- Copy [assets/canvas-test-plan.yaml](assets/canvas-test-plan.yaml). Every fixture states an expected send or suppression and the evidence that proves it. One profile and one email address per fixture.
- Run in the test workspace. A duplicated Canvas in production needs the containment checklist first; the test workspace is mandatory when another live journey shares a fixture event as trigger or exit and fixtures could enter it.
- "Test Canvas" previews admit ineligible users, so they prove branch logic and content only. Braze's docs conflict on whether Context steps run there.
- Fixture writes are drafted (see [assets/example-acme-users-track.json](assets/example-acme-users-track.json)), approved, and run against test profiles with current timestamps.
- Treat an edit to a live Canvas as a release: save a version, retest one in-flight user and one new entrant.

Fixtures, containment, change control and a worked Acme run: [references/synthetic-test-plan.md](references/synthetic-test-plan.md).

### 8. Diagnose a missing or unwanted message in order

Capture perishable evidence first: the Message Activity Log keeps 60 hours, `group_id` status 24 hours, the Event User Log 30 days (internal group members with User Events on only; empty for anyone else proves nothing), Messaging History about 40 recent events.

If several people are affected, start with the population view: entries versus sends per step, then entry, exit, send and abort events by step from Currents, Snowflake Data Sharing or Query Builder.

Then walk the gates and stop at the first that fails: 1 source, 2 profile, 3 entry, 4 current eligibility, 5 permission, 6 reachability, 7 delivery controls, 8 outcome. Never fix by removing filters until the test arrives. Where to look for each: [references/missing-message-diagnosis.md](references/missing-message-diagnosis.md).

## Common failure modes

- `changeUser` at logout to a shared ID merges strangers until Braze blocks the profile. Detect: extreme session counts on a few profiles, `BLACKLISTED_EXTERNAL_USER_ID` errors.
- Logout without re-enabling the SDK. Detect: on a shared device, the second user's events and push token never reach their profile.
- A batch logged as sent while `errors` rejected objects. Detect: accepted count below sent count.
- Browser and backend both send the trigger. Detect: the same event from SDK and API seconds apart in the Event User Log, or entries above the producer ledger count.
- Re-eligibility shorter than the Canvas. Detect: `last_entered` moves while the earlier entry is still mid-path.
- A profile-level flag used for object-level state. Detect: fixture F11 fails.
- Stale warehouse field as the recheck. Detect: the freshness rule fails; validation exits cluster after each sync.
- "Day 2" copy that assumes the capped "day 1" arrived. Detect: cap or abort events on the earlier step for users who got the later one.
- Every profile synced as "subscribed" by an integration. Detect: a group near 100% subscribed with a single writer.

## Worked example

Fictional: Acme reminds a workspace admin 24 hours after workspace creation if the first import has not succeeded. Unit: workspace. Entry: API-triggered by the import service with `workspace_id` in `context`. Exits: `first_import_succeeded` and `workspace_cancelled`, matched on `workspace_id`. Send-time recheck per workspace: a Connected Content lookup of that workspace's import state, aborting when it succeeded. No profile attribute, because one admin can have several workspaces.

The synthetic run in a duplicated Canvas (delay shortened to 3 minutes, containment checked) passed the happy path, completion during the delay, cap, quiet hours and partial API failure fixtures. It failed two: a retried trigger entered twice because the import service kept no ledger, and completing one workspace exited the admin's other workspace journey because the exit filter was not set to "Personalize value". Fixes went out as drafts with owners; the plan stays "not ready" until F9, F11 and the regression fixtures pass. Full run: [references/synthetic-test-plan.md](references/synthetic-test-plan.md).

## Acceptance checks

- Identity: every specimen transition lands on the expected profile, checked with Search Users or `/users/export/ids`. Pass: no shared IDs; after logout the SDK is re-enabled and the next user's push token sits on their profile; merge behaviour recorded per platform.
- Ingestion: a seeded invalid object appears in the sender's error log with its code while the others land. Pass: rejected plus accepted objects equal sent objects, counting object-level codes only, with field-level drops counted separately if the seeded test showed them.
- Rate limits: Pass: a unit or integration test against stubbed 429 responses, with and without `X-RateLimit-Retry-After`, plus code review showing waits and capped retries. No load test against Braze.
- Trigger: one producer per Canvas trigger. Pass: a duplicated business event, including a retry after a simulated timeout, produces one entry.
- Canvas sheet: unit, re-eligibility, entrance limit, exit per stop reason and send-time recheck recorded per Canvas. Pass: every consequential message after a delay has a recheck scoped to the journey unit.
- Synthetic plan: Pass only when every executed fixture passes with evidence (`last_entered`, `last_exited`, `steps_received`, Messaging History) and every not-exercised fixture has a reason. An open failure blocks launch unless a named release owner accepts it in writing with a compensating control recorded in `decisions.md`.
- Controls: caps, quiet hours, Global Control Group, subscription settings recorded with values and the date checked.
- Diagnosis: the report names the first failing gate, its evidence, pass evidence for every gate above it, and for population cases the step-level counts.

## Boundaries

- Read-only by default. Creating or updating profiles, triggering Canvases, changing Canvas or workspace settings, subscription changes, identify, merge, rename and Global Control Group changes are drafts that stop for human approval. Merges and control group reshuffles cannot be undone.
- Never generate load against Braze endpoints. On MAU pricing, burst limits are shared across every workspace, so a test workspace can throttle production.
- No credentials, no customer personal data, test profiles for all tests.
- Hand-offs:
  - Braze remote MCP server (OAuth, dashboard permissions). Canvas tools are read-only and return metadata, step structure, message content and aggregates, with no profile data. Operator Connect (beta) edits Canvases with no step approval; keep it out of a QA pass. See [references/braze-mcp-handoff.md](references/braze-mcp-handoff.md).
  - SDK changes to the app engineers, with the specimen results.
  - Consent basis and wording to the owner of the approved consent policy.
  - Deliverability to the email delivery owner.

## Live docs

Platform settings, limits and menu paths change. Before stating any parameter name, limit, quota or UI path:

- Fetch the current page from the vendor docs MCP server or llms.txt listed in `sources.yaml`, or open the canonical URL.
- If the live page disagrees with this skill, follow the live page and tell the user what changed.
- Cite the URL you used.

Most important `sources.yaml` entries: `/users/track`, `/canvas/trigger/send`, API limits and keys, `/users/export/ids`; data collection (logout); internal groups; Canvas, exit, re-eligibility and Delay step pages; caps, workspace quiet hours, subscriptions, Global Control Group; MCP pages. Context7 index: `/websites/braze`. `llms.txt` exists per docs section; the root `/docs/llms.txt` returned 404 on 2026-10-17.
