HTTPGet

Performs an HTTP GET request and returns the response body. Covers the status output variable that reports 0 on success and -2 on a failed request.

Engagement

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	string | boolean | number	No	When truthy, a request error is swallowed and the empty string is returned; when falsy, the error aborts the page. Accepts true, false, 1, 0, "true", "false", "1", "0"
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.

continueOnError is the inverse of the POST-family flags. All eight boolean-like literals are accepted, and against a 404 endpoint a truthy value returns HTTP 200 with the error swallowed (empty body, status -2) while a falsy value aborts the page with HTTP 422 — the opposite of exceptionOnError on the POST functions, where truthy aborts. An unrecognised string is coerced to falsy rather than rejected. emptyContentHandling’s send-context effects — ending a send on error, skipping a subscriber on empty content — govern email and automation runs and do not apply to a page 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
]%%

OutputLine needs Concat

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	No

See also

• HTTPRequestHeader — other HTTP functions
• Official reference
• ampscript.guide