sfmc.guide
Engagement Next
⌘K

ContentBlockByKey

Retrieves and renders a Content Builder content block by its customer key. 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

ContentBlockByKey(contentBlockKey[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode])  →  string
1–5 arguments

Parameters

Name Type Required Description
contentBlockKey string Yes Customer key 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

%%=ContentBlockByKey('ssjs-guide-test-block')=%%

Renders the stored body of the block with that customer key — 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 = ContentBlockByKey("nosuch-key", "", 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 customer key renders the block body. This is the most portable of the retrieval functions because the key travels with the block across business units, unlike the numeric ID.

A missing block with the error flag set to 0 returns the default content. ContentBlockByKey("nosuch-key", "", 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
  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("CBK=[", ContentBlockByKey("ssjs-guide-test-block"), "]"))

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

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