ContentBlockByID
→ stringRenders a Content Builder asset by its numeric identifier.
Syntax
Platform.Function.ContentBlockByID(id[, regionName, stopOnError, fallbackContent])
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | number | Yes | The numeric ID of the Content Builder asset. Accepted as a number, as a numeric string, and as a variable. |
regionName |
string | No | The impression region name to associate with this content block. ⚠️ Unreachable from SSJS — supplying a 2nd argument always throws, see below. |
stopOnError |
boolean | No | When true, stops rendering if the block is not found. Defaults to false. ⚠️ Unreachable from SSJS — the call already throws on regionName. |
fallbackContent |
string | No | HTML string to render if the block is not found. ⚠️ Unreachable from SSJS — never emitted. |
From SSJS only the single-argument form works. Supplying any second argument throws a resolved-value error naming ImpressionRegionName — a string literal fails exactly like a variable, so this is not a literal-vs-variable restriction. The three optional parameters are reachable only through the AMPscript form; see the workaround below.
Show test script
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Chapter: Parameters —
* Platform.Function.ContentBlockByID(id[, regionName, stopOnError, fallbackContent])
*
* Proves:
* 1. The member resolves on Platform.Function (typeof "clrmethodinfo",
* the engine's uniform marker for a host CLR method — it proves
* nothing about existence, only invocation does).
* 2. `id` is required and the documented minimal 1-argument call returns
* the asset's rendered body as a string (return_type: string,
* min_args: 1).
* 3. TYPE-ACCEPTANCE (Number↔string): `id` is accepted as a number AND as
* a numeric STRING with the SAME meaningful result (fixture body), and
* also as a VARIABLE — the single-argument form has no literal
* restriction. Dual acceptance widens the Parameters type to
* string | number.
* 4. A non-existent id throws.
* 5. DEV the documented optional `regionName` (parameter 2) is
* unreachable from SSJS: a plain STRING LITERAL is rejected with the
* resolved-value error naming ImpressionRegionName / Ordinal 2 /
* ResolvedValueParameter. A number, a boolean, the empty string, null
* and a variable all fail the same way — so this is NOT a
* literal-vs-variable restriction, the parameter cannot be supplied.
* 6. DEV because parameter 2 is rejected outright, the documented
* `stopOnError` (parameter 3) and `fallbackContent` (parameter 4) are
* UNREACHABLE from SSJS: arity 3 and arity 4 throw the same
* ImpressionRegionName error, so neither stopOnError nor the fallback
* string ever takes effect.
* 7. Arities outside the documented 1..4 range (0 and 5) throw the
* overloaded "security descriptor" error.
*
* SCOPE: CloudPage only. Whether `regionName` would register an impression
* is not asserted — impression counts surface in Marketing Cloud tracking
* reports after a send is processed and are not observable from inside this
* request. (It is moot here in any case: the parameter cannot be supplied.)
*
* NOT ASSERTED: the exact text of the thrown messages. Any string operation
* on these CLR exception messages (.length / .indexOf / .substring) aborts
* the CloudPage with HTTP 422, so each message is printed verbatim next to
* its assertion for the reader instead of being matched programmatically.
*
* EXPECTED OUTPUT: every line starts with PASS. A FAIL means the runtime no
* longer matches the documented claim and the page must be revised.
*/
function assert(id, actual, expected) {
Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
function assertThrows(id, fn) {
var threw = false, msg = "";
try { fn(); } catch (ex) { threw = true; msg = ex.message; }
Platform.Response.Write((threw ? "PASS " : "FAIL ") + id + " -> " + (threw ? "threw: " + msg : "did NOT throw") + "\n");
}
/* 1. The member resolves as a host CLR method. */
assert("typeof Platform.Function.ContentBlockByID is clrmethodinfo", String(typeof Platform.Function.ContentBlockByID), "clrmethodinfo");
/* 2. The required numeric `id` alone renders the block and returns a string. */
var body = Platform.Function.ContentBlockByID(1469165);
assert("arity 1 with a real numeric id returns a string", String(typeof body), "string");
assert("arity 1 returns the fixture block's body", body, "SSJSGUIDE-TEST-BLOCK-OK");
/* 3. TYPE-ACCEPTANCE: number, numeric string and variable all accepted at arity 1 with the same body. */
var bodyAsNumber = Platform.Function.ContentBlockByID(1469165);
var bodyAsString = Platform.Function.ContentBlockByID("1469165");
assert("arity 1 accepts the id as a number", bodyAsNumber, "SSJSGUIDE-TEST-BLOCK-OK");
assert("arity 1 accepts the id as a numeric string", bodyAsString, "SSJSGUIDE-TEST-BLOCK-OK");
assert("TYPE-ACCEPT number and numeric-string id return the same body", bodyAsNumber === bodyAsString ? "true" : "false", "true");
var varId = 1469165;
assert("arity 1 accepts a VARIABLE id", Platform.Function.ContentBlockByID(varId), "SSJSGUIDE-TEST-BLOCK-OK");
/* 4. A non-existent id throws. */
assertThrows("arity 1 with a non-existent id throws", function () {
return Platform.Function.ContentBlockByID(12345);
});
/* 5. DEV regionName cannot be supplied at all — every shape is rejected. */
assertThrows("DEV arity 2 with a STRING LITERAL regionName throws (docs: optional impression region)", function () {
return Platform.Function.ContentBlockByID(1469165, "ssjsGuideRegion");
});
assertThrows("DEV arity 2 with a numeric regionName throws too", function () {
return Platform.Function.ContentBlockByID(1469165, 7);
});
assertThrows("DEV arity 2 with a boolean regionName throws too", function () {
return Platform.Function.ContentBlockByID(1469165, false);
});
assertThrows("DEV arity 2 with an empty-string regionName throws too", function () {
return Platform.Function.ContentBlockByID(1469165, "");
});
assertThrows("DEV arity 2 with a null regionName throws too", function () {
return Platform.Function.ContentBlockByID(1469165, null);
});
var varRegion = "ssjsGuideRegion";
assertThrows("DEV arity 2 with a VARIABLE regionName throws the same way (not a literal-vs-variable rule)", function () {
return Platform.Function.ContentBlockByID(1469165, varRegion);
});
/* 6. DEV stopOnError and fallbackContent are unreachable behind that rejection. */
assertThrows("DEV arity 3 stopOnError=true throws (docs: terminates on a missing block)", function () {
return Platform.Function.ContentBlockByID(12345, "ssjsGuideRegion", true);
});
assertThrows("DEV arity 3 stopOnError=false throws (docs: the call proceeds)", function () {
return Platform.Function.ContentBlockByID(12345, "ssjsGuideRegion", false);
});
assertThrows("DEV arity 4 fallbackContent never emitted, call throws (docs: fallback is displayed)", function () {
return Platform.Function.ContentBlockByID(12345, "ssjsGuideRegion", false, "FALLBACK-OK");
});
assertThrows("DEV arity 4 throws even when the block EXISTS", function () {
return Platform.Function.ContentBlockByID(1469165, "ssjsGuideRegion", false, "FALLBACK-OK");
});
assertThrows("DEV arity 3 with a null regionName throws as well", function () {
return Platform.Function.ContentBlockByID(1469165, null, false);
});
/* 7. Off-signature arities throw the overloaded security-descriptor error. */
assertThrows("arity 0 throws", function () {
return Platform.Function.ContentBlockByID();
});
assertThrows("arity 5 throws", function () {
return Platform.Function.ContentBlockByID(1469165, "ssjsGuideRegion", false, "FALLBACK-OK", "extra");
});
</script>
Description
Renders a Content Builder block by its numeric asset ID and returns its rendered body as a string. The call returns the content rather than emitting it — pass the result to Write() to place it on the page.
Prefer Platform.Function.ContentBlockByKey() as it uses the external key, which is more stable and human-readable than a numeric ID. Both forms return identical content for the same asset, and both are subject to the same single-argument restriction.
ContentBlockByID is the modern replacement for the deprecated Platform.Function.ContentArea(), whose every arity throws.
Runtime notes:
- A non-existent ID throws
An error occurred when attempting to evaluate a ContentBlockByID function call. - Passing the asset’s external key instead of its numeric ID fails — use
ContentBlockByKey()for keys. - There is no bare-name Core form:
typeof ContentBlockByIDis"undefined"even afterPlatform.Load("core", "1.1.5"), and calling it throwsObject expected: ContentBlockByID.
The official docs show the optional regionName, stopOnError and fallbackContent parameters as usable from SSJS. At runtime only the 1-argument form works; supplying regionName fails even when it is a string literal, so the remaining optional parameters are reachable only through the AMPscript form.
Show test script — only the single-argument form works from SSJS
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Differs-from-docs claim: the official Salesforce documentation shows
* Platform.Function.ContentBlockByID(12345,"impressionRegion",false,"defaultContentHere")
* as ordinary working SSJS. At runtime ONLY the single-argument form works.
*
* Official docs: the 4-argument call returns the block's content, with
* stopOnError:false letting a failed call proceed and
* fallbackContent shown when nothing is returned.
* SFMC runtime: arity 1 -> returns the block's body (works)
* arity 2/3/4 -> "A ContentBlockByID function call includes
* an invalid parameter value. … must be a
* literal (constant) values."
* Parameter Name: ImpressionRegionName
* Parameter Ordinal: 2
* Parameter Type: ResolvedValueParameter
* arity 0/5+ -> "Unable to retrieve security descriptor for
* this frame."
* (each message is printed verbatim by its assertion below)
*
* Proves every part of the claim, and — crucially — CONTROLS for the two
* competing explanations:
* 1. The 1-argument form genuinely works, so the failure at arity 2+ is
* not "the function is broken" and not "the block does not exist".
* 2. DEV arity 2 throws for a STRING LITERAL regionName in a plain
* top-level call with no closure and no variable anywhere — so the
* failure is not a literal-vs-variable rule and not an artefact of
* wrapping the call in a test helper.
* 3. DEV every other regionName shape (number, boolean, empty string,
* null, variable) fails identically, and arity 3 and 4 fail with the
* SAME parameter-2 error, which is what makes stopOnError and
* fallbackContent unreachable.
* 4. CONTROL: the AMPscript form of the same function, invoked through
* Platform.Function.TreatAsContent, accepts ALL FOUR parameters and
* returns content — proving the platform implements the documented
* semantics and that the restriction is specific to the SSJS binding.
* 5. The sibling Platform.Function.ContentBlockByKey has the identical
* restriction, so this is a family-wide SSJS binding limitation.
* 6. There is no bare-name Core escape hatch: typeof ContentBlockByID is
* "undefined" after Platform.Load and invoking it throws
* "Object expected: ContentBlockByID".
*
* SCOPE: CloudPage only — the same calls inside an email send were not
* exercised.
*
* EXPECTED OUTPUT: every line starts with PASS.
*/
function assert(id, actual, expected) {
Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
function assertThrows(id, fn) {
var threw = false, msg = "";
try { fn(); } catch (ex) { threw = true; msg = ex.message; }
Platform.Response.Write((threw ? "PASS " : "FAIL ") + id + " -> " + (threw ? "threw: " + msg : "did NOT throw") + "\n");
}
/* 1. The 1-argument form works — the function itself is not broken. */
assert("CONTROL arity 1 returns the block's body", Platform.Function.ContentBlockByID(1469165), "SSJSGUIDE-TEST-BLOCK-OK");
/* 2. DEV a top-level, closure-free, all-literal arity-2 call still throws. */
var topLevel2 = "did NOT throw";
try { Platform.Function.ContentBlockByID(1469165, "ssjsGuideRegion"); }
catch (exTop) { topLevel2 = "threw"; }
assert("DEV top-level all-literal arity 2 throws (docs: returns content)", topLevel2, "threw");
assertThrows("DEV arity 2 string literal regionName throws (message printed)", function () {
return Platform.Function.ContentBlockByID(1469165, "ssjsGuideRegion");
});
/* 3. DEV every regionName shape, and arity 3/4, fail the same way. */
assertThrows("DEV arity 2 numeric regionName throws", function () {
return Platform.Function.ContentBlockByID(1469165, 7);
});
assertThrows("DEV arity 2 boolean regionName throws", function () {
return Platform.Function.ContentBlockByID(1469165, false);
});
assertThrows("DEV arity 2 empty-string regionName throws", function () {
return Platform.Function.ContentBlockByID(1469165, "");
});
assertThrows("DEV arity 2 null regionName throws", function () {
return Platform.Function.ContentBlockByID(1469165, null);
});
var dynRegion = "ssjsGuideRegion";
assertThrows("DEV arity 2 variable regionName throws", function () {
return Platform.Function.ContentBlockByID(1469165, dynRegion);
});
assertThrows("DEV arity 3 stopOnError=true throws (docs: terminates the call)", function () {
return Platform.Function.ContentBlockByID(12345, "ssjsGuideRegion", true);
});
assertThrows("DEV arity 3 stopOnError=false throws (docs: the call proceeds)", function () {
return Platform.Function.ContentBlockByID(12345, "ssjsGuideRegion", false);
});
assertThrows("DEV arity 4 throws so fallbackContent is never emitted (docs: fallback shown)", function () {
return Platform.Function.ContentBlockByID(12345, "ssjsGuideRegion", false, "FALLBACK-OK");
});
/* 4. CONTROL — the AMPscript form implements the full documented signature. */
assert("CONTROL AMPscript arity 2 with a region returns the body", Platform.Function.TreatAsContent('%%=ContentBlockByID(1469165,"ssjsGuideRegion")=%%'), "SSJSGUIDE-TEST-BLOCK-OK");
assert("CONTROL AMPscript arity 4 returns fallbackContent for a missing block", Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"ssjsGuideRegion",false,"FALLBACK-OK")=%%'), "FALLBACK-OK");
assert("CONTROL AMPscript arity 4 ignores the fallback when the block exists", Platform.Function.TreatAsContent('%%=ContentBlockByID(1469165,"ssjsGuideRegion",false,"FALLBACK-OK")=%%'), "SSJSGUIDE-TEST-BLOCK-OK");
assert("CONTROL AMPscript arity 3 stopOnError=false yields the empty string", Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"ssjsGuideRegion",false)=%%'), "");
assertThrows("CONTROL AMPscript arity 3 stopOnError=true propagates the error", function () {
return Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"ssjsGuideRegion",true)=%%');
});
/* 5. The sibling ContentBlockByKey carries the identical restriction. */
assert("CONTROL ContentBlockByKey arity 1 works", Platform.Function.ContentBlockByKey("ssjs-guide-test-block"), "SSJSGUIDE-TEST-BLOCK-OK");
assertThrows("DEV ContentBlockByKey arity 2 throws the same ImpressionRegionName error", function () {
return Platform.Function.ContentBlockByKey("ssjs-guide-test-block", "ssjsGuideRegion");
});
/* 6. No bare-name Core escape hatch exists. */
assert("there is no bare-name ContentBlockByID global", String(typeof ContentBlockByID), "undefined");
assertThrows("invoking the bare name throws Object expected", function () {
return ContentBlockByID(1469165);
});
/* 7. Off-signature arities throw the security-descriptor error. */
assertThrows("arity 0 throws", function () {
return Platform.Function.ContentBlockByID();
});
assertThrows("arity 5 throws", function () {
return Platform.Function.ContentBlockByID(1469165, "ssjsGuideRegion", false, "FALLBACK-OK", "extra");
});
</script>
Workaround — reach the optional parameters via AMPscript
The AMPscript function of the same name accepts all four parameters. Invoke it from SSJS with Platform.Function.TreatAsContent():
// impression region — works, returns the block's body
var html = Platform.Function.TreatAsContent('%%=ContentBlockByID(1469165,"heroRegion")=%%');
// fallback content for a missing block — returns "FALLBACK" instead of throwing
var safe = Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"heroRegion",false,"FALLBACK")=%%');
// stopOnError: true — the missing block now throws through TreatAsContent
var strict = Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"heroRegion",true)=%%');
With stopOnError: false and no fallbackContent, a missing block yields the empty string.
Show test script
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Chapter: Description — renders a Content Builder block by numeric ID and
* returns it, ContentBlockByKey is the preferred alternative, this is the
* modern replacement for ContentArea, plus the runtime notes and the
* TreatAsContent workaround.
*
* Proves:
* 1. The function renders a CONTENT BUILDER asset: the value returned for
* id 1469165 is exactly that asset's stored body, and it is a
* non-empty string. The call RETURNS the content rather than emitting
* it.
* 2. The identifier really is the numeric asset ID — passing the asset's
* external KEY throws the security-descriptor error, which is what
* distinguishes it from ContentBlockByKey.
* 3. The recommended alternative works and is interchangeable for this
* asset: ContentBlockByKey("ssjs-guide-test-block") resolves as a host
* method and returns the SAME body.
* 4. It is the working replacement for the deprecated ContentArea family:
* Platform.Function.ContentArea throws where this returns content.
* 5. The runtime notes: a non-existent id throws, arity 0 and arity 5+
* throw the security-descriptor error, and there is NO bare-name Core
* form (typeof "undefined"; invoking it throws "Object expected").
* 6. The WORKAROUND section, end to end — every optional parameter that
* SSJS rejects is reachable through the AMPscript form via
* Platform.Function.TreatAsContent:
* - a named impression region returns the body,
* - fallbackContent is returned for a missing block,
* - stopOnError:true propagates the error,
* - stopOnError:false without a fallback yields the empty string.
*
* SCOPE: CloudPage only — rendering the same block inside an email send was
* not exercised, and whether the impression region is actually recorded is
* not observable from inside this request.
*
* EXPECTED OUTPUT: every line starts with PASS.
*/
function assert(id, actual, expected) {
Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
function assertThrows(id, fn) {
var threw = false, msg = "";
try { fn(); } catch (ex) { threw = true; msg = ex.message; }
Platform.Response.Write((threw ? "PASS " : "FAIL ") + id + " -> " + (threw ? "threw: " + msg : "did NOT throw") + "\n");
}
/* 1. It renders and RETURNS the Content Builder asset's stored body. */
var byId = Platform.Function.ContentBlockByID(1469165);
assert("the numeric id renders the Content Builder asset's body", byId, "SSJSGUIDE-TEST-BLOCK-OK");
assert("the returned value is a non-empty string", (typeof byId === "string" && byId !== "") ? "true" : "false", "true");
/* 2. The identifier is the numeric ID — the external key is not accepted. */
assertThrows("passing the external key to ContentBlockByID throws", function () {
return Platform.Function.ContentBlockByID("ssjs-guide-test-block");
});
/* 3. The preferred alternative resolves and returns the same body. */
assert("typeof Platform.Function.ContentBlockByKey is clrmethodinfo", String(typeof Platform.Function.ContentBlockByKey), "clrmethodinfo");
var byKey = Platform.Function.ContentBlockByKey("ssjs-guide-test-block");
assert("ContentBlockByKey returns the same body for the same asset", byKey, "SSJSGUIDE-TEST-BLOCK-OK");
assert("both forms agree", byId === byKey ? "true" : "false", "true");
/* 4. Unlike the deprecated ContentArea family, this one returns content. */
assertThrows("the deprecated Platform.Function.ContentArea throws where this works", function () {
return Platform.Function.ContentArea(1469165);
});
/* 5. The runtime notes. */
assertThrows("a non-existent id throws", function () {
return Platform.Function.ContentBlockByID(12345);
});
assertThrows("arity 0 throws the security-descriptor error", function () {
return Platform.Function.ContentBlockByID();
});
assertThrows("arity 5 throws the security-descriptor error", function () {
return Platform.Function.ContentBlockByID(1469165, "r", false, "fb", "extra");
});
assert("there is no bare-name Core form", String(typeof ContentBlockByID), "undefined");
assertThrows("invoking the bare name throws Object expected", function () {
return ContentBlockByID(1469165);
});
/* 6. The workaround — all four parameters reachable through AMPscript. */
assert("workaround: a named impression region returns the body", Platform.Function.TreatAsContent('%%=ContentBlockByID(1469165,"heroRegion")=%%'), "SSJSGUIDE-TEST-BLOCK-OK");
assert("workaround: fallbackContent is returned for a missing block", Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"heroRegion",false,"FALLBACK")=%%'), "FALLBACK");
assertThrows("workaround: stopOnError=true propagates the error", function () {
return Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"heroRegion",true)=%%');
});
assert("workaround: stopOnError=false with no fallback yields the empty string", Platform.Function.TreatAsContent('%%=ContentBlockByID(12345,"heroRegion",false)=%%'), "");
</script>
Example
var blockHtml = Platform.Function.ContentBlockByID(1469165);
Write(blockHtml);
The single argument may be a number, a numeric string or a variable — all three resolve the same asset:
var id = 1469165;
Platform.Function.ContentBlockByID(1469165); // number
Platform.Function.ContentBlockByID("1469165"); // numeric string
Platform.Function.ContentBlockByID(id); // variable
Show test script
<script runat="server">
Platform.Load("core", "1.1.5");
/*
* Chapter: Example —
* var blockHtml = Platform.Function.ContentBlockByID(1469165);
* Write(blockHtml);
* plus the number / numeric-string / variable trio.
*
* Proves the documented example's shape:
* 1. The documented pattern works verbatim: the call assigns a string to
* the variable and that string is the block's body.
* 2. The bare-name Write() global used by the example is available after
* Platform.Load("core", "1.1.5") and emits its argument unchanged —
* writing the block's body reproduces it exactly in the response.
* 3. All three documented single-argument shapes resolve the same asset:
* a number literal, a numeric string, and a variable.
* 4. The call itself emits nothing — the content only reaches the page
* because the example passes the returned value to Write().
*
* SCOPE: CloudPage only. Write() in an email-send context was not
* exercised.
*
* EXPECTED OUTPUT: every line starts with PASS, except the single
* WRITE-PROBE line between the assertions, which IS the raw Write() output
* being proven in point 2 and reads
* WRITE-PROBE-START SSJSGUIDE-TEST-BLOCK-OK WRITE-PROBE-END.
*/
function assert(id, actual, expected) {
Platform.Response.Write((actual === expected ? "PASS " : "FAIL ") + id + " -> [" + actual + "]\n");
}
/* 1. The documented pattern. */
var blockHtml = Platform.Function.ContentBlockByID(1469165);
assert("the example's variable receives a string", String(typeof blockHtml), "string");
assert("the example's variable holds the block's body", blockHtml, "SSJSGUIDE-TEST-BLOCK-OK");
/* 2. The bare-name Write() global from the example is available and faithful. */
assert("typeof the bare-name Write is function after Platform.Load", String(typeof Write), "function");
Platform.Response.Write("WRITE-PROBE-START ");
Write(blockHtml);
Platform.Response.Write(" WRITE-PROBE-END\n");
/* 3. Number, numeric string and variable all resolve the same asset. */
var id = 1469165;
assert("number literal id resolves the asset", Platform.Function.ContentBlockByID(1469165), "SSJSGUIDE-TEST-BLOCK-OK");
assert("numeric string id resolves the asset", Platform.Function.ContentBlockByID("1469165"), "SSJSGUIDE-TEST-BLOCK-OK");
assert("variable id resolves the asset", Platform.Function.ContentBlockByID(id), "SSJSGUIDE-TEST-BLOCK-OK");
/* 4. The call returns the content rather than emitting it. */
var emitted = Platform.Function.ContentBlockByID(1469165);
assert("the call returns the content rather than emitting it", emitted, "SSJSGUIDE-TEST-BLOCK-OK");
</script>