ampscript-data 3.7.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1028 @@
1
+ // AUTO-SPLIT from the original single-file src/index.js. Data moved verbatim.
2
+ // AMPscript FUNCTIONS — category: Content (21 entries).
3
+
4
+ import { INF } from '../constants.js';
5
+
6
+ export const CONTENT_FUNCTIONS = [
7
+ {
8
+ name: 'AttachFile',
9
+ supportedInCloudPage: false,
10
+ supportedInEmail: false,
11
+ mcnSince: null,
12
+ handlebarsEquivalent: null,
13
+ mcnNotes: null,
14
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-attach-file.html',
15
+ guideUrl: 'https://ampscript.guide/attachfile/',
16
+ minArgs: 2,
17
+ maxArgs: 8,
18
+ category: 'Content',
19
+ description: 'Includes a file attachment in the outgoing message.',
20
+ params: [
21
+ {
22
+ name: 'fileLocationType',
23
+ description:
24
+ 'The type of location to pull the file from. Accepted values: http, ftp, contentbuilder',
25
+ type: 'string',
26
+ enum: ['http', 'ftp', 'contentbuilder'],
27
+ },
28
+ {
29
+ name: 'fileLocation',
30
+ description:
31
+ 'The location to pull the file from. This parameter can contain a maximum of 2088 characters. If you specify http for the first parameter, this parameter must contain a URL. If you specify ftp for the first parameter, this parameter must contain the name of a file in the Import folder of your Enhanced FTP site. If you specify contentbuilder for the first parameter, this parameter must contain the external key of the file to attach.',
32
+ type: 'string',
33
+ },
34
+ {
35
+ name: 'attachmentFileName',
36
+ description:
37
+ "The name assigned to a file when it's attached to an email message. If you don't specify a new name, the function uses the original file name. If you specify http for the first parameter and don't provide a value for this parameter, the function uses the Content-Disposition information from the HTTP header. If the server providing the file doesn't provide Content-Disposition information, the function uses an auto-generated value.",
38
+ type: 'string',
39
+ optional: true,
40
+ },
41
+ {
42
+ name: 'viewOnWeb',
43
+ description:
44
+ 'If `true` or `1`, a link to the file is included when a recipient selects the "View as a Web Page" link in the email. If `false` or `0`, the link is omitted. You can only use this parameter if the value of the first parameter is `http`.',
45
+ type: 'boolean',
46
+ optional: true,
47
+ },
48
+ {
49
+ name: 'viewOnWebUrl',
50
+ description:
51
+ 'The URL to use when including a link to the file in the "View as a Web Page" context. If the value of `viewOnWeb` is true, you must provide a value for this parameter. You can only use this parameter if the value of the first parameter is `http`.',
52
+ type: 'string',
53
+ optional: true,
54
+ },
55
+ {
56
+ name: 'viewOnWebFileName',
57
+ description:
58
+ 'The file name to use when including a link to the file in the "View as a Web Page" context. You can only use this parameter if the value of the first parameter is `http`.',
59
+ type: 'string',
60
+ optional: true,
61
+ },
62
+ {
63
+ name: 'viewOnWebDuration',
64
+ description:
65
+ 'The number of days the link appears in the "View as a Web Page" context. You can only use this parameter if the value of the first parameter is `http`.',
66
+ type: 'number',
67
+ optional: true,
68
+ },
69
+ {
70
+ name: 'contentDispositionAttachment',
71
+ description:
72
+ 'If `true` or `1`, the function changes the value of the `content-disposition` header for the attachment to `attachment`. If `false` or `0`, the value of this header is set to `inline`.',
73
+ type: 'boolean',
74
+ optional: true,
75
+ },
76
+ ],
77
+ returnType: 'void',
78
+ returnDescription: 'No value is returned; the file is attached to the outgoing email.',
79
+ syntax: 'AttachFile(fileLocationType, fileLocation, attachmentFileName, viewOnWeb, viewOnWebUrl, viewOnWebFileName, viewOnWebDuration, contentDispositionAttachment)',
80
+ example: "%%=AttachFile('http', 'https://example.com/catalog.pdf', 'Catalog.pdf')=%%",
81
+ isConfirmed: false,
82
+ verificationBlocked: true,
83
+ verificationBlockedReason: 'no-working-invocation',
84
+ officialDocsNote:
85
+ 'AttachFile targets the outgoing email at send time; it has no working invocation on a CloudPage. Every reached call — contentbuilder key, http URL, and the two-argument minimum form — aborted the page with HTTP 422 and no partial output, on the child BU and again on the parent BU. The abort only happens when the call is actually reached: gating it behind an unmatched query-string branch leaves the page at HTTP 200, so the failure is a runtime abort of the reached call rather than a compile-time rejection. An email-context render on the child BU sharpened the cause: the Email Preview API recognises and evaluates the function and fails with a precise message that the EMAIL_ATTACHMENTS business rule must be turned on before AttachFile can be used, so the block is an account-level provisioning gate rather than a broken function.',
86
+ },
87
+ {
88
+ name: 'BarcodeURL',
89
+ supportedInCloudPage: true,
90
+ supportedInEmail: true,
91
+ mcnSince: null,
92
+ handlebarsEquivalent: null,
93
+ mcnNotes: null,
94
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-barcode-url.html',
95
+ guideUrl: 'https://ampscript.guide/barcodeurl/',
96
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/barcodeurl/',
97
+ minArgs: 4,
98
+ maxArgs: 9,
99
+ category: 'Content',
100
+ description:
101
+ 'Generates a URL that renders a barcode image from the given value, symbology, width, and height, plus optional formatting. An empty value aborts the page instead of returning an empty result.',
102
+ params: [
103
+ {
104
+ name: 'valueToConvert',
105
+ description: 'Data to convert into a barcode',
106
+ type: 'string',
107
+ },
108
+ {
109
+ name: 'barcodeType',
110
+ description: 'Type of barcode to generate',
111
+ type: 'string',
112
+ enum: [
113
+ 'codabar',
114
+ 'code11',
115
+ 'code128auto',
116
+ 'code128a',
117
+ 'code128b',
118
+ 'code128c',
119
+ 'code39',
120
+ 'code39ext',
121
+ 'code93',
122
+ 'code93ext',
123
+ 'datamatrix',
124
+ 'ean13',
125
+ 'ean8',
126
+ 'industr25',
127
+ 'interl25',
128
+ 'msi',
129
+ 'pdf417',
130
+ 'upca',
131
+ 'upce',
132
+ ],
133
+ },
134
+ { name: 'width', description: 'Barcode image width in pixels', type: 'number' },
135
+ { name: 'height', description: 'Barcode image height in pixels', type: 'number' },
136
+ {
137
+ name: 'checksumValue',
138
+ description: 'Checksum value for barcode',
139
+ type: 'string',
140
+ optional: true,
141
+ },
142
+ {
143
+ name: 'showText',
144
+ description:
145
+ "If `true` or `1`, the function includes the text of `valueToConvert` under the barcode. If `false` or `0`, the function doesn't include the text of `valueToConvert` under the barcode. The default value is `false`.",
146
+ type: 'boolean',
147
+ optional: true,
148
+ },
149
+ {
150
+ name: 'altText',
151
+ description: 'Alternate text to display under the barcode if `showText` is `false`',
152
+ type: 'string',
153
+ optional: true,
154
+ },
155
+ {
156
+ name: 'rotation',
157
+ description: 'Orientation of barcode in degrees',
158
+ type: 'number',
159
+ enum: [0, 90, 180, 270],
160
+ optional: true,
161
+ },
162
+ {
163
+ name: 'transparentBG',
164
+ description:
165
+ 'If `true` or `1`, the barcode includes a transparent background. Otherwise, the background is white. The default value is `false`.',
166
+ type: 'boolean',
167
+ optional: true,
168
+ },
169
+ ],
170
+ returnType: 'string',
171
+ returnDescription: 'A URL that renders the requested barcode image.',
172
+ syntax: 'BarcodeURL(valueToConvert, barcodeType, width, height, checksumValue, showText, altText, rotation, transparentBG)',
173
+ example: "<img src=\"%%=BarcodeURL('12345678901', 'code128auto', 150, 50)=%%\">",
174
+ isConfirmed: true,
175
+ differsFromOfficialDocs: false,
176
+ },
177
+ {
178
+ name: 'BeginImpressionRegion',
179
+ supportedInCloudPage: true,
180
+ supportedInEmail: true,
181
+ mcnSince: null,
182
+ handlebarsEquivalent: null,
183
+ mcnNotes: null,
184
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-begin-impression-region.html',
185
+ guideUrl: 'https://ampscript.guide/beginimpressionregion/',
186
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/beginimpressionregion/',
187
+ minArgs: 1,
188
+ maxArgs: 1,
189
+ isConfirmed: true,
190
+ differsFromOfficialDocs: false,
191
+ category: 'Content',
192
+ description:
193
+ 'Marks the start of an impression tracking region. The region name must be a literal — a variable argument aborts the page.',
194
+ params: [{ name: 'regionName', description: 'Impression region name', type: 'string' }],
195
+ returnType: 'void',
196
+ returnDescription: 'No value is returned; it marks the start of an impression region.',
197
+ syntax: 'BeginImpressionRegion(regionName)',
198
+ example: "BeginImpressionRegion('Region A')",
199
+ },
200
+ {
201
+ name: 'BuildOptionList',
202
+ supportedInCloudPage: true,
203
+ supportedInEmail: true,
204
+ mcnSince: null,
205
+ handlebarsEquivalent: null,
206
+ mcnNotes: null,
207
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-build-option-list.html',
208
+ guideUrl: 'https://ampscript.guide/buildoptionlist/',
209
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/buildoptionlist/',
210
+ minArgs: 3,
211
+ maxArgs: INF,
212
+ category: 'Content',
213
+ description:
214
+ 'Builds HTML <option> elements from supplied value/text pairs for use in a <select> dropdown, marking the pair whose value matches the default selection as selected.',
215
+ params: [
216
+ {
217
+ name: 'defaultSelection',
218
+ mcnSince: null,
219
+ mcnNotes: null,
220
+ description: 'The option that is selected by default',
221
+ type: 'string|number',
222
+ },
223
+ {
224
+ name: 'option1Value',
225
+ description:
226
+ 'An identifier for the first option. The function sets the `value` parameter in the `<option>` tag to this value.',
227
+ type: 'string',
228
+ },
229
+ {
230
+ name: 'option1Text',
231
+ description: 'The display text for the option tag.',
232
+ type: 'string',
233
+ },
234
+ {
235
+ name: 'optionValueN',
236
+ description:
237
+ 'An identifier for an additional option. The function sets the `value` parameter in the `<option>` tag to this value.',
238
+ type: 'string',
239
+ optional: true,
240
+ },
241
+ {
242
+ name: 'optionTextN',
243
+ description: 'The display text for the additional option tag.',
244
+ type: 'string',
245
+ optional: true,
246
+ },
247
+ ],
248
+ returnType: 'string',
249
+ returnDescription: 'An HTML string of option elements built from the supplied values.',
250
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
251
+ syntax: 'BuildOptionList(defaultSelection, option1Value, option1Text[, optionValueN, optionTextN, ...])',
252
+ example:
253
+ '%%[\n' +
254
+ 'set @DefaultOption = 2\n' +
255
+ 'set @OptionList = BuildOptionList(@DefaultOption, "1", "Option A", "2", "Option B", "3", "Option C")\n' +
256
+ ']%%\n' +
257
+ '<p>Choose an option:</p>\n' +
258
+ '<select name="choice">\n%%=v(@OptionList)=%%\n</select>',
259
+ isConfirmed: true,
260
+ differsFromOfficialDocs: false,
261
+ },
262
+ {
263
+ name: 'BuildRowsetFromJSON',
264
+ supportedInCloudPage: true,
265
+ supportedInEmail: true,
266
+ mcnSince: 67,
267
+ handlebarsEquivalent: 'jsonPath',
268
+ handlebarsExact: false,
269
+ mcnNotes: null,
270
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-build-rowset-from-json.html',
271
+ guideUrl: 'https://ampscript.guide/buildrowsetfromjson/',
272
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/buildrowsetfromjson/',
273
+ minArgs: 3,
274
+ maxArgs: 3,
275
+ category: 'Content',
276
+ description: 'Parses a JSON string and returns a rowset.',
277
+ params: [
278
+ {
279
+ name: 'jsonData',
280
+ description: 'The JSON data that you want to parse',
281
+ type: 'string',
282
+ },
283
+ {
284
+ name: 'jsonPathExpression',
285
+ mcnSince: null,
286
+ mcnNotes: null,
287
+ description: 'The JSONPath expression that parses the source data',
288
+ type: 'string',
289
+ },
290
+ {
291
+ name: 'returnEmptyOnError',
292
+ mcnSince: null,
293
+ mcnNotes: null,
294
+ description:
295
+ 'Pass 1 or true to get an empty rowset when the payload or path cannot be parsed; 0 or false makes the same input abort the page',
296
+ type: 'boolean|number',
297
+ },
298
+ ],
299
+ returnType: 'rowset',
300
+ returnDescription:
301
+ 'A rowset built from the matched JSON nodes. A path that matches nothing yields a rowset with zero rows rather than an error.',
302
+ syntax: 'BuildRowsetFromJSON(jsonData, jsonPathExpression, returnEmptyOnError)',
303
+ example: "%%[ SET @rows = BuildRowsetFromJSON(@json, '$.items[*]', 1) ]%%",
304
+ isConfirmed: true,
305
+ differsFromOfficialDocs: true,
306
+ officialDocsNote:
307
+ 'The official syntax section states that a false third argument yields an empty rowset and a true one raises an exception; runtime on the child BU (CloudPage GET) does the opposite. Malformed JSON with 1 rendered a rowset of zero rows, while the identical payload with 0 aborted the page with HTTP 422. The same page also proved that an unparsable payload, an unset variable, an empty string, [] and a path matching nothing all yield zero rows when 1 is passed. Note the official Errors section already describes the runtime ordering, so the page contradicts itself.',
308
+ },
309
+ {
310
+ name: 'BuildRowSetFromString',
311
+ supportedInCloudPage: true,
312
+ supportedInEmail: true,
313
+ mcnSince: null,
314
+ handlebarsEquivalent: null,
315
+ mcnNotes: null,
316
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-build-rowset-from-string.html',
317
+ guideUrl: 'https://ampscript.guide/buildrowsetfromstring/',
318
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/buildrowsetfromstring/',
319
+ minArgs: 2,
320
+ maxArgs: 2,
321
+ category: 'Content',
322
+ description: 'Splits a delimited string into a single-column rowset.',
323
+ params: [
324
+ {
325
+ name: 'sourceData',
326
+ description: 'A string that contains the data to load into a rowset',
327
+ type: 'string',
328
+ },
329
+ {
330
+ name: 'delimiter',
331
+ description:
332
+ 'The separator to split on; it may be several characters long, and an empty separator leaves the input as a single row',
333
+ type: 'string',
334
+ },
335
+ ],
336
+ returnType: 'rowset',
337
+ returnDescription:
338
+ 'A rowset where each row holds one delimited segment of the input string. The single column has no name, so read it with Field(row, 1). An empty or unset input gives zero rows.',
339
+ syntax: 'BuildRowSetFromString(sourceData, delimiter)',
340
+ example: "%%=BuildRowSetFromString('a,b,c', ',')=%%",
341
+ isConfirmed: true,
342
+ differsFromOfficialDocs: false,
343
+ },
344
+ {
345
+ name: 'BuildRowSetFromXML',
346
+ supportedInCloudPage: true,
347
+ supportedInEmail: true,
348
+ mcnSince: null,
349
+ handlebarsEquivalent: null,
350
+ mcnNotes: null,
351
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-build-rowset-from-xml.html',
352
+ guideUrl: 'https://ampscript.guide/buildrowsetfromxml/',
353
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/buildrowsetfromxml/',
354
+ minArgs: 3,
355
+ maxArgs: 3,
356
+ category: 'Content',
357
+ description: 'Parses an XML string using an XPath expression and returns a rowset.',
358
+ params: [
359
+ { name: 'xmlData', description: 'The XML data that you want to parse', type: 'string' },
360
+ {
361
+ name: 'xpathExpression',
362
+ description: 'The XPath expression that parses the source data',
363
+ type: 'string',
364
+ },
365
+ {
366
+ name: 'returnEmptyOnError',
367
+ mcnSince: null,
368
+ mcnNotes: null,
369
+ description:
370
+ 'Pass 1 or true to get an empty rowset when the payload or path cannot be parsed; 0 or false makes the same input abort the page',
371
+ type: 'boolean|number',
372
+ },
373
+ ],
374
+ returnType: 'rowset',
375
+ returnDescription:
376
+ 'A rowset built from the matched XML nodes, with a Value column, an Xml column holding the inner markup, and one <attribute>_att column per attribute seen on any matched node. An XPath that matches nothing yields zero rows rather than an error.',
377
+ syntax: 'BuildRowSetFromXML(xmlData, xpathExpression, returnEmptyOnError)',
378
+ example: "%%[ SET @rows = BuildRowSetFromXML(@xml, '/root/item', 1) ]%%",
379
+ isConfirmed: true,
380
+ differsFromOfficialDocs: true,
381
+ officialDocsNote:
382
+ 'The official syntax section states that a false third argument yields an empty rowset and a true one raises an exception; runtime on the child BU (CloudPage GET) behaves the other way round. Unclosed XML parsed with 1 rendered a rowset of zero rows, whereas the identical payload with 0 aborted the page with HTTP 422. An empty string, an unset variable, an empty root element and an XPath matching nothing likewise gave zero rows under 1.',
383
+ },
384
+ {
385
+ name: 'ContentArea',
386
+ supportedInCloudPage: true,
387
+ supportedInEmail: true,
388
+ mcnSince: null,
389
+ handlebarsEquivalent: null,
390
+ mcnNotes: null,
391
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-area.html',
392
+ guideUrl: 'https://ampscript.guide/contentarea/',
393
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentarea/',
394
+ minArgs: 1,
395
+ maxArgs: 5,
396
+ category: 'Content',
397
+ description: 'Inserts a classic content area by its numeric ID.',
398
+ params: [
399
+ {
400
+ name: 'contentAreaId',
401
+ mcnSince: null,
402
+ mcnNotes: null,
403
+ description: 'The ID of the content area to retrieve',
404
+ type: 'number|string',
405
+ },
406
+ {
407
+ name: 'impressionRegionName',
408
+ mcnSince: null,
409
+ mcnNotes: null,
410
+ description: 'The name of the impression region to associate with the content area',
411
+ type: 'string',
412
+ optional: true,
413
+ },
414
+ {
415
+ name: 'errorOnMissingContentArea',
416
+ mcnSince: null,
417
+ mcnNotes: null,
418
+ description:
419
+ "Determines whether the function returns an error when the system can't locate the specified content area or returns an invalid content area. A value of true returns an error. Defaults to true.",
420
+ type: 'boolean',
421
+ optional: true,
422
+ default: true,
423
+ },
424
+ {
425
+ name: 'errorMessage',
426
+ mcnSince: null,
427
+ mcnNotes: null,
428
+ description:
429
+ 'Default content to return if an error occurs. This value is emitted literally - any AMPscript it contains is not evaluated.',
430
+ type: 'string',
431
+ optional: true,
432
+ },
433
+ {
434
+ name: 'statusCode',
435
+ mcnSince: null,
436
+ mcnNotes: null,
437
+ description:
438
+ 'An output variable that contains the exit code of the function. A value of 0 indicates the function found the content area and successfully rendered the content. A value of -1 indicates either no content or an invalid content area.',
439
+ type: 'number',
440
+ optional: true,
441
+ },
442
+ ],
443
+ returnType: 'string',
444
+ returnDescription: 'The rendered HTML of the referenced content area.',
445
+ syntax: 'ContentArea(contentAreaId[, impressionRegionName, errorOnMissingContentArea, errorMessage, statusCode])',
446
+ example: '%%=ContentArea(12345)=%%',
447
+ isConfirmed: true,
448
+ differsFromOfficialDocs: false,
449
+ deprecated: true,
450
+ deprecatedReplacement: 'ContentBlockByID',
451
+ deprecatedReason:
452
+ 'ContentArea references classic content areas, which are no longer supported. Use Content Builder content blocks instead.',
453
+ },
454
+ {
455
+ name: 'ContentAreaByName',
456
+ supportedInCloudPage: true,
457
+ supportedInEmail: true,
458
+ mcnSince: null,
459
+ handlebarsEquivalent: null,
460
+ mcnNotes: null,
461
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-area-by-name.html',
462
+ guideUrl: 'https://ampscript.guide/contentareabyname/',
463
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentareabyname/',
464
+ minArgs: 1,
465
+ maxArgs: 5,
466
+ category: 'Content',
467
+ description: 'Inserts a classic content area by its folder path and name.',
468
+ params: [
469
+ {
470
+ name: 'contentAreaName',
471
+ description: 'The name of the content area to retrieve',
472
+ type: 'string',
473
+ },
474
+ {
475
+ name: 'impressionRegionName',
476
+ mcnSince: null,
477
+ mcnNotes: null,
478
+ description: 'The name of the impression region to associate with the content area',
479
+ type: 'string',
480
+ optional: true,
481
+ },
482
+ {
483
+ name: 'errorOnMissingContentArea',
484
+ mcnSince: null,
485
+ mcnNotes: null,
486
+ description:
487
+ "Determines whether the function returns an error when the system can't locate the specified content area or returns an invalid content area. A value of true returns an error. Defaults to true.",
488
+ type: 'boolean',
489
+ optional: true,
490
+ default: true,
491
+ },
492
+ {
493
+ name: 'errorMessage',
494
+ mcnSince: null,
495
+ mcnNotes: null,
496
+ description:
497
+ 'Default content to return if an error occurs. This value is emitted literally - any AMPscript it contains is not evaluated.',
498
+ type: 'string',
499
+ optional: true,
500
+ },
501
+ {
502
+ name: 'statusCode',
503
+ mcnSince: null,
504
+ mcnNotes: null,
505
+ description:
506
+ 'An output variable that contains the exit code of the function. A value of 0 indicates the function found the content area and successfully rendered the content. A value of -1 indicates either no content or an invalid content area.',
507
+ type: 'number',
508
+ optional: true,
509
+ },
510
+ ],
511
+ returnType: 'string',
512
+ returnDescription: 'The rendered HTML of the named content area.',
513
+ syntax: 'ContentAreaByName(contentAreaName[, impressionRegionName, errorOnMissingContentArea, errorMessage, statusCode])',
514
+ example: String.raw`%%=ContentAreaByName('My Folder\My Content')=%%`,
515
+ isConfirmed: true,
516
+ differsFromOfficialDocs: false,
517
+ deprecated: true,
518
+ deprecatedReplacement: 'ContentBlockByName',
519
+ deprecatedReason:
520
+ 'ContentAreaByName references classic content areas, which are no longer supported. Use Content Builder content blocks instead.',
521
+ },
522
+ {
523
+ name: 'ContentBlockByID',
524
+ supportedInCloudPage: true,
525
+ supportedInEmail: true,
526
+ mcnSince: 67,
527
+ handlebarsEquivalent: null,
528
+ mcnNotes: null,
529
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-block-by-id.html',
530
+ guideUrl: 'https://ampscript.guide/contentblockbyid/',
531
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentblockbyid/',
532
+ minArgs: 1,
533
+ maxArgs: 5,
534
+ category: 'Content',
535
+ description: 'Retrieves and renders a Content Builder content block by its numeric ID.',
536
+ params: [
537
+ {
538
+ name: 'contentBlockId',
539
+ description: 'The ID of the content block to retrieve',
540
+ type: 'number|string',
541
+ },
542
+ {
543
+ name: 'impressionRegionName',
544
+ mcnSince: null,
545
+ mcnNotes: null,
546
+ description:
547
+ 'The name of the impression region to associate with the content block',
548
+ type: 'string',
549
+ optional: true,
550
+ },
551
+ {
552
+ name: 'errorOnMissingContentBlock',
553
+ mcnSince: null,
554
+ mcnNotes: null,
555
+ description:
556
+ "If true, the function returns an error if the content block can't be found. If false, the function doesn't return an error. The default value is true",
557
+ type: 'boolean',
558
+ optional: true,
559
+ default: true,
560
+ },
561
+ {
562
+ name: 'errorMessage',
563
+ mcnSince: null,
564
+ mcnNotes: null,
565
+ description:
566
+ 'Default content to return if an error occurs. This value is emitted literally - any AMPscript it contains is not evaluated.',
567
+ type: 'string',
568
+ optional: true,
569
+ },
570
+ {
571
+ name: 'statusCode',
572
+ mcnSince: null,
573
+ mcnNotes: null,
574
+ description:
575
+ 'The exit code of the function. A value of 0 indicates the function found the content block and successfully rendered the content. A value of -1 indicates either no content or an invalid content block.',
576
+ type: 'number',
577
+ optional: true,
578
+ },
579
+ ],
580
+ returnType: 'string',
581
+ returnDescription: 'The rendered HTML of the content block identified by ID.',
582
+ syntax: 'ContentBlockByID(contentBlockId[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode])',
583
+ example: '%%=ContentBlockByID(12345)=%%',
584
+ isConfirmed: true,
585
+ differsFromOfficialDocs: false,
586
+ },
587
+ {
588
+ name: 'ContentBlockByKey',
589
+ supportedInCloudPage: true,
590
+ supportedInEmail: true,
591
+ mcnSince: 67,
592
+ handlebarsEquivalent: 'getContentBlock',
593
+ handlebarsExact: false,
594
+ mcnNotes: null,
595
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-block-by-key.html',
596
+ guideUrl: 'https://ampscript.guide/contentblockbykey/',
597
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentblockbykey/',
598
+ minArgs: 1,
599
+ maxArgs: 5,
600
+ category: 'Content',
601
+ description: 'Retrieves and renders a Content Builder content block by its customer key.',
602
+ params: [
603
+ {
604
+ name: 'contentBlockKey',
605
+ description: 'The key of the content block to retrieve',
606
+ type: 'string',
607
+ },
608
+ {
609
+ name: 'impressionRegionName',
610
+ mcnSince: null,
611
+ mcnNotes: null,
612
+ description:
613
+ 'The name of the impression region to associate with the content block',
614
+ type: 'string',
615
+ optional: true,
616
+ },
617
+ {
618
+ name: 'errorOnMissingContentBlock',
619
+ mcnSince: null,
620
+ mcnNotes: null,
621
+ description:
622
+ "If true, the function returns an error if the content block can't be found. If false, the function doesn't return an error. The default value is true",
623
+ type: 'boolean',
624
+ optional: true,
625
+ default: true,
626
+ },
627
+ {
628
+ name: 'errorMessage',
629
+ mcnSince: null,
630
+ mcnNotes: null,
631
+ description:
632
+ 'Default content to return if an error occurs. This value is emitted literally - any AMPscript it contains is not evaluated.',
633
+ type: 'string',
634
+ optional: true,
635
+ },
636
+ {
637
+ name: 'statusCode',
638
+ mcnSince: null,
639
+ mcnNotes: null,
640
+ description:
641
+ 'The exit code of the function. A value of 0 indicates the function found the content block and successfully rendered the content. A value of -1 indicates either no content or an invalid content block.',
642
+ type: 'number',
643
+ optional: true,
644
+ },
645
+ ],
646
+ returnType: 'string',
647
+ returnDescription: 'The rendered HTML of the content block identified by customer key.',
648
+ syntax: 'ContentBlockByKey(contentBlockKey[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode])',
649
+ example: "%%=ContentBlockByKey('welcome-header')=%%",
650
+ isConfirmed: true,
651
+ differsFromOfficialDocs: false,
652
+ },
653
+ {
654
+ name: 'ContentBlockByName',
655
+ supportedInCloudPage: true,
656
+ supportedInEmail: true,
657
+ mcnSince: 67,
658
+ handlebarsEquivalent: null,
659
+ mcnNotes: null,
660
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-block-by-name.html',
661
+ guideUrl: 'https://ampscript.guide/contentblockbyname/',
662
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentblockbyname/',
663
+ minArgs: 1,
664
+ maxArgs: 5,
665
+ category: 'Content',
666
+ description:
667
+ 'Retrieves and renders a Content Builder content block by its folder path and name.',
668
+ params: [
669
+ {
670
+ name: 'contentBlockName',
671
+ description: 'The full path of the content block to retrieve',
672
+ type: 'string',
673
+ },
674
+ {
675
+ name: 'impressionRegionName',
676
+ mcnSince: null,
677
+ mcnNotes: null,
678
+ description:
679
+ 'The name of the impression region to associate with the content block',
680
+ type: 'string',
681
+ optional: true,
682
+ },
683
+ {
684
+ name: 'errorOnMissingContentBlock',
685
+ mcnSince: null,
686
+ mcnNotes: null,
687
+ description:
688
+ "If true, the function returns an error if the content block can't be found. If false, the function doesn't return an error. The default value is true",
689
+ type: 'boolean',
690
+ optional: true,
691
+ default: true,
692
+ },
693
+ {
694
+ name: 'errorMessage',
695
+ mcnSince: null,
696
+ mcnNotes: null,
697
+ description:
698
+ 'Default content to return if an error occurs. This value is emitted literally - any AMPscript it contains is not evaluated.',
699
+ type: 'string',
700
+ optional: true,
701
+ },
702
+ {
703
+ name: 'statusCode',
704
+ mcnSince: null,
705
+ mcnNotes: null,
706
+ description:
707
+ 'The exit code of the function. A value of 0 indicates the function found the content block and successfully rendered the content. A value of -1 indicates either no content or an invalid content block.',
708
+ type: 'number',
709
+ optional: true,
710
+ },
711
+ ],
712
+ returnType: 'string',
713
+ returnDescription: 'The rendered HTML of the content block identified by name or path.',
714
+ syntax: 'ContentBlockByName(contentBlockName[, impressionRegionName, errorOnMissingContentBlock, errorMessage, statusCode])',
715
+ example: String.raw`%%=ContentBlockByName('My Folder\Welcome Header')=%%`,
716
+ isConfirmed: true,
717
+ differsFromOfficialDocs: false,
718
+ },
719
+ {
720
+ name: 'ContentImageByID',
721
+ supportedInCloudPage: true,
722
+ supportedInEmail: true,
723
+ mcnSince: null,
724
+ handlebarsEquivalent: null,
725
+ mcnNotes: null,
726
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-image-by-id.html',
727
+ guideUrl: 'https://ampscript.guide/contentimagebyid/',
728
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentimagebyid/',
729
+ minArgs: 1,
730
+ maxArgs: 2,
731
+ category: 'Content',
732
+ description:
733
+ 'Returns an HTML img tag for a Content Builder image asset by its numeric ID. A missing image with no fallback aborts the page.',
734
+ params: [
735
+ {
736
+ name: 'id',
737
+ description: 'The ID of an image in Content Builder',
738
+ type: 'number|string',
739
+ },
740
+ {
741
+ name: 'defaultImageExternalId',
742
+ mcnSince: null,
743
+ mcnNotes: null,
744
+ description:
745
+ "The ID of a fallback image in Content Builder. The function uses this image if it can't find the image that you specified in the first parameter",
746
+ type: 'number|string',
747
+ optional: true,
748
+ },
749
+ ],
750
+ returnType: 'string',
751
+ returnDescription:
752
+ 'An HTML img tag for the referenced image, with title, alt, border and thid attributes.',
753
+ syntax: 'ContentImageByID(id[, defaultImageExternalId])',
754
+ example: '%%=ContentImageByID(12345)=%%',
755
+ isConfirmed: true,
756
+ differsFromOfficialDocs: false,
757
+ },
758
+ {
759
+ name: 'ContentImageByKey',
760
+ supportedInCloudPage: true,
761
+ supportedInEmail: true,
762
+ mcnSince: null,
763
+ handlebarsEquivalent: null,
764
+ mcnNotes: null,
765
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-image-by-key.html',
766
+ guideUrl: 'https://ampscript.guide/contentimagebykey/',
767
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/contentimagebykey/',
768
+ minArgs: 1,
769
+ maxArgs: 2,
770
+ category: 'Content',
771
+ description:
772
+ 'Returns an HTML img tag for a Content Builder image asset by its customer key. A missing image with no fallback aborts the page.',
773
+ params: [
774
+ {
775
+ name: 'imageExternalKey',
776
+ description: 'External key of the image asset',
777
+ type: 'string',
778
+ },
779
+ {
780
+ name: 'defaultImageExternalKey',
781
+ mcnSince: null,
782
+ mcnNotes: null,
783
+ description: 'External key of the fallback image asset',
784
+ type: 'string',
785
+ optional: true,
786
+ },
787
+ ],
788
+ returnType: 'string',
789
+ returnDescription:
790
+ 'An HTML img tag for the referenced image, with title, alt, border and thid attributes.',
791
+ syntax: 'ContentImageByKey(imageExternalKey[, defaultImageExternalKey])',
792
+ example: "%%=ContentImageByKey('hero-image')=%%",
793
+ isConfirmed: true,
794
+ differsFromOfficialDocs: false,
795
+ },
796
+ {
797
+ name: 'EndImpressionRegion',
798
+ supportedInCloudPage: true,
799
+ supportedInEmail: true,
800
+ mcnSince: null,
801
+ handlebarsEquivalent: null,
802
+ mcnNotes: null,
803
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-end-impression-region.html',
804
+ guideUrl: 'https://ampscript.guide/endimpressionregion/',
805
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/endimpressionregion/',
806
+ minArgs: 0,
807
+ maxArgs: 1,
808
+ isConfirmed: true,
809
+ differsFromOfficialDocs: false,
810
+ category: 'Content',
811
+ description: 'Marks the end of an impression tracking region.',
812
+ params: [
813
+ {
814
+ name: 'endAllRegions',
815
+ mcnSince: null,
816
+ mcnNotes: null,
817
+ description:
818
+ 'Whether to end all open impression regions. A truthy value ends every open region; the default ends only the most recent one.',
819
+ type: 'string|boolean|number',
820
+ optional: true,
821
+ },
822
+ ],
823
+ returnType: 'void',
824
+ returnDescription: 'No value is returned; it marks the end of an impression region.',
825
+ syntax: 'EndImpressionRegion([endAllRegions])',
826
+ example: 'EndImpressionRegion(0)',
827
+ },
828
+ {
829
+ name: 'GetPortfolioItem',
830
+ supportedInCloudPage: false,
831
+ supportedInEmail: false,
832
+ mcnSince: null,
833
+ handlebarsEquivalent: null,
834
+ mcnNotes: null,
835
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-get-portfolio-item.html',
836
+ guideUrl: 'https://ampscript.guide/getportfolioitem/',
837
+ minArgs: 1,
838
+ maxArgs: 1,
839
+ category: 'Content',
840
+ description: 'Retrieves metadata for a classic portfolio item.',
841
+ params: [
842
+ {
843
+ name: 'itemExternalKey',
844
+ description: 'External key of the portfolio item',
845
+ type: 'string',
846
+ },
847
+ ],
848
+ returnType: 'string',
849
+ returnDescription: 'The content of the requested Portfolio item.',
850
+ syntax: 'GetPortfolioItem(itemExternalKey)',
851
+ example: "%%=GetPortfolioItem('my-portfolio-key')=%%",
852
+ isConfirmed: true,
853
+ nonFunctionalAtRuntime: true,
854
+ officialDocsNote:
855
+ 'Classic Portfolio is retired on this tenant, so no Portfolio item exists to retrieve. A reached call with an external key that does not resolve aborted the page with HTTP 422 and no partial output, on both the child BU and the parent BU; the same call gated behind an unmatched query-string branch left the page at HTTP 200, confirming a runtime abort of the reached call. No valid key could be sourced because Portfolio asset creation and applications were retired, so the documented success path could not be exercised here.',
856
+ },
857
+ {
858
+ name: 'Image',
859
+ supportedInCloudPage: false,
860
+ supportedInEmail: false,
861
+ mcnSince: null,
862
+ handlebarsEquivalent: null,
863
+ mcnNotes: null,
864
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-image.html',
865
+ guideUrl: 'https://ampscript.guide/image/',
866
+ minArgs: 1,
867
+ maxArgs: 2,
868
+ category: 'Content',
869
+ description:
870
+ 'Returns an HTML img tag for the Portfolio image matching the specified external key.',
871
+ params: [
872
+ {
873
+ name: 'imageExternalKey',
874
+ mcnSince: null,
875
+ mcnNotes: null,
876
+ description: 'External key of an image in your Portfolio',
877
+ type: 'string',
878
+ },
879
+ {
880
+ name: 'defaultImageExternalKey',
881
+ mcnSince: null,
882
+ mcnNotes: null,
883
+ description: 'External key of a fallback image used if the primary is not found',
884
+ type: 'string',
885
+ optional: true,
886
+ },
887
+ ],
888
+ returnType: 'string',
889
+ returnDescription: 'An HTML img tag for the referenced image.',
890
+ syntax: 'Image(imageExternalKey[, defaultImageExternalKey])',
891
+ example: "%%=Image('CorpLogo', 'DefaultImage')=%%",
892
+ isConfirmed: true,
893
+ nonFunctionalAtRuntime: true,
894
+ deprecated: true,
895
+ deprecatedReason:
896
+ 'The classic Portfolio / Classic Content area this function reads from was retired in April 2023, so no image assets exist for it to reference on any current tenant, and every invocation aborts the page at runtime. Use ContentImageByKey or ContentImageByID against Content Builder image assets instead.',
897
+ officialDocsNote:
898
+ 'No working invocation was found on either the child BU or the parent BU. Image resolves images from the legacy Portfolio, whose creation and applications have been retired; no Portfolio assets exist on either BU to reference. Every attempt aborted the CloudPage with HTTP 422 and no output: a literal URL, a Content Builder asset external key, and a plausible Portfolio-style key were all tried on the child BU, and a Portfolio-style key on the parent BU. Use ContentImageByKey or ContentImageByID against Content Builder image assets instead.',
899
+ },
900
+ {
901
+ name: 'LiveContentMicrositeURL',
902
+ supportedInCloudPage: false,
903
+ supportedInEmail: false,
904
+ mcnSince: null,
905
+ handlebarsEquivalent: null,
906
+ mcnNotes: null,
907
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-sites/mc-ampscript-reference-sites-live-content-microsite-url.html',
908
+ guideUrl: 'https://ampscript.guide/livecontentmicrositeurl/',
909
+ minArgs: 2,
910
+ maxArgs: 2,
911
+ category: 'Content',
912
+ description: 'Generates a URL to a microsite page that serves live, dynamic content.',
913
+ isConfirmed: true,
914
+ nonFunctionalAtRuntime: true,
915
+ deprecated: true,
916
+ deprecatedReason:
917
+ 'Live Offers (Live Content) was removed from Marketing Cloud in 2019 and the Classic Microsites this URL points at were retired in June 2022, so there is no provisionable modern equivalent and every invocation aborts the page at runtime.',
918
+ officialDocsNote:
919
+ "Attempted on both the child BU and the parent BU. Every invocation shape aborted the CloudPage with HTTP 200 lost to a 422 page abort: the documented-valid LiveContentMicrositeURL('coupon','MyCoupon'), an unknown content type, and an empty external key all failed identically. The function resolves a Live Offers (Live Content) coupon by external key, and no such Live Content asset is provisioned on either BU, so no working invocation could be produced. Left blocked pending a tenant with a real Live Offers coupon.",
920
+ params: [
921
+ {
922
+ name: 'contentType',
923
+ description:
924
+ 'The type of content to generate a URL for. Accepted values: microsite, landingpage',
925
+ type: 'string',
926
+ enum: ['coupon'],
927
+ },
928
+ {
929
+ name: 'externalKey',
930
+ description: 'The external key of the live content',
931
+ type: 'string',
932
+ },
933
+ ],
934
+ returnType: 'string',
935
+ returnDescription: 'A URL to the referenced live content microsite.',
936
+ syntax: 'LiveContentMicrositeURL(contentType, externalKey)',
937
+ example: '%%=LiveContentMicrositeURL("coupon", "50percent")=%%',
938
+ },
939
+ {
940
+ name: 'TransformXML',
941
+ supportedInCloudPage: true,
942
+ supportedInEmail: true,
943
+ mcnSince: null,
944
+ handlebarsEquivalent: null,
945
+ mcnNotes: null,
946
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-transform-xml.html',
947
+ guideUrl: 'https://ampscript.guide/transformxml/',
948
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/transformxml/',
949
+ minArgs: 2,
950
+ maxArgs: 2,
951
+ category: 'Content',
952
+ description: 'Transforms an XML document using an XSLT stylesheet.',
953
+ isConfirmed: true,
954
+ params: [
955
+ { name: 'xmlDocument', description: 'XML document string', type: 'string' },
956
+ { name: 'xslDocument', description: 'XSLT stylesheet string', type: 'string' },
957
+ ],
958
+ returnType: 'string',
959
+ returnDescription: 'The result of applying the XSL transform to the XML document.',
960
+ syntax: 'TransformXML(xmlDocument, xslDocument)',
961
+ example: '%%=TransformXML(@xml, @xsl)=%%',
962
+ },
963
+ {
964
+ name: 'TreatAsContent',
965
+ supportedInCloudPage: true,
966
+ supportedInEmail: true,
967
+ mcnSince: null,
968
+ handlebarsEquivalent: null,
969
+ mcnNotes: null,
970
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-treat-as-content.html',
971
+ guideUrl: 'https://ampscript.guide/treatascontent/',
972
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/treatascontent/',
973
+ minArgs: 1,
974
+ maxArgs: 1,
975
+ isConfirmed: true,
976
+ differsFromOfficialDocs: false,
977
+ category: 'Content',
978
+ description:
979
+ 'Evaluates a string as AMPscript content, rendering any embedded AMPscript expressions, and returns the rendered string. Plain text and the empty string pass through unchanged.',
980
+ params: [
981
+ {
982
+ name: 'stringToReturn',
983
+ mcnSince: null,
984
+ mcnNotes: null,
985
+ description: 'String containing AMPscript to evaluate',
986
+ type: 'string',
987
+ },
988
+ ],
989
+ returnType: 'string',
990
+ returnDescription: 'The supplied string rendered as AMPscript content.',
991
+ syntax: 'TreatAsContent(stringToReturn)',
992
+ example: '%%=TreatAsContent(@dynamicContent)=%%',
993
+ },
994
+ {
995
+ name: 'TreatAsContentArea',
996
+ supportedInCloudPage: true,
997
+ supportedInEmail: true,
998
+ mcnSince: null,
999
+ handlebarsEquivalent: null,
1000
+ mcnNotes: null,
1001
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-content/mc-ampscript-reference-content-treat-as-content-area.html',
1002
+ guideUrl: 'https://ampscript.guide/treatascontentarea/',
1003
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/treatascontentarea/',
1004
+ minArgs: 2,
1005
+ maxArgs: 3,
1006
+ isConfirmed: true,
1007
+ differsFromOfficialDocs: false,
1008
+ category: 'Content',
1009
+ description:
1010
+ 'Stores a content string under a key for the duration of a send and renders it, evaluating any embedded AMPscript. An optional third argument names an impression region.',
1011
+ params: [
1012
+ { name: 'contentKey', description: 'Content area key identifier', type: 'string' },
1013
+ { name: 'contentValue', description: 'HTML/AMPscript content', type: 'string' },
1014
+ {
1015
+ name: 'impressionRegion',
1016
+ mcnSince: null,
1017
+ mcnNotes: null,
1018
+ description: 'Impression region name',
1019
+ type: 'string',
1020
+ optional: true,
1021
+ },
1022
+ ],
1023
+ returnType: 'string',
1024
+ returnDescription: 'The supplied value rendered as a content area.',
1025
+ syntax: 'TreatAsContentArea(contentKey, contentValue[, impressionRegion])',
1026
+ example: "%%=TreatAsContentArea('region-key', @content)=%%",
1027
+ },
1028
+ ];