Customize messages

 

Introduction

You can insert “dynamic text” (also called a “dynamic field”) to customize the message. For example, you can start your message with a “Dear …,” personalized with the first name of each user. Or you can customize some parts of the message by including contents from external sources.

Objective

Know and be able to use dynamic codes to customize any part of the message.

Supported codes

Here is a list of the main dynamic codes supported by Contactsend.

Code name Open tag Close tag Media Description
USER_DATA_TAGS ${ }$ all Values includes, for each recipient, from the fields of the db associated to the group in use.
INLINE_CONTENT_TAGS @( )@ email URL to retrieve and embed files (for example images) in the message body.
DYNAMIC_INLINE_CONTENT_TAGS ^( )^ email Similar to INLINE_CONTENT_TAGS but supporting the use of other dynamic codes in the URL, like: USER_DATA_TAGS, NOTES_TAGS
TRACKED_URL_TAGS %{ }% email It genereates a syntax for statistical tracking of link clicks.
DYNAMIC_TRACKED_URL_TAGS ^{ }^ email Similar to TRACKED_URL_TAGS but supporting the use of other dynamic codes, like: USER_DATA_TAGS, NOTES_TAGS
ERB_TAGS <% %> all It processes ERB tags in the message, if any.
EXTERNAL_SOURCE_TAGS @{ }@ all Some content (tipically an html file) is retrieved via an URL and included in the message.
INCLUDE_URL_TAGS <@ @> all Similar to EXTERNAL_URL_TAGS but supporting the use of other dynamic codes in the URL, like: USER_DATA_TAGS, NOTES_TAGS
NOTES_TAGS <{ }> all It allows you to include the value of one of the saved labels.

Now, for each part of the message, we list the pipeline order (from top down) for codes processing. The processing order is important in case you want to use a dynamic code in a specific step of campaign creation: in order to do that, Contactsend must have already processed it in that phase of the message creation.

EMAIL

Subject:

  1. USER_DATA_TAGS
  2. ERB_TAGS

Mail from and Reply to:

  1. USER_DATA_TAGS

HTML body

1. EXTERNAL_SOURCE_TAGS
2. INLINE_CONTENT_TAGS
3. TRACKED_URL_TAGS
4. NOTES_TAGS
5. USER_DATA_TAGS
6. ERB_TAGS
7. INCLUDE_URL_TAGS
7a. TRACKED_URL_TAGS
7a. TRACKED_URL_TAGS
8. DYNAMIC_INLINE_CONTENT_TAGS
9. DYNAMIC_TRACKED_URL_TAGS
10. USER_DATA_TAGS

Plain text body:

1. EXTERNAL_SOURCE_TAGS
2. TRACKED_URL_TAGS
3. NOTES_TAGS
4. USER_DATA_TAGS
5. ERB_TAGS
6. INCLUDE_URL_TAGS
6a. TRACKED_URL_TAGS
6b. USER_DATA_TAGS
7. DYNAMIC_TRACKED_URL_TAGS
8. USER_DATA_TAGS

SMS

Message body:

1. USER_DATA_TAGS
2. INCLUDE_URL_TAGS
2a. TRACKED_URL_TAGS
2b. USER_DATA_TAGS
3. ERB_TAGS

Base customization

USER_DATA_TAGS

We can apply a base customization to our message through the “USER_DATA_TAGS” code, that allows us to take values from the database associated to the (email/sms) group we are using, and place it inside the message.

Procedure

  • Check that in the database associated to the group in use, there’s a field relevant to our purpose.

For example, if we want to start our message with: “Dear John”, “Dear Mary” and so on, basing on our recipients’ first name, we need to have a field with users names in our db.

Let’s say this field is called NAME (all in capital letters).

  • Now put the cursor in the exact point (either in the visual editor, PageBuilder, or directly in the html code) of the message.
  • Type: Dear ${NAME}$

Note: the dynamic code is case sensitive, so please pay attention to write it exactly as it is named in the database.

If we are in the “Message contents” step of the campaign creation wizard, we can use the relevant dropdown menues to place the code inside our html. The email medium also allows to make the senders details (mail from and reply to address) dynamic, if globally enabled on the email group.

You can also insert more than one dynamic code in your message; for example:

Dear ${FirstName}$ ${LastName}$, we inform you that your user account ${Username}$ is about to expire.

You can automatically modify the values of included fields using:

Field modifiers

The field modifier syntax allow you to apply changes to the values taken via the USER_DATA_TAGS codes, such as: ${field_name}$ . Modifiers change the visualization of data taken from a database field. You can apply more modifiers to the same field. They will be executed in a pipeline.

This is the modifiers syntax: ${field_name|modifier}$ where:

  • field_name: is the name of the field in the user db. It is, once again, case sensitive.
  • modifier: is the name of the modifier you want to apply to that field.

Here’s list of available modifiers, with a description and examples:

– default

You can a default value in case the field is NULL or empty.

${name default:””}$

Examples:

(name = “Mary”) Dear ${name|default:”customer”}$ => Dear “Mary”

(name = “”) Dear ${name|default:”customer”}$ => Dear “customer”

In the example above, if the field ‘name’ is empty, the word ‘customer’ will appear instead.

Specific use case: use withing the “a” html tag. Let’s say we want to use this modifier withing the href attribute, this way: href=”${Domain|default:”http://oursite.com”}$” to display for each user the URL contained in his/her Domain db field, or oursite.com if empty.

The syntax above will NOT work, as the output will be an invalid link. Use the following instead: href=”${Domain|default:’http://oursite.com’}$” where the default URL is surrounded by ‘ instead of ” (double quote).

– date_format This formats date fields using these placeholders: %d – month day number (from 00 to 31) %m – month as a number (from 01 to 12) %y – year as a two digits number (from 00 to 99) %Y – year as a four digits number

Example:

(birth_date = 1992-04-15)
${birth_date|date_format:”%d/%m/%Y”}$ => “15/04/1992″**

The date field must be in mysql format: yyyy-mm-dd If the date is not in mysql format, use the date_parse modifier instead (see below) and then the date_format modifier.

– date_parse Creates a date from a string, and then you can format it via the date_format modifier; it user the same syntax of date_format.

Example:

(birth_date = “1992/04/15″) ${birth_date|date_parse:”%Y/%m/%d”|date_format:”%d-%m-%y”}$ => “15-04-92″**

– string_format It allows you to format a text string.

Example:

(value_1 = 23.5787446) ${value_1|string_format:”%.2f”}$ => “23.58”**

In the example above, value_1 will be rounded at second decimal digit.

– substring It extracts a portion of the string, between starting portion (included) and final portion (excluded). If final portion exceeds string length, result ends with the end of the string. The string start is marked with “0” (zero).

Examples:

(value = “abcdefg”) ${value|substring:”0″:”5″}$ => “abcde” ${value|substring:”2″:”5″}$ => “cde” ${value|substring:”2″:”100″}$ => “cdefg”

– capitalize It capitalizes only the first letter of the string.

Example:

(full_name = “joseph guerrisi”) ${full_name|capitalize}$ => “Joseph guerrisi”

– lower (o lowercase) Changes all letters in the string to lower case.

Example:

(full_name = “Joseph Guerrisi”) ${full_name|lower}$ => “joseph guerrisi”

– upper (or uppercase) Changes all letters in the string to upper case.

Example:

(full_name = “joseph guerrisi”) ${full_name|uppercase}$ => “JOSEPH GUERRISI” **

– swapcase Changes lower case to upper, and upper case to lower.

Example:

(full_name = “Joseph Guerrisi”) ${full_name|swapcase}$ => “jOSEPH gUERRISI” **

– reverse Reverts the string.

Example:

(full_name = “Joseph Guerrisi”) ${full_name|reverse}$ => “isirreuG hpesoJ”

– urlencode Codes the string for use in URLs.

Example:

(full_name = “Joseph/Guerrisi”) ${full_name|urlencode}$ => “Joseph%2FGuerrisi”

– urldecode The contrary of urlencode

– replace Find & Replace; it is case sensitive. The first parameter is the string to be replaced, the second is the string that will replace it.

Example:

(full_name = “Joseph Guerrisi”) ${full_name|replace:”Joseph”:”John”}$ => “John Guerrisi”

In the example above, all fields containing the name “Joseph” are replaced by the string “John”.

– md5 (o md5sum) It calculates the md5 checksum

Example: (full_name = “Joseph Guerrisi”) ${full_name|md5}$ => “a5887a62d652d2b476e57f20bbbc8c2c”

– base64encode Base64 encoding

Example:

(full_name = “Mario Rossi”) ${full_name|base64encod}$ => “TWFyaW8gUm9zc2k=”

– base64decode The contrary of base64encode

Pipelining

You can apply more modifiers to the same field, creating a pipeline: the result of a modifier will be passed to the follwing modifier.

Example:

(field2 = “”) ${campo2|default:”Not Available”|lowercase|urlencode}$ => “not+available”

(birth_date = “1992/04/15″) ${biirth_date|date_parse:”%Y/%m/%d”|date_format:”%d-%m-%y”}$ => “15-04-92”

Advanced customization

EXTERNAL_SOURCE_TAGS

Trough relevant tags placed in the html code, you can include in that point an external content (tipically, a portion of html code or a full html file).

  • Let’s suppose we want to automatically send, on a daily basis, contents from our web page http://oursite.com/dailynews.html
  • At the “Message contents” step of the Create > Email campaign wizard, we place the following dynamic syntax inside the message body:@{http://oursite.com/dailynews.html}@
  • Content at that address will be automatically included in the message.

Attention: content will be retrieved at the moment when the message is generated, so please be sure in that moment you have the correct contents at that URL.

INCLUDE_URL_TAGS

Similarly to EXTERNAL_URL_TAGS, it allows you to include files from an external URL, but it also supports the use of other dynamic codes.

Example:

<@http://oursite.com/${country}$/dailynews.html@>

that for users from the US will retrieve contents from
http://oursitecom/us/dailynews.html , for users from the UK from
http://oursite.com/uk/dailynews.html and so on.

INLINE_CONTENT_TAGS and DYNAMIC_INLINE_CONTENT_TAGS

@(http://oursite.com/img/pic1.jpg)@ and ^(http://oursite.com/img/${country}$/pic1.jpg)^
retrieve the image from the URL, and embedded it into the message body. The use of embedded images, on one hand makes them immediately visible in the email, because they’re inside the message body itself and notattached or retrieved on the fly from an external source. On the other hand, the message is heavier, and the anti-spam blocking more risky. For those reasons, we suggest not to use embadded images.

TRACKED_URL_TAGS and DYNAMIC_TRACKED_URL_TAGS

This syntax is normally automatically placed by Contactsend in the message body, during the email campaign creation process, to allow link tracking and clicks counting. The syntax of TRACKED_URL_TAGS can be inserted manually, for example when you need to track URLs containing dynamic parameters. For example: http://oursite.com/index.php?${country}$

In case dynamic parameters are placed in different points of the URL, or in the domain itself, you can use a syntax like DYNAMIC_TRACKED_URL_TAGS , as in the following examples: ^{http://oursite.com/${country}$/docs/index.html}^ ^{${domain}$}^

ATTENTION: to avoid slowing down message preparation and broadcasting, plase do not use this syntax when you have many unique values, on sendings with a high number of recipients.

NOTES_TAGS

Typing the name of a campaign label, it allows to include its value.

For example <{client_id}> places the relevant value in the point where the dynamic code is present (like a placeholder).