When you trigger an external event, you can pass variables as parameters. You might want to display or hide some parts of the email based on these variables. You can use our conditional placeholders in this situation.
If the placeholder is not a field in the contact database, it must be included in the JSON of the API Call which triggers the event. If you omit the placeholder from the JSON it will not be interpreted as having no value; it is the undefined variable that causes the the conditional statement itself to be added to the email content.
Basic use cases
For example, it can happen that there is a contact list where not all the name fields are known. In this case you can create an email with a conditional placeholder:
%%IF name%%Dear %%name%%,%%ELSE%%Hi,%%ENDIF%%
By including this, if the name field has a value, it follows the word “Dear”, otherwise only “Hi,” is displayed in the email.
It can also happen that a key does not have a value. If you want to hide that this variable is not defined, you may want to include a condition:
%%IF money%%You have $%%money%% on your account.%%ENDIF%%
By including this condition in your email, nothing will be displayed when the variable money has no value. Or better put, the amount of money is listed only if it is defined.
You can also check if the value of a numeric variable is less, more or equal to a value:
%%IF hours<12%%Good morning,%%ELSE%%Good afternoon,%%ENDIF%%
In this example, the message “Good morning,” will be included if the value of the hoursvariable is less than 12, otherwise “Good afternoon,” is shown.
The keys for the placeholders can be defined by the following operators:
|!=||not equal to|
|<=||equal to or less than|
|>=||equal to or greater than|
The general pattern a conditional must follow is this:
%%IF KEY[=|!=|>|>=|<|<=][true|false|5|string]%% ... [%%ELSE%% ...] %%ENDIF%%
IF is the introductory element of the conditional. The conditional placeholder should start with ‘%%’.
KEY is the name of any field in the database that you would like to show or hide in the email, based on its presence or value. This can be either a system field or a custom field. For the list of available fields, see the Listing Available Fields endpoint.
ELSE is the element introducing the action that should happen when the ‘IF’ part of the statement is not fulfilled. For example, if the name field is missing, show only “Hi,”.
ENDIF concludes the placeholder statement. Don’t forget to close it with ‘%%’.
- You cannot use HTML content in conditional placeholders.
- You must not use spaces around the conditional.
- Parameters should only contain the characters Aa-Zz, 0-9, _, and -.
- Placeholders should only contain the characters Aa-Zz and 0-9.
Here are a few examples of adding conditional placeholders to an email and the result they produce:
|%%IF item%% Left %%ELSE%% Right %%ENDIF%%||If “item” is present with any value, the text “Left” is shown.|
|%%IF item=true%% Left %%ELSE%% Right %%ENDIF%%||If “item” is true, the text “Left” is shown. If it is false, the text “Right” is shown.|
|%%IF item!=5%% Left %%ELSE%% Right %%ENDIF%%||If “item” is NOT 5, the text “Left” is shown. If it is 5, the text “Right” is shown.|
|%%IF item<=5%% Left %%ELSE%% Right %%ENDIF%%||If “item” is 5 OR it is less than that, the text “Left” is shown. If it is more than 5, the text “Right” is shown.|