Skip to content

Link aliasing

Use link aliasing to create recognizable, user-generated names to identify links sent in email messages from Braze. Link aliasing gives you the ability to re-target users that have clicked specific links, allowing you to create action-based triggers when users click a specific aliased link.

Link aliasing creates user-generated names that are available for segmentation retargeting, action-based triggering, and link analytics. Link aliasing works by decorating a Braze-generated query parameter on links in the email channel. For each known link that is present in the email body, Braze will append lid={{placeholder}} to the end, where {{placeholder}} is a unique Liquid-generated alphanumeric value.

To create a link alias, click on the Link Management tab in a Braze campaign or Canvas wizard to decorate all known links in the email body. You can also set an alias that will be used to reference this link when dealing with reporting or segmentation.

Aliases must be uniquely named per email campaign variant or Canvas step. Link aliasing is only supported in href attributes within HTML anchor tags where it is safe to append a query parameter. It is best to include a question mark (?) at the end of your link so Braze can easily append the lid value. Without appending the lid value, Braze will not recognize the URL for link aliasing.

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!

Extracting Data

The following endpoints are available to extract the alias set in each message variant in a campaign or an email Canvas step:

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.

Note that link templates can only be applied for links visible in the Link Management tab. This means that links without the lid URL parameter, such as “old” Content Blocks or links that cannot be marked up, will not be eligible for link templates. To fix this, we recommend copying “old” Content Blocks or including a question mark (?) or ampersand (&) in the href attribute for the URL.

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.

Any existing Content Blocks created before Braze enabled this feature will only have their links modified when the HTML in that Content Block is edited and the Content Block is relaunched. Rather than relaunching, we recommend duplicating the Content Block.

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.

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 step. This filter is only available for campaigns or Canvases that have tracked aliases present.

When composing your email message, a new column will be present in the Link Management tab. Here, you can indicate to Braze which alias you would like to be “tracked” for segmentation purposes. You can track an unlimited number of links.

Only aliases you have indicated to be tracked will 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.

Untracking a link will not deallocate existing segments with the filter to the untracked alias. The old data will remain on the user profiles until they are evicted 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 app group by default. Links in messages that are archived will automatically be 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

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 step. A pipe delimited filter option displays the Canvas and Canvas step, followed by the alias within the Canvas step. 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 step. Because aliases are considered “global”, any global alias will target link clicks from all campaigns and Canvas steps.

Action-based filters

In addition to creating segment filters, you can also create action-based messages targeting any link (tracked or not tracked) across any email campaign or Canvas step.

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,
  "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!