Something BIG is happening to our documentation! Check back in early October!

Managing User Subscriptions

Subscription States

Braze has three subscription tiers for e-mail users:

State Definition
Opted-in User has explicitly confirmed he/she wants to receive e-mail. We recommend an explicit opt-in process to acquire consent from users to send e-mail.
Subscribed User has neither unsubscribed, nor explicitly opted-in to receive e-mails. A user automatically gets set as Subscribed when a valid e-mail address is added to their user profile.
Unsubscribed User has either explicitly unsubscribed from your e-mails or been automatically unsubscribed after marked one of your e-mails as spam.

Changing Subscriptions

Changing Email Subscriptions

In most cases, your users will manage their email subscription through subscription links that are included in the emails they receive.

Braze automatically inserts a footer with an unsubscribe link at the bottom of every email you send, in accordance with the CAN-SPAM Act of 2003. When users click on the unsubscribe url in this footer, they are unsubscribed and taken to a landing page that confirms the change to their subscription.

Braze provides the ability to set an app group wide custom email footer which you can template into every email using the {{${email_footer}}} attribute. In this way, you do not have to create a new footer for every email template or email campaign you use. Changes you make to your custom footer will be reflected in every email campaign that starts after the changes are saved. Remember that compliance with the CAN-SPAM Act of 2003 requires you to include a physical address for your company and an unsubscribe link in your emails. It is your responsibility to make sure that your custom footer meets those requirements.

To create or edit your custom footer, go to the Manage App Group page under App Settings, and select the Email Settings tab.

Email Settings

In the Custom Footer section, you can choose to turn on Custom Footers. Once turned on, you will see a window to edit your footer and send a test message.

Custom Footer

You will see the default footer which uses the {{${set_user_to_unsubscribed_url}}} attribute and Braze’s physical mailing address. To comply with CAN-SPAM regulations, your custom footer must include {{${set_user_to_unsubscribed_url}}}; you will not be able to save a custom footer without {{${set_user_to_unsubscribed_url}}}.

If using the default footer which uses the {{${set_user_to_unsubscribed_url}}} attribute, be sure to select “other” for the Protocol as indicated below.

Default Unsub URL Protocol

No Footer-Email Settings

Be very careful to use a template with the custom footer {{${email_footer}}} or {{${set_user_to_unsubscribed_url}}}when composing an email campaign. A warning will pop-up, however the ultimate decision of whether to send an email without an unsubscribe link lies with you.

No Footer-Campaign Composition

When creating a custom footer, Braze suggests you use attributes for personalization. Here are a few you may find useful:

Attribute Tag
User’s Email Address {{${email_address}}}
User’s Custom Unsubscribe URL {{${set_user_to_unsubscribed_url}}}
User’s Custom Opt-In URL {{${set_user_to_opted_in_url}}}
User’s Custom Subscribe URL {{${set_user_to_subscribed_url}}}

Of course, the full set of default and custom attributes are available to you. As a best practice, Braze recommends including both an unsubscribe link (i.e. {{${set_user_to_unsubscribed_url}}}) and an opt-in link (i.e. {{${set_user_to_opted_in_url}}}) in your custom footer. This way users will be able to both unsubscribe or opt-in and you can passively collect opt-in data for a portion of your users.

You can also choose to set a custom footer for plaintext emails, which follows the same rules as the custom footer for HTML emails. If you choose not to write a plaintext footer, Braze will automatically build one from the HTML footer. When your custom footers are to your liking, press Save at the bottom of the page.

Save Custom Footer

Custom Unsubscribe Landing Page

When a user clicks on an unsubscribe url in an email, they are taken to a default landing page that confirms the change to their subscription.

Optionally, you may provide HTML for your own custom landing page, which users will be directed to (instead of the default page) upon unsubscribing. This feature is available on the “App Settings - Email” page. We recommend including a resubscribe link (i.e. {{${set_user_to_subscribed_url}}} ) on this page so that users have the option to resubscribe in case they unsubscribed by accident.

Custom ReSubscribe

Changing Push Subscriptions

Braze’s SDKs provide methods for changing a user’s push message subscription. Please refer to Braze’s technical documentation for your mobile platform for information on configuring these methods:

Manually Changing User Subscriptions

You can manually change the subscription status for any user in his/her individual user profile. You can find individual user profiles by searching for a user’s ID or email address on the “User Search” page. Under the user profile’s “Engagement” tab, you’ll find a user’s current push and email subscription status. Clicking on the “Unsubscribed”, “Subscribed”, or “Opted In” buttons will allow you to change that user’s subscription status. If available, the user profile also displays a timestamp for when the user’s subscription was last changed.

User Profile Subscription UI

Subscriptions and Campaign Targeting

Campaigns with push or email messages are targeted at users who are subscribed or opted-in by default. You can change this targeting preference when editing a campaign by going to the “Target Users” step and clicking “Advanced Options.”

Braze supports three targeting states:

  • Users who are subscribed or opted-in (default).
  • Only users who are opted-in.
  • All users, including those who have unsubscribed.

Please note that it is your responsibility to comply with any applicable spam laws when using these targeting settings.

Campaign Targeting Subscription UI

Segmenting by User Subscriptions

The “Email Subscription Status” and “Push Subscription Status” filters allow you to segment your users by their subscription status.

This can be useful - for example, if you want to target users who have neither opted in nor out and encourage them to explicitly opt-in to email or push. In that case, you would create a segment with a filter for “Email/Push Subscription Status is Subscribed” and campaigns to this segment will go to users who are subscribed but not opted in.

Subscription Filter

User Import

Braze’s User Import feature allows users to upload and update user profiles via CSV files. This feature supports updating default and custom user profile attributes.


Braze accepts user data in the standard CSV format from files up to 100MB in size. The particulars of how to construct your file are described below.

Column Headers

Braze expects that the first row in your CSV file will contain the headers for each column in the file. The number of columns in each row must match the number of headers.

Users imported to Braze via CSV must be identified – Braze does not support creating entirely anonymous users via User Import. You must specify either a ‘braze_id’ or an ‘external_id’, but not both, allowing Braze to match an existing user.

  • If you provide an external_id, we will update any existing user with the same external_id or create a new identified user with that external_id set if one is not found.

  • If you provide a braze_id, we will update any existing user with the same braze_id but will not create a new identified user with that braze_id if one is not found since we do not allow entirely anonymous users via User Import.

All headers will be interpreted as custom attributes unless they match these fields used with the user data REST API:

  • braze_id
  • external_id
  • first_name
  • last_name
  • email
  • dob
  • country
  • language
  • home_city
  • bio
  • gender
  • phone
  • email_subscribe
  • push_subscribe
  • image_url

All of these fields are of type String except for dob (date of birth). Take care to use the exact spelling and proper case for pre-existing user data fields.


These data types are accepted in User Import:

  • Datetime (Must be stored in the ISO 8601 format)
  • Boolean (TRUE/FALSE)
  • Number (Integer or Float with no spaces or commas, floats must use ‘.’ as the decimal separator)
  • String (no commas)
  • Blank

Note that the following data types are not supported in User Import:

  • Arrays
  • Push Tokens
  • Custom Events

For uploading these kinds of values, please use our User Data API.


Any value which is not formatted to match the Datetime, Boolean, Integer, or Float specifications will be read as a String. Each comma in the input will be interpreted as a column separator, therefore any commas in values will cause errors in parsing the file. In addition, all leading and trailing whitespace will be trimmed from each value. Otherwise, values will be stored exactly as stored in the input CSV file. Blank values will not overwrite existing values on the user profile, and you do not need to include all existing user attributes in your CSV file.

For segmentation, it is important that each column contains a consistent data type. Values which do not match the attribute’s data type will not match the filters used to segment the attribute. In addition, for custom attributes whose data type is set as “Detect Automatically” on the dashboard, the most recently added value is used to set the data type of the attribute, so an error in your last row can interfere with proper segmentation.

During import, Braze determines the data type of each column by scanning a sample from the top rows of the file. Mixed data types in a column will not prevent you from importing your file, so we recommend exercising caution and ensuring the values in each column are consistent and match the data type you expect.


To import your CSV file, navigate to the User Import page under the Users section on the left hand toolbar. In the lower text box, “Recent Imports”, there will be a table which lists up to twenty of your most recent imports, their file names, number of lines in the file, number of lines successfully imported, total lines in each file, and the status of each import.

User Import

The upper box, “Import CSV”, will contain importing directions and a button to begin your import. Press the “Select CSV File” button and select your file of interest, then press “Start Upload.” Braze will upload your file and check the column headers as well as the data types of each column. Once the upload is complete, you will see a modal window with a table previewing the contents of your file. All the information in this table is based off of the values in top few rows of your CSV file. For column headers, default attributes will be written in normal text, while custom attributes will be italicized and have their type noted in parentheses. There will also be a short summary of your file at the top of the pop-up.

You can import more than one CSV at the same time. CSV imports will run concurrently, and as such the order of updates is not guaranteed to be serial. If you require CSV imports run in a serial fashion, you should wait until a CSV import has finished before uploading a second one.

Errorless Import

If Braze notices something malformed in your file during the upload, errors will be shown above the summary. A file can be imported with errors, but once started, an import cannot be cancelled or rolled-back. Review the preview, and if errors are found cancel the import and modify your file. It is important to examine the full file before upload as well. Braze does not scan every row of the input file at this stage; errors can exist which Braze does not catch while generating this preview. Malformed rows and rows lacking an external ID (A) will not be imported, all other errors can be imported (B) but may interfere with filtering when creating a segment. Note that errors are based solely off of data type and file structure - for example, a poorly formatted email address (C) would still be imported as it can still be parsed as a string.

Import Errors

When you are satisfied with the upload, start the import. The pop-up will close and the import will begin in the background. You can track its progress on the User Import page, which will refresh every 5 seconds, or at the press of the refresh button in the Recent Imports box. Under Lines Processed, you will see the progress of the import; the status will change to Complete when finished. You can continue to navigate around other parts of the dashboard during the import, you will receive modal notifications when the import begins and ends.

When the import process runs into an error, a yellow warning icon will be displayed next to the total number of lines in the file. You can mouse over the icon to see details into why certain lines failed. Once the import is Complete, all data will have been added to existing profiles or all new profiles will have been created.

Error Tooltip


User Import creates and updates user profiles, and can also be used to create segments. To create a segment, check the ‘Create a segment from this CSV’ box.

Create a Segment

You can set the name of the segment or accept the default, which is the name of your file. Files which were used to create a segment will have a link to view the segment once the import has completed.

View the Segment

The filter used to create the segment selects users who were created or updated in a selected import, and is available with all other filters in the edit segment page. Note that as of 4/10/2018, for each user, only the last 100 CSVs the user was imported/updated in are cached. So if you attempt to create a segment by filtering for members who were in an older import, the segment will not include users who have been in 100 or more imports since. Previous to 4/10/2018 Braze cached the last 10 CSVs that a user was imported/updated in.

Edit the Segment

Common Errors

  • No external_id: To connect data from User Import to user profiles, Braze requires an external_id in each row. Rows without a value in the external_id column will be excluded from the import. User profiles that lack an external_id cannot be created or updated via the User Import.
  • Malformed Row: There must be a header row in order to properly import data. Each row must have the same number of cells as the header row. Rows whose length that have more or fewer values than the header row will be excluded from the import. Commas in a value will be interpreted as a separator and can lead to this error being thrown. Additionally, all data must be UTF-8 encoded.
  • Multiple Data Types: Braze expects each value in a column to be of the same data type. Values which do not match their atttribute’s data type will cause errors in segmenting.
    • Incorrectly Formatted Dates: Dates not in the ISO 8601 format will not be read as datetimes on import.
    • String Quotation: Values encapsulated in single (‘’) or double (“”) quotation marks will be read as strings on import.