Handlebars Helper Function: buildUrl

Creates a URL that includes click tracking. Use this helper to add UTM parameters and custom query parameters to a link.

Availability

This helper is available in the Winter ’27 release of Marketing Cloud Next.

Syntax

{{buildUrl base
  [encode=true|false] [label=LABEL]
  [noTracking=true|false] [sfmclinkid=LINK_ID]
  [sfmclinkalias=LINK_ALIAS] [utm_campaign=CAMPAIGN]
  [utm_content=CONTENT] [utm_medium=MEDIUM]
  [utm_source=SOURCE] [utm_term=TERM]
  [CUSTOM_KEY=CUSTOM_VALUE]
}}

Parameters

Parameter	Type	Description
`base`	String	Required. The destination URL. The helper function preserves existing query parameters.
`encode`	Boolean	When `true`, URL-encodes parameter values. The default is `true`. The `base` URL is never encoded.
`label`	String	A link alias for tracking. Don't use with `sfmclinkalias`.
`noTracking`	Boolean	When `true`, returns the composed URL without click tracking. The default is `false`.
`sfmclinkid`	String	An internal link identifier for tracking.
`sfmclinkalias`	String	A link alias for tracking. Don't use with `label`.
`utm_campaign`	String	The campaign name or identifier.
`utm_content`	String	A value that differentiates links that point to the same URL.
`utm_medium`	String	The marketing medium.
`utm_source`	String	The traffic source.
`utm_term`	String	Paid-search keywords.
`CUSTOM_KEY`	Any	A custom parameter to append to the URL.

Specify all optional parameters as named parameters.

The helper also applies link parameters configured for the content asset and business unit. Values provided directly in buildUrl take precedence over content-level values, which take precedence over business unit values. A direct parameter with a null or blank value removes the parameter from the URL.

Return Value

The function returns a URL that has click tracking enabled. By default, it adds the composed destination URL to a tracking token. When noTracking=true, the function returns the composed destination URL directly.

If base is missing, null, or empty, the function throws an exception. It also throws an exception if you use a reserved tracking parameter as a custom parameter or specify both label and sfmclinkalias.

Usage Examples

This example creates a tracked URL with a campaign parameter.

{{buildUrl product.DetailUrl utm_campaign=$message.campaign.name}}

This example adds a custom parameter and turns off automatic encoding because the value is already encoded.

{{buildUrl product.DetailUrl token=preEncodedToken encode=false}}

This example creates an untracked URL. Query parameters are still applied.

{{buildUrl https://www.example.com noTracking=true}}