AMPscript Syntax Guide

Using Function Calls

You can use ExactTarget function calls inside AMPscript blocks or outside of script blocks: anywhere a traditional substitution string is valid.  Function calls outside of AMPscript blocks must be introduced by the opening delimiter %%= and terminated by the closing delimiter =%%.  Function calls within AMPscript should not include these delimiters. These function calls will be executed even if they are not part of a scripting statement, such as SET or IF.

Function Call Outside an AMPscript Block

%%=LOWERCASE(Name)=%%

Function Call Inside an AMPscript Block

%%[ LOWERCASE(Name) ]%%

Functions Accept Any of These Input Types:

Constant Value

LOWERCASE("Mary Smith")

Attribute Value

LOWERCASE(Name)

Variable Value

LOWERCASE(@Name)

AMPscript Language Elements

AMPscript uses the following language elements:

• Constants
• Attributes and Data Extensions
• Keywords

Constants

AMPscript can include numeric constants and string constants.

Numeric constant values consist of an unquoted set of numerals and can also include one decimal point and an introductory minus sign to indicate negative values. Numeric constant values cannot contain commas. Here are some examples:

123

-123


123.456

String (or text) constant values must be quoted in double or single quotes. String constants can escape the delimiting quote character if they appear within the text by doubling it. Alternative quote characters, such as smart quotes, are not recognized.

"A string value"


"123.456"


'a string value'


'Sally"s string value'


(Doubled '' will be rendered as ')

Boolean constant values must be true or false and are case insensitive. Here are some examples:

true


false


TRUE

False

Attribute and Data Extension (Custom Object) Values

Subscriber attribute, additional email attributes, and data extension column values are referenced in functions and scripts as unquoted strings. If the attribute, data extension column, table, or relationship name includes a space or special character, it must be enclosed in square brackets. For example:

EmailAdr


[Data Extension Attribute Name]


[Total-Expense]

You can define additional email attributes within the email and use them in substitutions or as parameters in AMPscript function calls. ExactTarget must enable the use of additional email attributes for you account. Contact your ExactTarget representative with any questions about this functionality.

Keywords

Variables can be declared, initialized, and modified within a script. Variables then can be referenced by script statements and functions.

A variable declaration consists of the keyword VAR followed by one or more comma-delimited variable names. Variable names must begin with the @ symbol and be followed by at least one other letter, number, or underscore. Spaces and commas are not allowed in variable names. For example:

@Name

@C1

A variable assignment consists of the keyword SET followed by the variable name, equal sign, and value.

Declaring a variable with the VAR keyword adds an entry to the Variables Dictionary with the variable name as the key and NULL as the value. If an entry for that name already exists, the value of the variable is set to NULL.  If the variable is being used to control a FOR loop, an attempt to declare it will result in a validation or runtime error.

%%[VAR @Count]%%


%%[VAR @Count1, @Count2, @Count3]%%

if <condition> then <statement>   
    elseif <condition> then <statement> 
      .   
    else <statement>
endif

%%[IF expression1 <comparison operator> expression2 THEN]%%
    [wrapped script or email content]
%%[ELSEIF expression1 <comparison operator> expression3 THEN]%%
    [wrapped script or email content]
%%[ELSE]%%
    [wrapped script or email content]
%%[ENDIF]%%

IF expression1 <comparison operator> expression2
        AND [NOT] (expression3 <comparison operator> expression4
        OR expression3 <comparison operator> expression5)
THEN .

IF NOT EMPTY(expression1) THEN

%%[if not empty(MailingAddress) then]%%
%%MailingAddress%%
%%[endif]%%

%%[FOR @Variable = <start expression> TO|DOWNTO <end expression> DO ]%%
        [wrapped script or email content]
    %%[NEXT @Variable]%%

%%[
VAR @Count, @Count2
SET @Count = 0
SET @Count2 = 100
]%%
@Name
@C1

%%[Output(Now())]%%

%%[ Var @text
Set @text = "Example Text"
Output(v(@text)) ]%%

%%[ Var @text
Set @text = "Example Text"
Output(@text) ]%%

%%[ OutputLine(Substring("Example Text",1,6)) ]%%

Using Comments

AMPscript may contain comments-or non-executed notes-that allow you, as the author, to document your code.  You must open comments with the /* sequence and close comments with the */ sequence.  Comments may span multiple lines.

%%[ /* Insert Comment Here */ ]%

Using AMPscript Language Elements with Enterprise Awareness

The following AMPscript functions have Enterprise awareness:

LookupRows()
Lookup()
LookupOrderedRows()

You can use the ENT. prefix with these functions to indicate to the system that the data extension being operated on exists at the parent Enterprise level and not at the child level.

In the following example, the system looks up data from the MERCHANT data extension stored at the Enterprise Administrator level:

%%[
Var @rows
Set @rows = LookupRows("Ent.Merchants","TRAVELWEB_MERCHANT_ID",200043800)
]%%<br>
%%=Field(Row(@rows,1),"merchant_name")=%%<br><br>

Using Data Modification Functions

Two sets of functions allow a client's data extension data to be modified through AMPscript: send time support and landing page support. These functions allow insert, update, upsert (update/insert), and delete actions to be performed at the subscriber level.  The use of these functions is restricted according to the content being processed by the ExactTarget system.

The key or filter fields for update and upsert calls are distinguished from the columns being set by the second parameter for these calls.  This parameter must have a value of 1 or more to indicate how many of the following column name and column value pairs make up the key for finding the row to be updated.  The remaining name and value pairs specify the columns to be updated and the new values.

%%=UPDATEDE("DE_To_Update",1,"Filter Column","Filter Value","Column","Value")=%%

%%=INSERTDE("CustomObject4","Region","None","Product",_SubscriberKey,"Price",99.77, "Inventory", 88,
"ExpireDate",NOW(),"Available",1,"Inventory",77,"Locale", LOOKUP("CustomObject3",
"Custom Object Value"
,"Region",Region),"_FromName","Bob",<"_FromEmail",LOOKUP("CustomObject2","EmailAddress",
"Region1",Region))=%% %%=UPDATEDE("CustomObject4",1,"Region","None","Available",0,"Price",100.77,"Inventory",0,
"ExpireDate",NOW())=%% %%=UPDATEDE(_SourceDE,1,"_CustomObjectKey",_CustomObjectKey,"Total & Credit - Cost",_CustomObjectKey,"SubscriberID",SubscriberID)=%% %%=UPSERTDE("ent.CustomObject4",2,"Region","None","Product",_SubscriberKey,"Available",0, "Price",100.77,"Inventory",0,"ExpireDate",NOW(),"Url",CONCAT(SubscriberID," Upsert"))=%% %%=DELETEDE("CustomObject4","Region","None")=%%

%%=INSERTDATA("CustomObject4","Region","None","Product",_SubscriberKey,"Price",99.77, "Inventory", 88,
"ExpireDate",NOW(),"Available",1,"Inventory",77,"Locale",LOOKUP("CustomObject3","Custom Object Value","Region",Region),"_FromName","Bob","_FromEmail",LOOKUP("CustomObject2",
"EmailAddress","Region1",Region))=%%

%%=UPDATEDATA("CustomObject4",1,"Region","None","Available",0,"Price",100.77,"Inventory",
0,"ExpireDate",NOW())=%%

%%=UPSERTDATA("ent.CustomObject4",2,"Region","None","Product",_SubscriberKey,"Available",
0,"Price",100.77,"Inventory",0,
"ExpireDate",NOW(),"Url",CONCAT(SubscriberID," Upsert"))=%%

%%=DELETEDATA("CustomObject4","Region","None")=%%

Using Execution Context

Content used in landing pages, Web Collect and Smart Capture and called via an AMPScript function can be processed contextually by the ExactTarget system. That message content is processed depending on the context of the function's execution.

Execution context is supported by type and name and represented by the global read-only variable @@ExecCtx.  The system processes Load and Post types, and it defaults to Load if no context is specified in the call.  Any content without a specific execution context will always be processed.  The system honors any context type, and it only processes script blocks in the active content with the specified name.  For example, the ExactTarget system processes only script blocks named SaveData if the caller specifies the Post context type and the blocks are located in a section of code executed for the Post type.

The caller sets @@ExecCtx to a string value of Load or Post, indicating the current execution context, and the value is case-insensitive.  Use this variable to to control the processing of content according to execution context as shown in the example below:

/* Content and Script to always be executed here */
%%[ IF @@ExecCtx == "LOAD" THEN]%%
    %%[/*Load Content or Script Here*/]%%
%%[ ELSEIF @@ExecCtx == "POST" THEN]%%
    %%[/*Load Content or Script Here*/]%%
%%[ENDIF]%%
/* Content and Script to always be executed here */

You can also control processing of content using execution context names. When the caller specifies a name, only script blocks with that name are executed. Callers can also specify a script type at the script block level, with the script name and type set immediately after the script start delimiter. Use single or double quotes for the string values. Names and types are case insensitive:

%%[[name="nameStr";type="Load|Post].]%%
In this example, the UpsertData command executes only if the caller's execution context is set to POST and the name UpdateDate is specified:
%%[[name="UpdateDate";type=" Post]UpsertData("MyDE","Col1",Val1,"Col2",Val2)]%%

Script blocks must be completed within the same script block section.  For example, any IF or FOR statements inside a script block must be completed by an ENDIF or NEXT within the same named script block. If script blocks span two or more script block sections, the ExactTarget returns the following error message:

"An incomplete IF statement exists in a typed script block.  Script statements cannot span named or typed script blocks."

You can also use execution context to determine whether to display most current content or the content current as of when the email was sent. This document provides an example of how to use AMPscript to contextually display send-time content, which requires enabling the send logging feature.

Using Dynamic Link Names

Dynamic link names or link aliases are supported. This functionality lets you include dynamic content, including substitution strings and AMPscript function calls, in the name assigned to a link and then track the link by the resolved values.

This functionality is available only if:

• You are using the HTML version of emails.
• You are using Always on Clicks.

When creating an email, include your dynamic statements when setting the link name or alias attribute in the Content Editor inside the user interface. For example:

<a href="http://website.example.com/key/p...ID=C12915x001B" target="new" alias="%%=CONCAT(Region,' Region')=%%">

This example tracks the link specified above separately by each subscriber's region included in the send. For example:

West Region
North Region.

There is a configuration limit on the number of unique resolved link names, as defined by a link alias, that can be tracked for each link with a dynamic link name. This limit is 100 names. If the number of unique link names exceeds this limit, the excess links are tracked under the original unresolved link name.

Date and Time Formatting

You can use several different data and time formats with AMPscript, depending on your needs. The table below demonstrates the available formats:

For example, the AMPscript below takes the results of the DateAdd() function (using the examples from the table) and returns it in the specified format:

%%=Format(Now(), "MMMM d, yyyy")=%%
August 15, 2011

The example below takes the value of Now(), offsets it using the DateAdd() function, then returns that value in the specified format:

%%[ VAR @futureDate, @today SET @today = Now(1) SET @futureDate = DateAdd(@today, 11, "D") ]%% 
Date: %%=Format(@futureDate, "MMMM d, yyyy")=%%

The example below outputs the Birthday attribute of a subscriber in the format specified:

%%[Output(Format([Birthday],"dd/MM/yyyy"))]%%