sfmc.guide
Engagement Next
⌘K

URLEncode

URL-encodes a string for safe inclusion in a URL. Runtime-proven on a live Marketing Cloud Engagement CloudPage — including the default that leaves a value which is not a URL completely unchanged.

Runtime verified Test scripts included

Syntax

URLEncode(urlToEncode[, encodeAllChars, encodeAllStrings])  →  string
1–3 arguments

Parameters

Name Type Required Description
urlToEncode string | number Yes Value to make safe for use in a URL
encodeAllChars string | boolean | number No Switches on full encoding of the query string; off by default
encodeAllStrings string | boolean | number No Switches on encoding of the whole input, not just a query string; off by default

Each flag accepts 1/0, true/false, or any of those four words quoted as a string.

Example

%%[
  VAR @safe
  SET @safe = URLEncode("https://example.org/go?promo=spring sale&tags=a,b")
]%%
%%=v(@safe)=%%

Renders https://example.org/go?promo=spring%20sale&tags=a,b.

A bare field value needs both flags, otherwise nothing happens to it:

%%[
  VAR @promo, @link
  SET @promo = "spring sale"
  SET @link = Concat("https://example.org/go?promo=", URLEncode(@promo, 1, 1))
]%%
<a href="%%=v(@link)=%%">Shop now</a>

That builds https://example.org/go?promo=spring+sale. Why the flags are needed for a plain value is the subject of the next chapter.

Return value

string — the encoded form of the input.

Hex escapes are written in lower case (%3d, %2c). There is no closed set of sentinel values to test for: an empty input returns an empty string, and every rejected call aborts the page rather than returning a marker value.

Behaviour

By default only the segment after a question mark is touched, and only spaces are converted. The literal spring sale comes back as spring sale, unchanged, while https://example.org/go?promo=spring sale&tags=a,b comes back as https://example.org/go?promo=spring%20sale&tags=a,b — the space became %20, and the comma, ampersand and equals sign were left alone.

Switching encodeAllChars on percent-encodes the reserved query characters and turns spaces into plus signs. The same URL then renders as https://example.org/go?promo%3dspring+sale%26tags%3da%2cb. The scheme and host before the question mark are never encoded, whatever the flags say.

Switching encodeAllStrings on makes a non-URL input eligible. spring sale renders as spring%20sale with the second flag alone, and as spring+sale when both flags are on.

Omitting the third argument is the same as switching it off. A two-argument call on the URL above produced exactly the value the three-argument call with a trailing off value produced.

Numbers are accepted as the input. Encoding the numeric literal 4821 gives 4821, so a numeric field needs no conversion first. An empty input returns an empty string.

The two flags have four interchangeable spellings

Call on spring sale Renders
URLEncode(@promo, 0, 1) spring%20sale
URLEncode(@promo, false, true) spring%20sale
URLEncode(@promo, "0", "1") spring%20sale
URLEncode(@promo, 1, 1) spring+sale
URLEncode(@promo, true, true) spring+sale
URLEncode(@promo, "1", "1") spring+sale

The integer form and the boolean form are not two behaviours — all four combinations of the two flags were run in both spellings over the same input and matched character for character. The quoted spellings reach the same code path, so a flag read out of a data extension field works without conversion. A value outside the two states is accepted rather than rejected: passing 2 for both flags rendered the input untouched, i.e. it behaved like the off state.

Catalogued on Differs from official docs. The official page describes the flags as integers and the community reference as booleans; neither is contradicted by the runtime, both are simply incomplete, so the entry is not flagged as disagreeing with the docs.

Show test script
%%[
  VAR @b, @plain, @url
  SET @b = RequestParameter("b")
  SET @plain = "spring sale"
  SET @url = Concat("https://example.org/go?promo=spring sale&tags=a,b")

  /* the defaults, and the integer and boolean spellings of both flags */
  IF @b == "safe" THEN
    OutputLine(Concat("A1PLAIN=[", URLEncode(@plain), "]"))
    OutputLine(Concat("A1URL=[", URLEncode(@url), "]"))
    OutputLine(Concat("N00=[", URLEncode(@url, 0, 0), "]"))
    OutputLine(Concat("B00=[", URLEncode(@url, false, false), "]"))
    OutputLine(Concat("N10=[", URLEncode(@url, 1, 0), "]"))
    OutputLine(Concat("B10=[", URLEncode(@url, true, false), "]"))
    OutputLine(Concat("N01=[", URLEncode(@plain, 0, 1), "]"))
    OutputLine(Concat("B01=[", URLEncode(@plain, false, true), "]"))
    OutputLine(Concat("N11=[", URLEncode(@plain, 1, 1), "]"))
    OutputLine(Concat("B11=[", URLEncode(@plain, true, true), "]"))
    OutputLine(Concat("A2N0=[", URLEncode(@url, 0), "]"))
    OutputLine(Concat("A2N1=[", URLEncode(@url, 1), "]"))
    OutputLine(Concat("A2BF=[", URLEncode(@url, false), "]"))
    OutputLine(Concat("A2BT=[", URLEncode(@url, true), "]"))
    OutputLine(Concat("EMPTY=[", URLEncode(""), "]"))
  ENDIF

  /* the same two flags written as quoted strings */
  IF @b == "strflag" THEN
    OutputLine(Concat("--- strflag start ---"))
    OutputLine(Concat("S11=[", URLEncode(@plain, "1", "1"), "]"))
    OutputLine(Concat("STRUE=[", URLEncode(@plain, "true", "true"), "]"))
    OutputLine(Concat("S01=[", URLEncode(@plain, "0", "1"), "]"))
    OutputLine(Concat("SFALSETRUE=[", URLEncode(@plain, "false", "true"), "]"))
    OutputLine(Concat("--- strflag done ---"))
  ENDIF

  /* a number is accepted as the input */
  IF @b == "numsrc" THEN
    OutputLine(Concat("--- numsrc start ---"))
    OutputLine(Concat("NUMSRC=[", URLEncode(4821, 1, 1), "]"))
    OutputLine(Concat("--- numsrc done ---"))
  ENDIF

  /* a flag value outside 0/1 is accepted and behaves like the off state */
  IF @b == "outdomain" THEN
    OutputLine(Concat("--- outdomain start ---"))
    OutputLine(Concat("OUT22=[", URLEncode(@plain, 2, 2), "]"))
    OutputLine(Concat("--- outdomain done ---"))
  ENDIF

  /* both branches below abort the page: the start marker never renders */
  IF @b == "a0" THEN
    OutputLine(Concat("--- a0 start ---"))
    OutputLine(Concat("A0=[", URLEncode(), "]"))
  ENDIF

  IF @b == "a4" THEN
    OutputLine(Concat("--- a4 start ---"))
    OutputLine(Concat("A4=[", URLEncode(@plain, 1, 1, 1), "]"))
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next No

See also