Skip to main content

Braze

info

The Braze integration allows Karla to provide your Braze account with triggers of any sort, like shipment notifications or claims.

Steps​

1. Open Braze & navigate to Settings​

Navigate to your Braze dashboard and click on the Settings icon in the top navigation bar.

2. Navigate to APIs and Identifiers​

In the Settings menu, select APIs and Identifiers from the sidebar.

3. Create REST API Key​

In the REST API Keys section, click on Create New API Key.

Name your API key "Karla Integration" for easy identification.

4. Assign Required Permissions​

When creating your API key, you must assign the following permissions:

Required Scopes​

  • users.track - Allows Karla to send custom events and user data to Braze
  • users.export.ids - Allows looking up user profiles by email to validate and match customers with delivery events
note

These two permissions are the minimum required for the integration to work. The users.track permission enables Karla to send custom event triggers to Braze, while users.export.ids allows checking user profiles by email address via the /users/export/ids endpoint.

5. Save and Copy the API Key​

Click Save to create your API key. Copy the generated REST API Key immediately, as it cannot be viewed again after you navigate away.

Important

Once you create a new REST API key, you cannot edit the scope of permissions or the whitelisted IPs. If you need to change the scope of a key, create a new key with the updated permissions and implement that key in place of the old one.

6. Set up the REST API Key in Karla​

In our portal, navigate to Settings > Integrations, and select Braze.

braze 1

Paste the REST API Key into the API Key field.

You'll also need to provide your Braze Instance URL (also called REST Endpoint). This can be found in the Braze dashboard under Settings > APIs and Identifiers. It will look like https://rest.fra-01.braze.eu or similar, depending on your cluster.

Click on Save.

Building Braze Canvas Workflows​

Our Braze integration will automatically create custom events prefixed with karla_ for all delivery journey events.

From there, you can create Canvas workflows relying on these events to configure your own email flows.

To cover the most important delivery journey events, we recommend first creating Canvas workflows for the following event groups:

  1. karla_shipment_in_transit
  2. karla_shipment_carrier_delay
  3. karla_shipment_damaged
  4. karla_shipment_out_for_delivery
  5. karla_shipment_delivered_all_events
  6. karla_shipment_not_picked_up_returned
  7. karla_shipment_failed_returned

By creating these 7 Canvas workflows you will be able to cover standard events happening for every order (karla_shipment_in_transit, karla_shipment_out_for_delivery), all delivered cases (karla_shipment_delivered_all_events) and the events that hopefully do not happen too often, but where it is most important to be proactive with your customers (karla_shipment_carrier_delay, karla_shipment_damaged, karla_shipment_not_picked_up_returned, karla_shipment_failed_returned).

Event Groups vs Webhook Refs

Braze uses namespaced event groups (like karla_shipment_delivered) while webhooks use ref patterns (like shipments/delivered/SUCCESSFULLY_DELIVERED). Event groups are business-friendly names that group multiple specific events for easier automation management.

For complete documentation, see: Events Reference

Creating a Canvas Workflow​

Step 1: Create New Canvas​

Navigate to Messaging > Canvas in the left sidebar, then click Create Canvas.

Step 2: Set Up Entry Schedule​

In the Entry Schedule section:

  1. Select Action-Based as the entry type
  2. Choose Perform Custom Event as the trigger
  3. Select the Karla custom event you want to trigger this Canvas (e.g., karla_shipment_delivered)
  4. Optionally add property filters to further segment which events trigger the Canvas
Canvas Entry Properties

When using action-based entry with custom events, you can access the event properties throughout your Canvas using {{canvas_entry_properties.${property_name}}} in your Liquid templates.

The available event properties are the same as documented in Event-specific Data (within event_data).

Step 3: Add Target Audience​

Configure your target audience filters. For shipment notifications, you typically want to include all users who trigger the custom event, but you can add additional filters as needed.

Step 4: Build Canvas Flow​

Add components to your Canvas:

  1. Message Step - Drag the Message component from the sidebar
  2. Select Email as the messaging channel
  3. Configure your email content with personalization using Liquid syntax
  4. Add additional steps like delays, decision splits, or action paths as needed

Step 5: Configure Message Content​

In your email Message step, you can use both canvas entry properties and user attributes for personalization:

{{canvas_entry_properties.${order_number}}}
{{canvas_entry_properties.${tracking_number}}}
{{canvas_entry_properties.${carrier_reference}}}
{{canvas_entry_properties.${estimated_delivery_date}}}

Step 6: Test and Launch​

  1. Use Braze's Preview & Test functionality to verify personalization
  2. Send test emails to ensure proper formatting
  3. Review the Canvas flow for logical errors
  4. When ready, click Launch Canvas

Inserting the tracking page link​

To include the tracking page link in your Braze transactional emails you should use Liquid personalization with order_number and zip_code properties, so that your customers always receive their personalized link:

For emails triggered through Braze:

Karla events​

Karla hosted tracking page
https://app.gokarla.io/track/slug?orderNumber={{canvas_entry_properties.${order_number}}}&zipCode={{canvas_entry_properties.${zip_code}}}&ref=karla
Embedded tracking page
https://yourshop.com/pages/tracking?orderNumber={{canvas_entry_properties.${order_number}}}&zipCode={{canvas_entry_properties.${zip_code}}}&ref=karla

Shipping Confirmation​

Triggered by external events from your shop system.

Karla hosted tracking page
https://app.gokarla.io/track/slug?orderNumber={{canvas_entry_properties.${order_number}}}&zipCode={{canvas_entry_properties.${shipping_zip}}}&ref=karla
Embedded tracking page
https://yourshop.com/pages/tracking?orderNumber={{canvas_entry_properties.${order_number}}}&zipCode={{canvas_entry_properties.${zip_code}}}&ref=karla
tip

A slug is your unique identifier that represents your shop within the Karla system. This is used to properly route tracking information and ensure that shipment data is associated with the correct merchant account.

Testing the Canvas workflows​

Once you've set up the Canvas workflows and the respective emails it is important you make sure that the integration is working as expected.

In the Message step, use the Preview & Test functionality to verify:

  1. All Liquid tags are rendering correctly
  2. Canvas entry properties are displaying expected values
  3. Email formatting appears correctly across devices
warning

You will see accurate customer information only after you have integrated your shop with Karla. The preview will show test data until real events are flowing. More on shop integrations

Putting the Canvas workflows live​

After you have tested your Canvas workflows, you can launch them upon the agreed go-live date.

warning

Make sure you have configured the proper sending settings and have disabled any frequency caps for transactional emails, so that all of your customers receive their shipping updates.

Event Groups​

Karla provides the following event groups to your Braze instance for building Canvas workflows. These are business-friendly groupings that make it easier to create targeted campaigns without dealing with individual event names.

Event Groups vs Webhook Patterns

Event groups are specifically designed for Braze integration and are different from webhook ref patterns:

  • Event Groups: Business-friendly names, prefixed by karla_ (e.g., karla_shipment_delivered)
  • Webhook Refs: Technical identifiers (e.g., shipments/delivered/SUCCESSFULLY_DELIVERED)

For complete documentation of all events, ref patterns, and event groups, see: Events Reference �

Common Use Cases​

Post-Delivery Review Request​

Event Group: karla_shipment_delivered Timing: 2-3 days after delivery (use Delay step) Content: Thank you message + review request

Pickup Reminder​

Event Group: karla_shipment_delivered_to_parcel_shop Timing: Immediate + daily reminders (use Delay and Decision Split steps) Content: Pickup location, hours, deadline

Delivery Issue Resolution​

Event Group: karla_shipment_delivery_failed Timing: Immediate Content: Failed reason, next steps, support link

Proactive Delay Communication​

Event Group: karla_shipment_carrier_delay Timing: As soon as delay detected Content: New ETA, apology, compensation if applicable

Best Practices​

1. Email Content Guidelines​

  • Be Specific: Reference the exact delivery status
  • Include CTAs: Add tracking links and next steps
  • Personalize: Use canvas entry properties and user attributes for personalization
  • Mobile-Optimize: Most tracking emails are read on mobile

2. Testing Recommendations​

  1. Test each event group Canvas separately
  2. Verify Liquid tags populate correctly using Preview & Test
  3. Check email rendering across devices
  4. Monitor delivery rates and engagement in Braze analytics

3. Canvas Flow Best Practices​

  • Use Delivery Validations in Message steps to ensure users still meet criteria at send time
  • Leverage Action Paths to branch based on user behavior after initial message
  • Add Delay steps for time-based follow-ups (e.g., pickup reminders)
  • Use Decision Splits to create different paths based on user attributes

Troubleshooting​

Events Not Triggering Canvas​

  1. Verify event group name matches exactly (case-sensitive)
  2. Check REST API key has users.track permission
  3. Confirm Canvas is launched (not in draft mode)
  4. Verify Entry Schedule is configured for action-based delivery
  5. Check that target audience filters aren't excluding users

Missing Data in Emails​

  1. Ensure all Liquid tags match canvas entry property names
  2. Check syntax: {{canvas_entry_properties.${property_name}}}
  3. Use Preview & Test with sample data to verify rendering
  4. Verify the custom event includes the expected properties

Canvas Entry Issues​

  1. Check if there's a race condition between audience filter and trigger event
  2. Verify users meet both the trigger event criteria AND audience filters
  3. Review Canvas analytics to see where users are exiting
  4. Ensure Delivery Validations aren't too restrictive

API Authentication Errors​

  1. Verify REST API key is active (not deleted or regenerated)
  2. Check that the correct REST endpoint URL is configured in Karla portal
  3. Confirm IP whitelist includes Karla's IPs (if IP whitelisting is enabled)
  4. Verify API key has required permissions: users.track, users.export.ids, events.list

Advanced Features​

Using Action Paths​

Action Paths allow you to split users based on actions they take or don't take during the Canvas journey:

  1. Add an Action Paths step after a Message component
  2. Configure the action you're waiting for (e.g., email open, custom event)
  3. Set a time window for the action
  4. Create different Message steps for each path (took action vs didn't)
Event Properties in Action Paths

When using Action Paths with custom events, you can access {{event_properties.${property_name}}} in the first Message step following the Action Paths component. For subsequent steps, use {{canvas_entry_properties.${property_name}}} instead.

Property Filtering​

When setting up your Canvas entry schedule, you can add property filters to further segment which events trigger the Canvas.

Intelligent Timing​

Enable Intelligent Timing in your Message steps to send emails at the optimal time for each user based on their engagement history with your emails.

Security Best Practices​

  • Rotate API keys periodically - Create a new key and update it in Karla before deleting the old one
  • Monitor API usage - Use Braze's Developer Console to monitor API calls and look for anomalies
  • Limit permissions - Only grant the minimum required scopes listed above

Support​