Skip to content

Creating an email with custom HTML

Email messages are great for delivering content to your users on their terms. They are also excellent tools to re-engage users who may have even uninstalled your app. Sending customized and tailored email messages will enhance your users’ experience, and help your users get the most value out of your app.

To see examples of email campaigns, check out our Case Studies.

Step 1: Choose where to build your message

Not sure whether your message should be sent using a campaign or a Canvas? Campaigns are better for single, simple messaging campaigns, while Canvases are better for multi-step user journeys.


  1. Go to Messaging > Campaigns and click + Create Campaign.
  1. Select Email, or, for campaigns targeting multiple channels, select Multichannel Campaign.
  2. Name your campaign something clear and meaningful.
  3. Add Teams and Tags as needed.
    • Tags make your campaigns easier to find and build reports out of. For example, when using the Report Builder, you can filter by particular tags.
  4. Add and name as many variants as you need for your campaign. For more on this topic, refer to Multivariate and A/B testing.


  1. Create your Canvas using the Canvas composer.
  2. After you’ve set up your Canvas, add a step in the Canvas builder. Name your step something clear and meaningful.
  3. Choose a step schedule and specify a delay as needed.
  4. Filter your Audience for this step, as necessary. You can further refine the recipients of this step by specifying segments and adding additional filters. Audience options will be checked after the delay, at the time messages are sent.
  5. Choose your advancement behavior.
  6. Choose any other messaging channels that you would like to pair with your message.

Step 2: Select your editing experience

Braze offers two editing experiences when creating an email campaign: our drag-and-drop editor and our standard HTML editor. Click on the appropriate tile to select which editing experience you’d prefer.

Choosing between drag-and-drop editor or HTML editor for your email editing experience.

Then, you can either select an existing email template, upload a template from a file (HTML editor only), or use a blank template.

Step 3: Compose your email

After you’ve selected your template, you’ll see an overview of your email where you can quickly jump to the fullscreen editor to draft your email, change your sending information, and view warnings about deliverability or law compliance.

Email Variants panel for composing your email.

Step 3a: Add your sending information

After you’ve finished designing and building your email message, it’s time to add your sending information in the Sending Settings section.

  1. Under Sending Info, select an email as the From Display Name + Address. You can also customize this by selecting Customize From Display Name + Address.
  2. Select an email as the Reply-To Address. You can also customize this by selecting Customize Reply-To Address.
  3. Next, select an email as the BCC Address to make your email visible to this address.
  4. Add a subject line to your email. Optionally, you can also add a preheader and a whitespace after the preheader.

A preview in the right-hand panel will populate with the sending information you’ve added. This information can also be updated by navigating to Settings > Email Preferences > Sending Configuration.


Under Sending Settings > Advanced, you can turn on inline CSS and add personalization for email headers and email extras, which allows you to send additional data back to other email service providers.

Email headers

To add email headers, select Add New Header. Email headers contain information about the email being sent. These key-value pairs typically have information about the sender, recipient, authentication protocols, and email routing information. Braze automatically adds the necessary header information required by the RFC for emails to be delivered to your inbox provider properly.

Braze allows you the flexibility to add additional email headers as needed for advanced use cases. There are a few reserved fields that the Braze platform will overwrite during sending.

Avoid using the following keys:

Reserved Fields
BCC dkim-signature Reply-To
CC From Subject
Content-Transfer-Encoding MIME-Version To
Content-Type Received x-sg-eid
DKIM-Signature received x-sg-id
Adding email extras

Email extras allows you to send additional data back to other email service providers. This is only applicable for advanced use cases, so you should only use email extras if your company already has this set up.

To add email extras, go to the Sending Info and click Add New Extra.

Email extra values are not published to Currents or Snowflake. If you’re looking to send additional metadata or dynamic values to Currents or Snowflake, use message_extras instead.

Step 3b: Preview and test your message

After you finish composing your perfect email, you need to test it before sending it out.

From the bottom of the overview screen, click Preview and Test. Here, you can preview how your email will appear in a customer’s inbox. With Preview as User selected, you can preview your email as a random user, select a specific user, or create a custom user. This allows you to test that your Connected Content and personalization calls are working as they should.

You can also switch between desktop, mobile, and plaintext views to get a sense of how your message will appear in different contexts.

When you’re ready for a final check, select Test Send and send a test message to yourself or a group of content testers to ensure that your email displays properly on a variety of devices and email clients.

Test Send option and example email preview when composing your email.

If you see any issues with your email, or want to make any changes, click Edit Email to return to the editor.

Step 3c: Check for email errors

The editor will call out any problems it catches with your message before you send it. Here’s a list of errors that are accounted for in our editor:

  • From Display Name and Header not specified together
  • Invalid From and Reply-To addresses
  • Duplicate Header keys
  • Liquid syntax problems
  • Email bodies larger than 400kb (bodies are highly recommended to be smaller than 102kb)
  • Emails with a blank Body or Subject
  • Emails without an unsubscribe link
  • Email you’re sending from is not allowlisted (sends will be highly limited to ensure deliverability)

Step 4: Build the remainder of your campaign or Canvas

Next, build the remainder of your campaign! See the following sections for further details on how to best utilize our tools to build your email campaign.

Choose delivery schedule or trigger

Emails can be delivered based on a scheduled time, an action, or based on an API trigger. For more, refer to Scheduling your campaign.

You can also set the campaign’s duration, specify Quiet Hours, and set frequency capping rules.

Choose users to target

Next, you need to target users by choosing segments or filters to narrow down your audience. You’ll automatically be given a snapshot of what that segment population looks like right now, including how many users within that segment are reachable via email. Keep in mind that exact segment membership is always calculated just before the message is sent.

You can also choose to only send your campaign to users who have a specific subscription status, such as those who are subscribed and opted in to email.

Optionally, you can also limit delivery to a specified number of users within the segment, or allow users to receive the same message twice upon a recurrence of the campaign.

Multichannel campaigns with email and push

For multichannel campaigns targeting both email and push channels, you may want to limit your campaign so that only the users who are explicitly opted in will receive the message (excluding subscribed or unsubscribed users). For example, say you have three users of different opt-in statuses:

  • User A is subscribed to email and is push enabled. This user doesn’t receive the email but will receive the push.
  • User B is opted-in to email but is not push enabled. This user will receive the email but doesn’t receive the push.
  • User C is opted-in to email and is push enabled. This user will receive both the email and the push.

To do so, under Audience Summary, select to send this campaign to “opted-in users only”. This option will check that only opted-in users will receive your email, and Braze will only send your push to users who are push enabled by default.

Choose conversion events

Braze allows you to track how often users perform specific actions, conversion events, after receiving a campaign. You can specify any of the following actions as a conversion event:

  • Opens app
  • Makes purchase (This can be a generic purchase or a specific item)
  • Performs specific custom event
  • Opens email

You can allow up to a 30-day window during which a conversion will be counted if the user takes the specified action. While Braze automatically tracks opens and clicks for your campaign, you may wish to set the conversion event to be when a user opens or clicks on an email address to take advantage of Intelligent Selection.

If you haven’t done so already, complete the remaining sections of your Canvas components. For further details on how build out the rest of your Canvas, implement multivariate testing and Intelligent Selection, and more, refer to the Build your Canvas step of our Canvas documentation.

Step 5: Review and deploy

The final page will give you a summary of the campaign you’ve just designed. Confirm all the relevant details and click Launch Campaign to enable it for sending.

Now just wait for all the data to roll in! Next, check out Email reporting to learn how you can access the results of your email campaigns.

New Stuff!