sfmc.guide
Engagement Next
⌘K

HTTPPost

Performs an HTTP POST request and returns the HTTP status code. Runtime-proven on a live Marketing Cloud Engagement CloudPage — including the fourth argument that receives the response body rather than the status the docs describe.

Runtime verified Differs from official docs Test scripts included

Syntax

HTTPPost(urlEndpoint, contentTypeHeader, contentToPost[, @response, headerName1, headerValue1, ...])  →  number

Parameters

Name Type Required Description
urlEndpoint string Yes The URL to post the content to
contentTypeHeader string Yes The Content-Type header for the request
contentToPost string Yes The content to send in the POST body
response string No Output variable that receives the response body
headerName1 string No Name of an additional request header
headerValue1 string No Value of an additional request header

There is no upper bound on the argument count — additional request headers are passed as repeated name/value pairs after the response variable.

Example

%%[ VAR @status, @body
  SET @status = HTTPPost("https://postman-echo.com/post", "application/json", '{"marker":"amp-post-zz9","n":7}', @body)
]%%
%%=v(@status)=%%

Renders 200, and @body holds the echoed response, e.g. {"args":{},"data":{"marker":"amp-post-zz9","n":7},….

Read the body from the output variable and treat any failure as an aborted page — a non-2xx response never returns a status here:

%%[
  VAR @status, @body
  SET @status = HTTPPost("https://postman-echo.com/post", "application/json", @payload, @body)
]%%
Status %%=v(@status)=%%; response %%=v(@body)=%%

Return value

number — the HTTP status code of the response, which is 200 on a successful POST. There is no closed set of values to test for a success, and a failing status is never returned: a non-2xx response aborts the page instead.

Behaviour

The fourth argument receives the response body, not the status. The official reference labels it as the request “status”, but at runtime it holds the response body — a POST to the echo endpoint filled it with 299 characters of echoed JSON. The numeric HTTP status code is the function’s return value instead. See the differs-from-docs note.

The content type and body are transmitted verbatim. The echo endpoint reflected the application/json content type and the exact payload back in its data field, confirming both were sent as supplied.

A failing response aborts the whole page. A POST that answered 404, and a POST with an empty URL, each aborted the page with HTTP 422 rather than returning a status you could branch on. Because AMPscript has no try/catch, there is no way to recover from a non-2xx response inline.

Show test script
%%[
  VAR @b, @st, @resp
  SET @b = RequestParameter("b")
  OutputLine(Concat("CTRL=[", Uppercase("ok"), "]"))

  /* 4-arg form: status is the return value, @resp receives the body. fetch ?b=post1 */
  IF @b == "post1" THEN
    SET @st = HTTPPost("https://postman-echo.com/post", "application/json", '{"marker":"amp-post-zz9","n":7}', @resp)
    OutputLine(Concat("status=[", @st, "] resplen=[", Length(@resp), "]"))
    OutputLine(Concat("respslice=[", Substring(@resp, 1, 60), "]"))
  ENDIF

  /* 3-arg minimal form (no out-variable): returns the status. fetch ?b=min3 */
  IF @b == "min3" THEN
    SET @st = HTTPPost("https://postman-echo.com/post", "text/plain", "hello-amp")
    OutputLine(Concat("status=[", @st, "]"))
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next No

See also