stitch

Migrating to Braze from Salesforce Marketing Cloud, Klaviyo or HubSpot

By the Stitch team · · 9 min read

Key takeaways

  • Consent is the highest-risk item. Map every opt-in and opt-out from the old platform to Braze global subscription states and subscription groups before importing anyone.
  • Choose your import route by job: CSV for one-off loads, /users/track for API loads and push tokens, Cloud Data Ingestion for ongoing warehouse syncs.
  • Journeys don't transfer. SFMC Journey Builder journeys, Klaviyo flows and HubSpot workflows all need to be rebuilt as Braze Canvases.
  • Plan a parallel-run period. New IPs need warming, and Braze calls warming required.
  • Decide early what history you actually need. Most teams need far less than they think.

What moves to Braze, and what doesn't?

ItemMoves?How
User profiles and attributesYesCSV import, API or Cloud Data Ingestion
Email and SMS consentYes, with mappingSubscription states and subscription groups
Mobile push tokensMostlyAPI import or automatic SDK capture
Web push tokensNoRe-permission users
Historical events and purchasesSelectivelyCSV (custom events) or API
TemplatesRebuildHTML can be reused, logic rewritten in Liquid
Journeys and automationsRebuildCanvas
IP and domain reputationNoWarm new IPs

A few of these deserve detail. Braze CSV import doesn't support arrays, push tokens or custom event data types in user import, so tokens go through the API. For mobile push, Braze notes that tokens for opted-in users are migrated automatically the next time they open your app once the SDK is live, and you can import them earlier through /users/track. Web push tokens can't be migrated through the API, so budget for a re-permission prompt.

Templates are the other surprise. Your HTML and design system can come across, but personalisation logic from the old platform has to be rewritten in Liquid, which Braze supports up to Liquid 5 but not in full. Move shared headers, footers and offer codes into Content Blocks as you go.

How do you import users into Braze?

Braze supports four main routes: Braze CSV import, a Lambda-based CSV import from S3, the /users/track REST endpoint, and Cloud Data Ingestion.

  • CSV import suits one-off backfills. Attribute files can be up to 500 MB and custom event files up to 50 MB. Each file must use one identifier type: external_id, braze_id, a user alias, email or phone. You can't mix external_id and aliases in one file.
  • The REST API suits engineering-led loads and anything CSV doesn't support, such as push tokens.
  • Cloud Data Ingestion suits teams with a warehouse. It syncs attributes (including subscription statuses), events, purchases and catalogs from Snowflake, BigQuery, Redshift, Databricks or Microsoft Fabric. If your warehouse is the source of truth, this is usually the cleanest migration path because the same pipeline keeps running after cutover.

Whatever the route, settle your external_id first. Braze recommends UUIDs and advises against using email addresses as user IDs. Old platform IDs can be kept as user aliases for reconciliation.

How do you map consent and subscription groups?

Braze has two layers. For email, global subscription states are opted_in, subscribed (neither opted in nor out) and unsubscribed, set through the email_subscribe field. Underneath sit subscription groups for categories such as newsletters or promotions. Changing a group doesn't change the global state.

For SMS, users must be in an SMS subscription group to receive messages, and each user is subscribed or unsubscribed per group. In a CSV import you set subscription_group_id and subscription_state, and only one group per row, so multi-group users need one import per group.

Practical rules:

  • Map conservatively. If the old platform can't prove an opt-in, don't import it as opted_in.
  • Carry suppressions across as unsubscribes, not as missing records. A missing record can be re-imported later as subscribed.
  • Keep the consent source and date as custom attributes for audit.
  • Get privacy or legal sign-off on the mapping table before the first import.

What should you know about each source platform?

Salesforce Marketing Cloud

In Marketing Cloud Engagement, a data extension is "simply a table with fields of data about your contacts". Sendable data extensions map to a subscriber, while non-sendable ones hold reference data such as orders or product tables. In Braze, sendable data usually becomes profile attributes, and reference data often fits better as catalogs via Cloud Data Ingestion or as a Connected Content lookup. Journey Builder journeys start from entry sources such as data extensions or API events, so inventory those entry sources: each becomes a Canvas entry trigger or segment.

Klaviyo

A Klaviyo flow is "a sequence of automated actions (e.g., sending messages) triggered by a behavior or event", with triggers including lists, segments, metrics, date properties, price drops and low inventory. Metric-triggered flows map naturally to action-based Canvases. Price drop and low inventory triggers depend on product-level data, so plan how that data reaches Braze. Klaviyo also records why a profile can't receive email marketing, such as unsubscribed, manual suppression, invalid email or hard bounce. Keep those reasons when you map to Braze.

HubSpot

HubSpot uses subscription types for categories of marketing email, and can require both an opted-in status and a legal basis to send. Subscription types map well to Braze email subscription groups. HubSpot workflows enrol records through filter, event, schedule or webhook triggers, which you'll rebuild as Canvas entry rules.

How should you handle email domains and IP warming?

Treat the email channel as new. Braze's setup starts with delegating a sending subdomain, after which Braze manages SPF and DKIM, and you should set DMARC on the root domain. Then warm the IPs. Braze calls warming required, and its conservative schedule is recommended for senders migrating from a shared IP. Start with your most engaged users and build to average daily volume.

Should you run both platforms in parallel?

Usually, yes, for a defined window. The old platform keeps carrying volume while Braze IPs warm, and you move journeys across one at a time. Rules that keep parallel running safe:

  • One platform owns each journey at any moment. Never let both send the same message.
  • Sync unsubscribes both ways during the overlap, ideally daily or faster.
  • Set an end date. Braze notes that reputation data is typically kept for about 30 days, so don't let new IPs sit idle while you wait.

What's a sensible migration sequence?

  1. Inventory: journeys, templates, data sources, consent fields, sending domains.
  2. Identity and consent mapping, signed off.
  3. SDK and data pipelines live, profiles and consent imported.
  4. Email domain delegated and IP warming started.
  5. Transactional and triggered journeys rebuilt and moved first.
  6. Marketing campaigns moved as warming volume allows.
  7. Old platform switched off, final suppression export kept.

A typical Stitch implementation runs 8 to 12 weeks. For a migration, plan for the longer end so the inventory and parallel run have room.

Migration risk checklist

  • Consent mapping documented and approved
  • Suppressions imported as unsubscribes
  • external_id agreed and old IDs stored as aliases
  • Push tokens imported with the correct app ID and environment
  • Web push re-permission planned
  • Liquid rewrites tested with missing-data fallbacks
  • IP warming schedule chosen and tracked
  • Unsubscribe sync running during parallel run
  • No journey live on both platforms
  • Contract end date for the old platform aligned with the plan

How Stitch can help

Stitch is an independent Auckland consultancy and Braze Alloys Solutions Partner (Orbit tier), named ANZ Rising Star of the Year at Braze's inaugural ANZ Partner Awards in 2026. We were appointed Braze onboarding partner by Skyline Enterprises in 2026, and as lead Braze partner for Serko AI we shipped a lifecycle layer to production in six weeks, including Cloud Data Ingestion from the warehouse and a dual sender architecture separating transactional and marketing email. We're also a Customer.io Gold Agency Partner, Segment Certified Partner and Hightouch Implementation Partner, so we're comfortable with the data plumbing either side of a migration.

FAQ

Can I migrate journeys from SFMC, Klaviyo or HubSpot into Braze automatically? No. Journeys, flows and workflows need to be rebuilt as Braze Canvases, though the logic and content can be reused.

How do I import email consent into Braze? Set email_subscribe to opted_in, subscribed or unsubscribed, and use subscription_group_id and subscription_state for subscription groups.

Can push tokens be migrated to Braze? Mobile tokens can be imported via the API or captured automatically when users open the updated app. Web push tokens can't be migrated through the API.

Do I need to warm new IPs when moving to Braze? Yes. Braze calls IP warming required, and recommends a conservative schedule when migrating from a shared IP.

How long does a migration to Braze take? Stitch's typical Braze implementation is 8 to 12 weeks. For a migration, plan for the longer end to allow for inventory and a parallel run.

Sources

Talk to a Braze partner

Talk to a Braze partner Get in touch

More on Braze

Let's connect the dots.
Get in touch.

Get in touch Book a 30-minute call

Or book a time that suits you. No pitch deck, no obligation.