Basic information about SAREscript

1. What is SAREscript?

SAREscript is a language created for SARE. It gives users greater control over the content of outgoing emails. Before SAREscript, SARE supported only basic message personalization by replacing selected content with recipient properties stored in the database. SAREscript lets you manipulate recipient data, for example during sending, and process other data available in the system. You can perform operations using basic operators, such as concatenation, addition, subtraction, multiplication and division, as well as available functions, such as rounding numbers, inflecting names, spelling out numbers, creating newsletters and scheduling sends. A key feature is support for conditional structures (if, elseif, else). You can also create loops (for) and define and use your own variables, including arrays. SAREscript currently provides several dozen functions and continues to expand.

2. Similarities to other languages

SAREscript is largely modelled on PHP, one of the most popular scripting languages. Developers familiar with PHP should find it easy to understand and use. This documentation includes many references to PHP. SAREscript functions with PHP equivalents often share the same names. This makes the language accessible to PHP developers while allowing people with no programming experience to create even advanced scripts.

The connection to PHP is intentional. Although a unique syntax could have been created when designing SAREscript, reusing familiar syntax avoids unnecessary complexity. Some constructs differ, however: the for loop syntax is closer to languages such as BASIC.

3. Using SAREscript

To use SAREscript in SARE, create a program for the system to interpret and execute. SAREscript is used during sending, when displaying click maps and personalized web previews, and as an advanced filter. A program can run independently or be embedded in the message to be sent. SARE automatically detects SAREscript in message content. During sending, the script runs for each recipient using the data (properties) assigned to that recipient's address. One email can contain multiple script blocks. Each block is called a scriptspot.

4. Scriptspot

Use SAREscript by creating a scriptspot. Start it with <!--sare.

Close it with sare-->.

The closing marker must be preceded by whitespace, such as a newline or space.

Example scriptspot:

<!--sare print("This is a scriptspot"); sare-->

A scriptspot can occupy one line, as above, or several lines:

<!--sare
print("This is a scriptspot");
sare-->

In both cases, the recipient sees:

This is a scriptspot

Incorrect scriptspot:

<!--sare print("This is a scriptspot");sare-->

Warning

There is no whitespace between the semicolon and the closing marker (;sare--> instead of ; sare-->). The sequence sare--> must appear only at the end of the scriptspot, never inside it.

5. Embedding a scriptspot in a message

A scriptspot can be embedded in message code like other HTML tags. Example:

<HTML>
<HEAD>
<TITLE>Newsletter</TITLE>
</HEAD>
<BODY>
We invite <!--sare print("you"); sare--> to visit our website <a href='http://www.naszastrona.pl/'>www.naszastrona.pl</a>
</BODY>
</HTML>

You can place multiple scriptspots in the same code:

We invite <!--sare print("you"); sare--> to visit our website <!--sare print("again"); sare--> <a href='http://www.naszastrona.pl/'>www.naszastrona.pl</a>

Warning

Do not place a scriptspot between the opening and closing angle brackets of an HTML tag. This is incorrect:

We invite you to visit our website <a href='http://www.naszastrona.pl/<!--sare print("panowie"); sare-->'>www.naszastrona.pl</a>

Do not split a tag between generated and static content, such as generating the opening tag with SAREscript while leaving the closing tag static. This is also incorrect:

We invite you to visit our website <!--sare print("<a href='http://www.naszastrona.pl/panowie'>"); sare-->www.naszastrona.pl</a>

A correct version is:

We invite you to visit our website <!--sare
print("<a href='http://www.naszastrona.pl/panowie'>www.naszastrona.pl</a>"); sare-->

6. Relationships between scriptspots

Embedding scriptspots in message content is the most practical use of SAREscript. It can also run in other contexts, such as advanced filters. SAREscript executes in these parts of the system:

1. Mailing > Editor - message preview
2. Mailing > Editor - email preview
3. Mailing > Sending - test email
4. Mailing > Sending - filter testing
5. Mailing > Sending - actual send
6. SAREscript > Run - execution and debugging
7. Reports > Click map
8. Message web preview
9. Subscription scenarios - displaying and sending objects
10. SOAP interface - calling the Execute method

SAREscript behavior differs significantly across these contexts. Scripts sometimes run one after another, and their execution order is essential to a correct result. Understanding how scriptspots run is therefore important. See Execution details for a detailed description.