sfmc.guide
Engagement Next
⌘K

ContentBlockByName

Retrieves and renders a Content Builder content block by its full Name/path. 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

ContentBlockByName(contentBlockName[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode])  →  string
1–5 arguments

Parameters

Name Type Required Description
contentBlockName string Yes Full Name/path of the content block to retrieve (for example Content Builder\My Folder\My Block)
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

%%=ContentBlockByName('Content Builder\My Folder\Welcome Banner')=%%

Renders the stored body of the block at that path.

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

%%[
  VAR @sc, @out
  SET @out = ContentBlockByName("Content Builder\nosuch-name", "", 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 full block Name/path renders the block body. The path is the complete folder chain plus the block name, using backslashes as separators.

A missing block with the error flag set to 0 returns the default content. ContentBlockByName("Content Builder\nosuch-name", "", 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 renders verbatim; the embedded AMPscript is not evaluated. Use TreatAsContent if the fallback string itself needs to run as AMPscript.

The full five-argument signature works. All optional 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, @name
  SET @b = RequestParameter("b")
  SET @name = Concat("Content Builder\", "nosuch-name-", "zzz")

  /* safe sweep: the missing/default paths are all accepted */
  IF @b == "safe" THEN
    /* missing with error flag 0: returns the default content and sets status to -1 */
    SET @miss = ContentBlockByName(@name, "", 0, "FB-CBN", @sc)
    OutputLine(Concat("miss=[", @miss, "] sc=[", @sc, "]"))

    /* default content is emitted literally - the inline AMPscript is NOT evaluated */
    SET @lit = ContentBlockByName(@name, "", 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