sfmc.guide
Engagement Next
⌘K

ContentBlockByID

Retrieves and renders a Content Builder content block by its numeric ID. Runtime-proven on a live Marketing Cloud Engagement CloudPage — including the missing-block default path and that default content is emitted literally.

Next
Runtime verified Test scripts included

Syntax

ContentBlockByID(contentBlockId[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode])  →  string
1–5 arguments

Parameters

Name Type Required Description
contentBlockId number | string Yes ID of the content block to retrieve
impressionRegionName string No Impression region name to associate with the block
errorOnMissingContentBlock boolean No When true (the default), a missing block aborts; set to 0 to fall back to the default content
errorMessage string No Default content returned when the block is missing — emitted literally
statusCode number No Output variable set to 0 on success or -1 when no content was found

Example

%%=ContentBlockByID(1469165)=%%

Renders the stored body of block 1469165 — in this run the fixture block rendered SSJSGUIDE-TEST-BLOCK-OK.

A more defensive form suppresses the missing-block abort and supplies fallback text plus a status variable:

%%[
  VAR @sc, @out
  SET @out = ContentBlockByID(999999999, "", 0, "Block unavailable", @sc)
]%%
%%=v(@out)=%%

Renders Block unavailable and sets @sc to -1.

Return value

string — the rendered HTML of the referenced block, or the errorMessage default when the block is missing and errorOnMissingContentBlock is 0. There is no closed set of sentinel values.

Behaviour

A bare numeric ID renders the block body. The numeric-string form (ContentBlockByID("1469165")) returns the identical result, so the ID accepts both a number and its string spelling.

A missing block with the error flag set to 0 returns the default content. ContentBlockByID(999999999, "", 0, "FB", @sc) renders FB and sets the status variable to -1 instead of aborting the page.

The default content is emitted literally. A default containing an inline expression — "PRE-%%=Add(2,3)=%%-POST" — renders PRE-%%=Add(2,3)=%%-POST verbatim; the embedded AMPscript is not evaluated. Use TreatAsContent if you need the fallback string itself to run as AMPscript.

The full five-argument signature works. All of the impression-region, error-flag, default-content and status-code arguments are honoured — unlike the SSJS binding of the same name, which only reads the first argument.

Show test script
%%[
  VAR @b, @sc, @miss, @lit
  SET @b = RequestParameter("b")

  /* safe sweep: the found render and the missing/default paths are all accepted */
  IF @b == "safe" THEN
    /* found: renders the stored block body */
    OutputLine(Concat("CBID=[", ContentBlockByID(1469165), "]"))

    /* missing with error flag 0: returns the default content and sets status to -1 */
    SET @miss = ContentBlockByID(999999999, "", 0, "FB-CBID", @sc)
    OutputLine(Concat("miss=[", @miss, "] sc=[", @sc, "]"))

    /* default content is emitted literally - the inline AMPscript is NOT evaluated */
    SET @lit = ContentBlockByID(999999999, "", 0, "PRE-%%=Add(2,3)=%%-POST", @sc)
    OutputLine(Concat("lit=[", @lit, "]"))
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next Yes, from API 67.0

See also