Skip to content

Braze Learning courseLink aliasing

Use link aliasing to create recognizable, user-generated names to identify links sent in email messages from Braze. These links are available for segmentation retargeting, action-based triggering, and link analytics. Link aliasing gives you the ability to retarget users that have clicked specific links, allowing you to create action-based triggers when users click a specific aliased link.

Link aliasing works by decorating a Braze-generated query parameter on links in the email channel. To create a link alias, follow these steps:

  1. Open your email body.
  2. Click the Link Management tab.
  3. Braze automatically generates unique default link aliases for each of your links.
  4. Give the alias a name. Aliases must be uniquely named per email campaign variant or Canvas component.

You can also set an alias that will be used to reference a specific link when dealing with reporting or segmentation.

Link aliasing is only supported in href attributes within HTML anchor tags where it is safe to append a query parameter. It’s best to include a question mark (?) at the end of your link so that Braze can easily append the lid value. Without appending the lid value, Braze will not recognize the URL for link aliasing.

Follow these steps to view all of your tracked link aliases:

  1. Go to Settings > Email Preferences under Workspace Settings.
  2. Click the Link Aliasing Settings tab.

Here, you can also sort and search through all link aliases.

Tracked Link Aliases page that shows a link alias named "test" that is an active part of a Canvas step.

On the Link Aliasing Settings tab, you can turn off tracking for link aliases.

  1. Select the link alias.
  2. Click Turn off tracking.

In Braze, if you have a link alias in your app or website and a user clicks on it, the event is recorded in the user’s profile with the alias. Later, if you decide to rename this link alias, the previous click data in the user profile will not be updated, meaning it will still show as the previous link alias. So, if you target users based on the the new link alias, it will not include the data from the previous link alias.

Checking workflows

Braze recommends evaluating the links within the email, adding link templates, and providing a naming convention that works for segmentation and reporting purposes. This helps you keep track of all links.

When link aliasing is enabled, messages, Content Blocks, and link templates are not modified. Any existing messages using link templates or Content Blocks will be the same. However, when you update a message, link alias markup will apply to all of the links, so you’ll need to reapply the link templates for the links to be visible.

Extracting data

Use the List link alias for campaign and List link alias for Canvas endpoints to extract the alias set in each message variant in a campaign or an email-specific Canvas component.

New Content Blocks will have their links modified where Braze will append a lid= to each link where applicable. This placeholder value is resolved when inserted into an email message variant.

To modify the links within existing Content Blocks that were created before Braze enabled link aliasing, duplicate the existing Content Blocks, then modify the links within the duplicated Content Blocks.

When a Content Block without a lid value is inserted into a new message, the links from that Content Block are not tracked with an alias. When a new Content Block is inserted into an “old” message variant, the links from that message variant will be recognized by link aliasing. Links from the Content Block are also recognized. However, “old” Content Blocks cannot nest “new” Content Blocks.


The following table provides examples of links in an email body, link aliasing results, and explanations for how the original link is updated with link aliasing.

Link in Email Body Link with Aliasing Logic Braze inserts a question mark (?) and adds the first query parameter into the URL. Braze detects other query parameters and appends lid= to the end of the URL.
<a href="{{custom_attribute.{product_url}}}?"> <a href="{{custom_attribute.{product_url}}}?lid=ac7a548g5kl7"> Braze recognizes that this is a URL and already has a question mark (?) present. Then, it appends the lid query parameter after the question mark. Braze expects the URL to use a standard structure where anchors (#) are present after a question mark (?). Because Braze reads from left to right, we will append the question mark and lid value before the anchor.

For URLs that are generated by an assign statement in the HTML or in a Content Block, we recommend adding a question mark (?) into the anchor tag. This will help Braze append query parameters (lid = somevalue) so link aliasing can work properly. Without identifying where to append query parameters, link aliasing will not recognize these URLs.


Check out this link aliasing example for the recommended formatting of the anchor tag:

{% assign link1 = "" %}

<a href="{{link1}}?">{{link1}}</a>

For new message variants, any existing link template can be used from the Link Management tab. For messages that were launched with a link template, they still will be applied. If an existing message is modified, the link template must be reapplied through the Link Management tab.

The retargeting of aliases filters allow you to create segmentation filters based on your customers clicking a specifically tracked alias from either an email campaign or Canvas component. This filter is only available for campaigns or Canvases that have tracked aliases present.

In the Link Management tab, select which aliases you would like to be “tracked” for segmentation purposes and to be present in segmentation filters. Note that tracked aliases are only for segmentation purposes and will have no impact on your link being tracked for reporting purposes.

Braze allows you to select unlimited links to track, though you may only retarget users on the most recent links they have opened. User profiles include their 100 most recently clicked links. For example, if you track 500 links and a user clicks on all 500 of them, you can retarget or create segments based on the 100 most recently clicked links.

Link Management tab of the Drag-and-Drop email editor.

Link Management tab of the HTML email editor.

Untracking a link will not reallocate existing segments with the filter to the untracked alias. The old data will remain on the user profiles until it’s replaced by newer data. The following segmentation filters will continue to exist, but new segments cannot be created with that filter.

For segmentation purposes, only 100 links can be tracked per workspace by default. Links in archived messages are automatically untracked. However, if archived messages are unarchived, the links will need to be tracked again. When link aliases are tracked, link reporting is indexed by the alias instead of top-level domains or full URLs.

Segment filters

The following segment filters apply to click events that are tracked at the time the event is processed. This means untracking links won’t remove existing data and tracking a link won’t backfill the data.

Clicked Alias in Campaign

Retarget users based on the specific alias that was clicked in a campaign. Only the campaigns that have aliases which were tracked will be reflected here.

Clicked Alias in Canvas Step

Retarget users based on the specific alias that was clicked in a Canvas component. A pipe delimited filter option displays the Canvas and Canvas component, followed by the alias within the Canvas component. Only Canvas steps with tracked aliases will be shown here.

Clicked Alias in Campaign or Canvas

Retarget users based on any alias that was clicked in the campaign or Canvas component. Because aliases are considered “global”, any global alias will target link clicks from all campaigns and Canvas steps.

Action-based filters

You can create action-based messages targeting any link (tracked or not tracked) or retarget users based on if they clicked an alias across any email campaign or Canvas component.

Email clicks event

The email clicks event occurs when a user clicks an email. Multiple events may be generated for the same campaign if a user clicks multiple times or clicks different links within the email. There are two additional fields for the email clicks event when link aliasing is enabled: link_id and link_alias.

// Email Click:
  "id": (string) unique ID of this event,
  "user_id": (string) Braze user ID of the user,
  "external_user_id": (string) External ID of the user,
  "time": (int) 10-digit UTC time of the event in seconds since the epoch,
  "timezone": (string) IANA time zone of the user at the time of the event,
  "campaign_id": (string) ID of the campaign if from a campaign,
  "campaign_name": (string) name of the campaign,
  "message_variation_id": (string) ID of the message variation if from a campaign,
  "message_variation_name": (string) the name of the message variation if from a campaign,
  "canvas_id": (string) ID of the Canvas if from a Canvas,
  "canvas_name": (string) name of the Canvas,
  "canvas_variation_id": (string) ID of the Canvas variation the user is in if from a Canvas,
  "canvas_variation_name": (string) name of the Canvas variation the user is in if from a Canvas,
  "canvas_step_id": (string) ID of the step for this message if from a Canvas,
  "canvas_step_name": (string) name of the step for this message if from a Canvas,
  "send_id": (string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
  "dispatch_id": (string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
  "email_address": (string) email address for this event,
  "url": (string) the URL that was clicked (Email Click events only),
  "user_agent": (string) description of the user's system and browser for the event (Email Click and Open events only),
  "ip_pool": (string) IP pool used for message sending,
  "link_id": (string) unique value generated by Braze for the URL,
  "link_alias": (string) alias name set when the message was sent
New Stuff!