sfmc.guide
Engagement Next
⌘K

HTTPGet

Performs an HTTP GET request and returns the response body. Runtime-proven on a live Marketing Cloud Engagement CloudPage — including the status output variable that reports 0 on success and -2 on a failed request.

Runtime verified Test scripts included

Syntax

HTTPGet(httpGetUrl[, continueOnError, emptyContentHandling, status])  →  string
1–4 arguments

Parameters

Name Type Required Description
httpGetUrl string Yes The URL to fetch with the GET method
continueOnError boolean No When true, an error is ignored instead of stopping the process
emptyContentHandling number No How empty content is handled: 0 allows it, 1 returns an error, 2 skips the subscriber in a send
status number No Output variable that receives the status: 0 success, -1 not found, -2 request error, -3 empty content

Example

%%[ VAR @body SET @body = HTTPGet("https://sfmc.guide/robots.txt") ]%%
%%=v(@body)=%%

Renders the target’s body text, e.g. a line beginning Sitemap: https://sfmc.gui….

Pass a status output variable and guard on it before using the body:

%%[
  VAR @body, @status
  SET @body = HTTPGet("https://sfmc.guide/robots.txt", true, 0, @status)
  IF @status == 0 THEN
]%%
%%=v(@body)=%%
%%[ ELSE ]%%
The content isn't available right now.
%%[ ENDIF ]%%

Return value

string — the body of the HTTP response as text. The body is arbitrary, so there is no closed set of values to test for. The numeric status is not the return value; it is delivered separately through the fourth output-variable argument.

Behaviour

The return is the response body, and the status is a separate output variable. A successful GET returns the body string; the fourth argument, when supplied, is a variable that receives the numeric status — 0 on success. This differs from the SSJS Platform.Function.HTTPGet, whose status array came back empty in the same context.

A failed request returns empty and sets the status to -2. Fetching a URL that 404s, or a host that does not resolve, with continueOnError set to true returns the empty string and puts -2 into the status variable, rather than aborting the page.

The empty-content and error options are accepted from a CloudPage. emptyContentHandling accepts 0 and continueOnError accepts true/false without error. Their send-context effects — ending a send on error, skipping a subscriber on empty content — govern email and automation runs and cannot be observed from a CloudPage request.

Show test script
%%[
  VAR @b, @url, @res, @st
  SET @b = RequestParameter("b")
  SET @url = "https://sfmc.guide/robots.txt"
  OutputLine(Concat("CTRL=[", Uppercase("ok"), "]"))

  /* 1-arg form: returns the response body string. fetch ?b=g1 */
  IF @b == "g1" THEN
    SET @res = HTTPGet(@url)
    OutputLine(Concat("len=[", Length(@res), "] slice=[", Substring(@res, 1, 25), "]"))
  ENDIF

  /* full 4-arg form with a status out-variable: status 0 on success. fetch ?b=g4 */
  IF @b == "g4" THEN
    SET @res = HTTPGet(@url, true, 0, @st)
    OutputLine(Concat("len=[", Length(@res), "] status=[", @st, "]"))
  ENDIF

  /* 2-arg form (continueOnError only). fetch ?b=g2arg */
  IF @b == "g2arg" THEN
    SET @res = HTTPGet(@url, true)
    OutputLine(Concat("len=[", Length(@res), "]"))
  ENDIF

  /* 3-arg form (continueOnError + emptyContentHandling). fetch ?b=g3arg */
  IF @b == "g3arg" THEN
    SET @res = HTTPGet(@url, true, 0)
    OutputLine(Concat("len=[", Length(@res), "]"))
  ENDIF

  /* a 404 URL with continueOnError=true: empty body, status -2. fetch ?b=badurl */
  IF @b == "badurl" THEN
    SET @res = HTTPGet("https://sfmc.guide/this-page-does-not-exist-xyz-404", true, 0, @st)
    OutputLine(Concat("len=[", Length(@res), "] status=[", @st, "] empty=[", Empty(@res), "]"))
  ENDIF

  /* an unresolvable host with continueOnError=true: empty body, status -2. fetch ?b=unreach */
  IF @b == "unreach" THEN
    SET @res = HTTPGet("https://this-host-does-not-resolve-zzq.example", true, 0, @st)
    OutputLine(Concat("len=[", Length(@res), "] status=[", @st, "] empty=[", Empty(@res), "]"))
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next No

See also