Braze: Telltide Seed Address Guide

Braze separates seed management into two distinct paths: the native Seed Group feature for Campaigns, and full user profile creation for Canvas monitoring. Understanding which path applies to your send type is the first decision to make before placing any seed address.

Quick reference

---

1. Scheduled or one-off sends (Campaigns)

Braze Campaigns are single-message or multi-variant sends. They support three delivery modes: Scheduled, Action-Based, and API-Triggered.

Where to add seed addresses

Braze has a native seed list system called Internal Groups. A Seed Group type Internal Group receives a copy of every email sent from any Campaign where that group is enabled. Seed addresses in the group do not need to be Braze user profiles.

Non-technical path

For CRM managers without API access. All work happens in the Braze dashboard.

Create the Seed Group:

1. Navigate to Settings > Workspace Settings > Internal Groups.
2. Click Create Internal Group.
3. Name the group (for example, "Telltide Seeds Production").
4. Set Group Type to Seed Group.
5. Add the seed email addresses to the group.
6. Click Save.

Enable the Seed Group on a Campaign:

1. Open the Campaign in the Campaign editor.
2. Navigate to the Target Users step.
3. Scroll to the Seed Groups section.
4. Select your seed group from the dropdown.
5. Save the Campaign.

On send, Braze delivers a copy of the email to every address in the Seed Group.

Technical path

For teams that prefer to manage seeds programmatically alongside their other CRM tooling. Seed Groups themselves are still managed through the dashboard, but you can confirm seed coverage by listing Internal Groups via the API or by adding the seed as an external_id recipient in API-Triggered Campaigns (see Section 2 for the user profile setup).

Profile attributes required

Seed Groups accept raw email addresses, no Braze user profile is needed. Seeds in a Seed Group receive the rendered email exactly as it would appear to a real recipient, using the Campaign's message content with any merge tags resolved using test data or left blank.

Ensuring seeds receive the same version as real recipients

A/B and multivariate tests: Seeds in a Seed Group receive a copy of every variant being sent, not just the winning variant. This is the correct behavior for monitoring; you confirm all variants are delivered and rendered without errors.

Experiment Paths in Canvas: Seed Groups are not available for Canvas. For Canvas experiment monitoring, use a proper user profile (see Section 2).

Gotchas

API-Triggered Campaigns: Seed Groups are not supported for API-Triggered Campaigns where the API call specifies the recipient list. To seed an API-triggered Campaign, include the seed address as an explicit recipient in the API call:

{
  "campaign_id": "{{campaign_id}}",
  "recipients": [
    { "external_user_id": "real_user_001" },
    { "external_user_id": "seed_monitor_001" }
  ]
}

Global Control Group: If any seed user profile is randomly assigned to the Braze Global Control Group, it will be excluded from all Canvases and Campaigns unless those sends are tagged to bypass the control group check. Seed Groups bypass this because they are not standard recipients; they receive a side copy of the email.

---

2. Ongoing or automated journeys (Canvas)

Canvas is Braze's multi-step journey builder. Monitoring a Canvas requires a proper Braze user profile that enters the Canvas through the configured entry source. Both Canvas Flow and Classic Canvas use the same user profile and entry primitives.

How to create trap profiles

Seed profiles must be real Braze user profiles with external_id values, correct subscription status, and all attributes needed to satisfy the Canvas entry segment.

Non-technical path

For CRM managers placing seeds without API access.

Option A: Create a profile through the dashboard.

1. Navigate to Audience > User Search.
2. Click Create User.
3. Enter the seed external_id, email address, and any attributes required by the Canvas entry segment.
4. Set Email Subscribe to Opted In.
5. Save.

Option B: CSV import.

1. Navigate to Audience > Import Users.
2. Upload a CSV with columns: external_id, email, email_subscribe, and any custom attributes used by the Canvas entry segment.
3. Confirm field mapping.
4. Complete the import.

Option C: Segment Extension manual add. If the Canvas entry segment is built on a Segment Extension, add seed users directly to the extension from the Segment Extension editor. Seeds become eligible for Canvas entry on the next segment refresh.

Technical path

Create or update a seed profile via API. The request body has separate attributes, events, and purchases arrays; each object must include at least one identifier (external_id, user_alias, braze_id, email, or phone).

POST https://rest.{{instance}}.braze.com/users/track
Authorization: Bearer {{rest_api_key}}
Content-Type: application/json

{
  "attributes": [
    {
      "external_id": "seed-monitor-001",
      "email": "seed@example.com",
      "email_subscribe": "opted_in",
      "first_name": "Seed",
      "last_name": "Monitor",
      "country": "US",
      "internal_test_user": true
    }
  ]
}

Key fields:

• external_id: Permanent unique identifier. Choose a stable value; it cannot be changed later without an alias-to-id swap.
• email_subscribe: Must be "opted_in" or "subscribed". Do not use "unsubscribed"; Braze will not send email to unsubscribed profiles.
• internal_test_user: A custom attribute set to true; lets you build a segment to manage and exclude seeds.

Each /users/track request may batch up to 75 updates combined across attributes, events, and purchases objects. Hourly request limits are dynamic per workspace and visible under Settings > APIs and Identifiers > API Usage Dashboard.

Always-on flow coverage

For Canvases and Campaigns that run continuously rather than as one-off sends, the seed must satisfy the entry conditions every time the flow evaluates. There are three primitives to align: Canvas or Campaign entry, Segment membership, and Subscription Group status.

Canvases with Segment entry (Scheduled or Audience-Triggered):

The seed profile must be a member of the Canvas entry Segment at the moment the Canvas evaluates membership. Confirm by:

1. Locating the seed profile under Audience > User Search.
2. Reviewing the Segments tab on the profile and confirming the entry Segment is listed.
3. If the Segment uses recency or behavioral filters that the seed cannot satisfy passively (for example, "Last used app more than 30 days ago"), build a parallel entry Segment that explicitly includes seeds via the internal_test_user attribute and use it alongside the production Segment.

Canvases with Action-Based entry:

Log the triggering custom event against the seed profile. The event must match the Canvas trigger event name and any property filters configured on the entry step.

POST https://rest.{{instance}}.braze.com/users/track
Authorization: Bearer {{rest_api_key}}
Content-Type: application/json

{
  "events": [
    {
      "external_id": "seed-monitor-001",
      "name": "abandoned_cart",
      "time": "2026-04-15T10:00:00Z",
      "properties": {
        "product_name": "Widget Pro",
        "cart_value": 49.99
      }
    }
  ]
}

API-Triggered Canvases:

Pass the seed external_id into /canvas/trigger/send. The recipients array accepts up to 50 objects per request.

POST https://rest.{{instance}}.braze.com/canvas/trigger/send
Authorization: Bearer {{rest_api_key}}
Content-Type: application/json

{
  "canvas_id": "{{canvas_id}}",
  "recipients": [
    {
      "external_user_id": "seed-monitor-001",
      "canvas_entry_properties": {
        "product_name": "Widget Pro",
        "cart_value": 49.99
      }
    }
  ],
  "broadcast": false
}

API-Triggered Campaigns broadcast to a Segment: When the Campaign uses broadcast: true against a target Segment configured in the dashboard, ensure the seed profile is a member of that Segment. The intersection of recipients and the Segment is sent, so to guarantee delivery to the seed without affecting real recipients, omit broadcast and pass the seed plus your real list as recipients:

POST https://rest.{{instance}}.braze.com/campaigns/trigger/send
Authorization: Bearer {{rest_api_key}}
Content-Type: application/json

{
  "campaign_id": "{{campaign_id}}",
  "recipients": [
    { "external_user_id": "seed-monitor-001" }
  ]
}

The canvas_id and campaign_id are visible in the URL of the Canvas or Campaign editor, or retrievable via the Canvas List and Campaign List APIs.

Subscription Group coverage: If any Canvas or Campaign email step targets a specific Subscription Group, the seed must be subscribed to that group. Use the V2 endpoint to update one or more groups in a single call:

POST https://rest.{{instance}}.braze.com/v2/subscription/status/set
Authorization: Bearer {{rest_api_key}}
Content-Type: application/json

{
  "subscription_groups": [
    {
      "subscription_group_id": "{{group_id}}",
      "subscription_state": "subscribed",
      "external_id": ["seed-monitor-001"]
    }
  ]
}

The V1 endpoint at /subscription/status/set is still supported and uses subscription_state (not subscription_status) with a single subscription_group_id per request.

---

Profile requirements per journey type

Welcome or onboarding

• Entry trigger: First session, account creation event, or custom event.
• Seed requirements: email, email_subscribe: "opted_in", any attributes used by the entry Segment.
• How to trigger entry: Log the triggering custom event via /users/track. If triggered by first session (app SDK install), configure the Canvas to accept an API-triggered delivery mode or use a custom equivalent event instead.
• Entry limit: Set to once per user; seed can only enter once. Use a new external_id for repeat monitoring cycles.

Abandoned cart

• Entry trigger: Action-based, triggered by a custom event (for example, abandoned_cart or braze_ec_cart_abandoned).
• Seed requirements: email, email_subscribe: "opted_in", event fired with product data properties.
• Event data structure:

{
  "external_id": "seed-monitor-001",
  "name": "abandoned_cart",
  "time": "2026-04-15T10:00:00Z",
  "properties": {
    "product_id": "SKU-123",
    "product_name": "Widget Pro",
    "price": 49.99,
    "quantity": 1,
    "image_url": "https://example.com/img/widget.jpg"
  }
}

• Gotcha: The email's Liquid personalization reads from {{canvas_entry_properties.${key}}}. Event properties must match the exact key names used in the email template.

Winback or re-engagement

• Entry trigger: Scheduled Canvas targeting a Segment of lapsed users.
• Seed requirements: email, email_subscribe: "opted_in", last_used_app or equivalent recency attribute set to a date older than the lapse threshold.
• How to set up: Set a custom attribute like last_purchase_date to a value that satisfies the "lapsed" condition:

{
  "attributes": [{
    "external_id": "seed-monitor-001",
    "last_purchase_date": "2025-12-01T00:00:00Z"
  }]
}

• Gotcha: If the Canvas entry Segment uses Braze's built-in recency filters (for example, "Last used app more than 30 days ago"), the seed profile must have an actual session or app usage record old enough to qualify. Consider building a parallel entry Segment that includes seeds explicitly.

Post-purchase

• Entry trigger: API-triggered or action-based on a purchase event.
• Seed requirements: email, email_subscribe: "opted_in", order data in canvas_entry_properties.
• How to trigger: Use /canvas/trigger/send with order details in canvas_entry_properties:

{
  "canvas_id": "{{canvas_id}}",
  "recipients": [{
    "external_user_id": "seed-monitor-001",
    "canvas_entry_properties": {
      "order_id": "TEST-ORD-001",
      "order_total": 149.99,
      "product_name": "Widget Pro"
    }
  }]
}

Birthday or anniversary

• Entry trigger: Scheduled Canvas targeting a Segment where the birthday attribute matches today.
• Seed requirements: email, email_subscribe: "opted_in", date_of_birth custom attribute set to a date where the month and day match today.
• How to set up: Set date_of_birth on the seed profile to a historical date with the same month and day as your test date.

---

Ensuring seeds progress through the full Canvas

Subscription Group requirements: If any Canvas email step targets a specific Subscription Group, the seed must be subscribed to that group via /v2/subscription/status/set or /subscription/status/set (see "Always-on flow coverage" above).

Frequency capping: Braze applies workspace-level frequency caps to Canvas steps. If the seed profile has recently received emails (within the capped window), the Canvas step will be skipped. Disable frequency capping per Canvas step:

1. Open the Canvas email step.
2. Click the gear icon on the step.
3. Toggle Frequency Capping to off.

Global Control Group: Check whether the seed profile is in the Global Control Group. Navigate to the seed's user profile in the dashboard and check the Engagement section for a Global Control Group indicator. If the seed is in the GCG, tag the Canvas to bypass the GCG check, or disable the GCG entirely for testing.

Decision Splits and Audience Paths: Review every split in the Canvas. Ensure the seed profile's attributes satisfy the conditions needed to take the path that leads to the email step you are monitoring.

---

How to reset seeds for repeated testing

Option A: Use a new external_id per monitoring cycle. Create seed-monitor-001-cycle1, seed-monitor-001-cycle2, and so on. Route all to the same seed inbox. Old profiles accumulate but the Canvas sees them as new entrants.

Option B: Configure Canvas re-entry. In Canvas entry settings, enable "Re-entry after exit" or "Re-entry anytime." Seeds that complete or exit the Canvas can re-enter on the next monitoring cycle.

Option C: Use exit criteria to eject the seed mid-journey. Set a custom attribute (for example, force_exit: true) on the seed profile. Define that attribute as Canvas exit criteria. Update the attribute via API to eject the seed at any point, then reset it for the next cycle.

Option D: Delete and recreate the profile. Use POST /users/delete to permanently remove the seed profile, then create a new one. This guarantees a clean re-entry but is irreversible.

---

3. Platform-specific considerations

API options

/users/track, create or update user profiles:

• POST https://rest.{{instance}}.braze.com/users/track
• Up to 75 objects per request, combined across attributes, events, and purchases.
• Hourly rate limit is dynamic per workspace; check Settings > APIs and Identifiers > API Usage Dashboard.
• Each request object must include at least one identifier: external_id, user_alias, braze_id, email, or phone.

/users/identify, merge an alias-only user into a known external_id:

• POST https://rest.{{instance}}.braze.com/users/identify
• Use when seeds were first created via SDK alias and need to be promoted to a permanent external_id.

/users/export/segment, export profiles in a Segment:

• POST https://rest.{{instance}}.braze.com/users/export/segment
• Useful for confirming seeds appear in the production entry Segment before relying on Canvas entry.

/canvas/trigger/send, inject users into API-triggered Canvases:

• POST https://rest.{{instance}}.braze.com/canvas/trigger/send
• Up to 50 recipients per request.
• 250 requests per minute when using Connected Audience filters; otherwise default 250,000 per hour with external_id.

/campaigns/trigger/send, inject users into API-triggered Campaigns:

• POST https://rest.{{instance}}.braze.com/campaigns/trigger/send
• Up to 50 recipients per request.
• Same rate limits as /canvas/trigger/send.

/v2/subscription/status/set, set subscription group status in batch:

• POST https://rest.{{instance}}.braze.com/v2/subscription/status/set
• Required when Canvas or Campaign steps target specific Subscription Groups.
• 5,000 requests per minute shared with V1.

/users/delete, delete a profile permanently:

• POST https://rest.{{instance}}.braze.com/users/delete
• Only use when you need a clean slate for re-entry testing.

Rate limits

Duplicate user handling

external_id is the permanent unique identifier. Sending /users/track with an existing external_id updates the profile; no duplicate is created. Sending with a new external_id creates a new profile. You cannot have two profiles with the same external_id.

Multiple profiles can share the same email address if they have different external_id values. The same seed inbox will receive one email per profile. Use this intentionally for monitoring multiple Canvas variants, but track which external_id maps to which seed inbox to avoid confusion.

Platform-specific terminology

Known limitations and workarounds

No API to remove a user from an active Canvas: Once a user has entered a Canvas, there is no endpoint to eject them mid-journey. Use exit criteria (attribute-based) or delete the profile to reset.

Seed Groups do not work for API-Triggered Campaigns: Include seeds explicitly as recipients in the API call instead.

Global Control Group membership is random and permanent: You cannot guarantee a specific user profile is excluded from the GCG. To protect seeds, use Seed Groups for Campaigns (which bypass GCG) and tag production Canvases to bypass the GCG check.

Frequency capping silently skips steps: There is no error notification when a Canvas step is skipped due to frequency capping. If a seed stops receiving emails mid-journey, frequency capping is the first thing to check.

API instance varies by account: The rest.iad-01.braze.com base URL is one US East cluster. Your account may use a different instance (iad-02, iad-03, iad-04, iad-05, iad-06, iad-08, eu-01, fra-01, au-01, and so on). Confirm your instance from the dashboard at Settings > APIs and Identifiers.