ContentBlockByName
Retrieves and renders a Content Builder content block by its full Name/path. Covers the missing-block default path and that default content is emitted literally.
Syntax
ContentBlockByName(contentBlockName[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode]) → stringParameters
| 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 |
string | boolean | number | No | When truthy (the default), a missing block aborts; when falsy, the page continues and the status variable is set to -1. Accepts true, false, 1, 0, "true", "false", "1", "0" |
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.
All eight boolean-like literals are accepted for errorOnMissingContentBlock. true, false, 1, 0, "true", "false", "1", "0" are interchangeable: when the block is missing, a truthy value aborts the page with HTTP 422 while a falsy value lets it continue at HTTP 200 and sets the status variable to -1.
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
]%%
OutputLine given a bare string literal renders an empty line. Wrap the argument in Concat() or your start and done markers vanish silently — which looks exactly like the function failing.
Availability
| Platform | Available |
|---|---|
| Marketing Cloud Engagement | Yes |
| Marketing Cloud Next | Yes, from API 67.0 |
See also
ContentBlockByID— retrieve the same block by its numeric IDContentBlockByKey— retrieve the same block by its customer keyContentAreaContentAreaByName— the retired Classic-content equivalents- Official reference
- ampscript.guide