Actions

Email templates: Difference between revisions

From LimeSurvey Manual

mNo edit summary
m (in ISO8601 format with time (Y-m-d H:i:s in PHP))
 
(83 intermediate revisions by 8 users not shown)
Line 3: Line 3:




=Introduction=
=Introduction= <!--T:97-->


The email templates are used to quickly send personalized invitations, reminders, confirmations, and registrations emails to your respondents (from the survey participants table). You can also edit the standard basic (or detailed) admin notifications that are sent to the survey administrator.


To access it, go to the '''survey settings''' and click on the '''Email templates''' tab:
<!--T:98-->
The email templates are used to send personalized invitations, reminders, confirmations, and registration emails to your participants (from the survey participants table). You can also edit the standard basic (or detailed) admin notifications that are sent to the survey administrators.


<!--T:99-->
Email Templates: '''Settings''' > '''Survey menu''' > '''Email templates'''


<!--T:100-->
<center>[[File:Location email templates.png]]</center>
<center>[[File:Location email templates.png]]</center>




<div class="simplebox">[[File:help.png]] If you are a superadministrator (you have access to the [[Global settings|global settings of your LimeSurvey installation]], you can change the Default HTML editor mode to all your LimeSurvey users. For further details, continue reading [[https://manual.limesurvey.org/Global_settings#General|the following wiki subsection]].</div>
<!--T:101-->
<div class="simplebox">[[File:help.png]] If you have the superadministrator permission (you have access to the [[Global settings|global settings of your LimeSurvey installation]]), you can change the Default HTML editor mode for all of your LimeSurvey users. For further details, continue reading [[Global_settings#General|the following wiki subsection]].</div>
 
 
<!--T:102-->
{{Alert|title=Attention|text=If you want to use the popup/inline HTML editor, do not forget to enable the '''HTML format for token emails'''! This is located in the '''Settings menu''' of your survey, under the [[Participant settings]] tab.}}


{{Alert|title=Attention|text=If you wish to use the inline HTML editor, do not forget to enable the '''HTML format for token emails'''! This is located in the '''Settings menu''' of your survey, under the [[Participant tokens]] tab.}}
=Email Templates Panel= <!--T:103-->


=Email templates panel=


<!--T:1-->
<!--T:1-->
The email templates panel looks like this:
The email templates panel:




Line 27: Line 35:




As it can be observed in the screenshot, the "HTML source" editor mode is used. To change it, check the the [[Global settings| global settings]] of your LimeSurvey installation (if you have the superadministrator permission) or [[First_login_-_your_user_preferences#HTML_editor_mode|personal account settings]].  
<!--T:104-->
In the above screenshot the "HTML source" editor mode is used. To change it, go to your [[First_login_-_your_user_preferences#HTML_editor_mode|personal account settings]].  




{{Note|To easily edit the text fields, access your account/global settings, and choose the inline editor mode.}}  
<!--T:105-->
{{Note|To edit the text fields, go to your account settings and choose the ''inline HTML editor mode''.}}  




As you can observe, six types of emails can be send to the users or admin(s):
<!--T:106-->
Five types of emails can be sent to users or admins:
*[[Email templates#Invitation|Invitation]]
*[[Email templates#Invitation|Invitation]]
*[[Email templates#Reminder|Reminder]]
*[[Email templates#Reminder|Reminder]]
Line 41: Line 52:




==Invitation==
==Invitation== <!--T:107-->
 


The invitation system is useful when you wish to send emails in bulk to all the respondents from your [[Survey participants#Send email invitation|survey participants table]] who have not been already sent an invitation.
<!--T:108-->
This functionality is used to send emails in bulk to all survey participants in the [[Survey participants#Send email invitation|survey participants table]] who have not yet received an invitation to complete your survey.


From the email templates panel, you can edit the message that reaches out those survey participants. To check which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. You can also use the [[Expression Manager]] to enhance your customization.
<!--T:109-->
From the email templates panel, you can edit the message sent to survey participants. To check which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. You can also use the [[ExpressionScript - Presentation|ExpressionScript]] to further customize your invitation email template.


==Reminder== <!--T:110-->


==Reminder==


The reminder system helps survey administrators remind their [[Survey_participants#Send_email_reminder|respondents from the survey participants table]] to answer to the survey.
<!--T:111-->
The ''Reminder'' functionality provides a way for survey administrators to remind the [[Survey_participants#Send_email_reminder|participants from the survey participants table]] to answer the survey.


You can edit the default format of the reminder email from the email templates panel. To check which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[Expression Manager]] can help you better customize the text body of this email template.
<!--T:112-->
You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.


<div class="simplebox">[[File:help.png]] '''Note:''' A reminder will be sent only to those participants where the "Completed" field is turned off (this means the respondent has either not taken or completed the survey) in the [[Survey participants|survey participants table]].</div>
<!--T:113-->
<div class="simplebox">[[File:help.png]] '''Note:''' A reminder will be sent only to those participants in the [[Survey participants|survey participants table]] where the "''Completed''" field is turned off. This means the respondent has either not taken or completed the survey.</div>


==Confirmation== <!--T:114-->


==Confirmation==


If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant tokens]] panel.
<!--T:115-->
If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant settings]] panel.


Click on the '''Confirmation''' tab if you wish to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[Expression Manager]] to enhance your customization.
<!--T:116-->
Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.


==Registration== <!--T:117-->


==Registration==


If the closed-access mode is enabled, only those participants who have an entry and a unique token code associated can complete the respective survey. If you allow participants [[Participant tokens|to publicly register to your survey]]. a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.
<!--T:118-->
If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.


Click on the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[Expression Manager]] can provide additional enhancements to the body text you wish to use.
<!--T:119-->
Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.


==Basic & Detailed Admin Notifications== <!--T:120-->


==Basic & Detailed admin notifications==


To get admin notifications, click on the [[Data management]] tab and type in an email address in the "Send basic admin notification email to" and another one (or the same) in the "Send detailed admin notification email to" field.
<!--T:121-->
To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.


By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kind of emails to also check the submitted answers without being needed to access the LimeSurvey installation.
<!--T:122-->
By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers.  They do not have to access the LimeSurvey installation.


However, by using the [[Expression Manager]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates however you want.
<!--T:123-->
However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.


=Email Templates Fields= <!--T:124-->


=Email templates fields=


<!--T:125-->
Each email template contains:
Each email template contains:
<!--T:126-->
*'''The subject of the email:''' The title of the email/batch of emails you want to send;
*'''The subject of the email:''' The title of the email/batch of emails you want to send;


*'''The email body:''' This field contains the text message you wish to send to the users. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. Moreover, the [[Expression Manager]] can be used to further enhance the message you wish to deliver;  
<!--T:127-->
*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;  


*'''Email actions:''' It is made of the following two functions:
<!--T:128-->
**''Validate expressions:'' It checks the logic of the email - whether the placeholders are correctly used or not. It is highly recommended to use it before sending a batch of emails. In this way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is immediately emphasized in red via this function:
<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>




<center>[[File:Validate email - email templates.png]]</center>
<!--T:129-->
*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.




**''Reset this template:'' Once clicked, the HTML code gets reset. No text is deleted.
<!--T:130-->
 
<center>[[File:Validate email - email templates.png]]</center>
*File actions: Different file-related actions can be performed here:
**''Add file:'' Once clicked, the following window will pop up, asking you to choose which document from the '''files''' folder you wish to send with the email:
 
 
<!--T:6-->
Attachments can be added at the bottom of the email template editing interface. Email attachments are uploaded on a per survey basis.
 
 
<center>[[File:Upload files - email templates.png]]</center>
 
 
You can also upload on the spot a file from the desktop to your LimeSurvey installation by clicking on the '''upload''' button and then selecting the file you wish to attach to the respective email template:
 
Once selected, double click on it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:
 
 
<center>[[File:Files table - email templates.png]]</center>
 
 
To have it permanently saved, do not forget to click on '''Save''' button located in the upper-right part of the windonw
 
<!--T:7-->
To decide if an attachment should be sent on an individual basis it is possible to add a relevance equation to each attachment.
 
<!--T:8-->
All functions supported by the [[Expression Manager|Expression Manager]] can be used, as well as token attributes if the survey uses tokens.
 
<!--T:9-->
In case of a notification or confirmation template it is also possible to use [[Expression Manager#Access to Variables|question codes]] used in the survey.
 
<!--T:10-->
{{Alert|title=Attention|text=Please note that:
* When a '''file can not be found''' on the file system, the email will be '''sent without attachment'''.
* '''Exporting/importing''' a survey does not export the uploaded files. The settings for attachments will be maintained, as will the relevance equations.}}
 
 
=Using replacement function.= <!--T:11-->
 
<!--T:12-->
In the email template , you can use some specific keywords to use token information: see [[Tokens#Email_placeholders|Emails placeholders]] to have the complete list of placeholders.
 
<!--T:13-->
A good example is the usage of the plain link to the survey instead of a long url.
 
==Example: Create a nice link to start the survey== <!--T:14-->
# First open up the email-templates editing and choose 'Invitation' on the upper tabs.
# Then write the text you want to appear as link to start the survey.
# Then select that text.
[[File:mark_text_to_hyperlink.jpg]]
#Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box
[[File:add_link_placeholder_choose_other.jpg]]
 
<!--T:15-->
Now if you send out your invitation mails, the link to start the survey will be a link and not an url.


=Email Placeholders= <!--T:138-->


=Email placeholders= <!--T:77-->


<!--T:139-->
{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}


You may observe in the body and/or subject of the message different email placeholders. Their role is to connect the email you wish to send to each token entry from the survey participants list. In this way, their data is automatically taken and you will not have to manually type the details of the respective survey participant (e.g. first name, administrator email, survey description, and so on).
<!--T:77-->
In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.


<!--T:78-->
<!--T:78-->
You can find below the field names that are allowed in invitation and reminder [[Email templates|email templates]] in LimeSurvey. They must be included in the body message! When sending out the emails, these field names will be already replaced in the preview of your invitation/reminder email.
Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].


<!--T:79-->
<!--T:79-->
{|
{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|{ADMINEMAIL}||Email of the Survey admin
|-
|-
Line 172: Line 152:


<!--T:80-->
<!--T:80-->
The following field names are allowed in invitation/reminder emails (subject and/or body) and will be replaced while sending out the mails:
The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:


<!--T:81-->
<!--T:81-->
{|
{|class="wikitable"
|{EMAIL}||Email of the recipient
|{EMAIL}||Email of the recipient
|-
|-
Line 182: Line 162:
|{LASTNAME}||Last Name
|{LASTNAME}||Last Name
|-
|-
|{SURVEYURL}||The URL pointing to the survey start - if you are sending HTML emails this will be a fully linked HTML version
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{EMAILSTATUS}|| Used for skipping emails on email sending. Default email status is "OK".
|-
|{LANGUAGE}|| Used to define the language to be used for emails and survey URL when using multilingual surveys
|-
|{SENT}|| Invitation send date in ISO8601 format with time (Y-m-d H:i:s in PHP)
|-
|-
|@@SURVEYURL@@||The URL pointing to the survey start - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|{REMINDERSENT }|| Reminder send date in ISO8601 format with time (Y-m-d H:i:s in PHP)
|-
|-
|{OPTOUTURL}||The URL to deactivate sending of mail for this survey  - this will be a fully linked HTML version
|{REMINDERCOUNT}|| Number of reminders already sent
|-
|-
|{TOKEN}||Token to access the survey
|{COMPLETED }|| Survey completion date
|-
|{TID}|| Internal ID at token table
|-
|-
|{ATTRIBUTE_1}||Attribute 1
|{ATTRIBUTE_1}||Attribute 1
Line 196: Line 200:


<!--T:82-->
<!--T:82-->
If your survey is '''not''' anonymous, the following field names are available to insert token data in survey text and javascript.  
If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).


<!--T:83-->
<!--T:83-->
{|
{|class="wikitable"
|{TOKEN:EMAIL}||Email of the recipient
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|-
|{TOKEN:FIRSTNAME}||First Name
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|-
|{TOKEN:LASTNAME}||Last Name
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|-
|{TOKEN}||Token to access the survey
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|-
|{TOKEN:ATTRIBUTE_1}||Attribute 1
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|-
|{TOKEN:ATTRIBUTE_2}||Attribute 2 (and so on for more attribute fields)
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}
|}


Note: You can use these fields in confirmation and notification email template too.
<!--T:140-->
{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}


Note:
<!--T:141-->
These email placeholders can also be used in the confirmation and admin notification email templates.


*If your survey is using anonymized responses then token-related placeholders will not work in notification email templates.
<!--T:142-->
*You can use [[Expression Manager|Expression Manager]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[Expression Manager HowTos|Expression Manager HowTos]] for an example.
Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!
Also have a look at the examples on using [[Adding a question#Information from tokens table|information from tokens table]].


=Edit email templates=
<!--T:143-->
Some of the placeholders that can be used only in the admin notification panels are mentioned below:


<!--T:86-->
<!--T:144-->
#'''Invitation Email Subject''': The subject line for the invitation email that gets sent out when tokens are used with your survey.
{|class="wikitable"
#'''Invitation Email''': This is the text for the invitation email that gets sent out when tokens are used with your survey. This is initially filled by the default invitation message (from the language files) but you can modify it to suit yourself. If you are using English as your base language, the default invitation and reminder text can be found in the limesurvey/tokens.php file. Of course if you don't plan to use tokens on your survey, whatever is in this field is irrelevant.  You can use the following "form" fields to insert individualized information in each email:
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
*'''{FIRSTNAME}''' - gets replaced with the token table's "firstname" value
|-
*'''{LASTNAME}''' - gets replaced with the token table's "lastname" value
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
*'''{SURVEYNAME}''' - gets replaced with your surveys name
|-
*'''{SURVEYDESCRIPTION}''' - gets replaced with your surveys description
|{STATISTICSURL}||Click this URL to access the statistics of the survey
*'''{ATTRIBUTE_1}''' - gets replaced with the token table's "attribute_1" value
|-
*'''{ATTRIBUTE_2}''' - gets replaced with the token table's "attribute_2" value and so on
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
*'''{SURVEYURL}''' - gets replaced with the fully qualified URL to this particular survey - in HTML emails this is a fully linked HTML link
|}
*'''@@SURVEYURL@@''' - Gets replaced with the survey barebone link. Use this if you want to integrate the link in your custom email HTML (available in v1.90 and later)
*'''{OPTOUTURL}''' - gets replaced with the URL for a respondent to opt-out of this particular survey


<!--T:87-->
<!--T:145-->
Note that these "form fields" apply to the following email fields.
<div class="simplebox">[[File:help.png]] '''Hints:'''
#'''Email Reminder Subject''': The subject line for the reminder email that gets sent out from the tokens tool
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
#'''Email Reminder''': This is the text for the reminder email that gets sent out when tokens are used with your survey. See "invitation email" for specific details on how this field is used.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
#'''Confirmation Email Subject''': When tokens are used, this is the subject line of the email that gets automatically sent to participants after completion of the survey
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>
#'''Confirmation Email''': This is the text of the email that gets sent to users after completion of the survey. Delete/blank this text remove the confirmation email sending.
#'''Public Registration Email Subject''': This is the subject line for the invitation email sent to members of the public who register for a survey.
#'''Public Registration Email''': This is the text for the invitation email sent to members of the public who register for a survey. The same "form fields" apply in this email as in the earlier ones.


<!--T:146-->
{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}


==== Participant opt-out==== <!--T:95-->
 
==Participant Opt-out== <!--T:95-->


<!--T:96-->
<!--T:96-->
When you use the {OPTOUTURL} tag in your invitation/reminder email, your participants have the possibility to opt out of this particular survey by just clicking on the related URL in the email - so you don't harass them with reminder emails. A participant that opted out of your survey will have the email status 'OptOut' set in the token.
When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].
 
==Barebone URL== <!--T:170-->
 
<!--T:171-->
URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …
 
=Using Replacement Function= <!--T:11-->
 
<!--T:12-->
Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.
 
<!--T:13-->
The below example uses a plain link to the survey instead of a long url:
 
<!--T:14-->
1) First, access the email templates panel and choose ''Invitation''.
 
<!--T:147-->
2) Write the text you want to appear as a link to start the survey.
 
<!--T:148-->
3) Then select that text.
 
<!--T:149-->
[[File:mark_text_to_hyperlink.jpg]]
 
<!--T:150-->
4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.
 
<!--T:151-->
[[File:add_link_placeholder_choose_other.jpg]]
 
<!--T:15-->
Now, when you send out your invitation emails, the link to start the survey will be shorter.
 
= Email Attachments = <!--T:152-->
 
== File Actions == <!--T:153-->
 
<!--T:154-->
When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:
 
 
<!--T:155-->
[[File:Upload_files_-_email_templates.png]]
 
 
<!--T:156-->
Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.
 
<!--T:157-->
You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.
 
<!--T:158-->
Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:
 
 
<!--T:159-->
[[File:Files_table_-_email_templates.png]]
 
 
<!--T:160-->
To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.
 
<!--T:161-->
To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.
 
<!--T:162-->
All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.
 
<!--T:163-->
With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.
 
<!--T:164-->
If you want to delete a file, click the red trash button located under the Action column and save the changes.
 
<!--T:165-->
{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}
 
== Image Attachment == <!--T:166-->
 


<!--T:167-->
You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.




<!--T:168-->
<center>[[File:Image-email-embed.png]]</center>




P.S. CHECK THE HTML EDITOR YOU USE
<!--T:169-->
{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}
</translate>
</translate>

Latest revision as of 15:35, 14 September 2022

Other languages:


Introduction

The email templates are used to send personalized invitations, reminders, confirmations, and registration emails to your participants (from the survey participants table). You can also edit the standard basic (or detailed) admin notifications that are sent to the survey administrators.

Email Templates: Settings > Survey menu > Email templates



If you have the superadministrator permission (you have access to the global settings of your LimeSurvey installation), you can change the Default HTML editor mode for all of your LimeSurvey users. For further details, continue reading the following wiki subsection.


  Attention : If you want to use the popup/inline HTML editor, do not forget to enable the HTML format for token emails! This is located in the Settings menu of your survey, under the Participant settings tab.


Email Templates Panel

The email templates panel:



In the above screenshot the "HTML source" editor mode is used. To change it, go to your personal account settings.


To edit the text fields, go to your account settings and choose the inline HTML editor mode.


Five types of emails can be sent to users or admins:


Invitation

This functionality is used to send emails in bulk to all survey participants in the survey participants table who have not yet received an invitation to complete your survey.

From the email templates panel, you can edit the message sent to survey participants. To check which email placeholders can be used, continue reading the following wiki subsection. You can also use the ExpressionScript to further customize your invitation email template.

Reminder

The Reminder functionality provides a way for survey administrators to remind the participants from the survey participants table to answer the survey.

You can edit the default format of the reminder email from the Email templates panel. To verify which email placeholders can be used, continue reading the following wiki subsection. The ExpressionScript can help you customize the text body of this email template.

Note: A reminder will be sent only to those participants in the survey participants table where the "Completed" field is turned off. This means the respondent has either not taken or completed the survey.

Confirmation

If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the Participant settings panel.

Click the Confirmation tab if you want to edit the email template. Check the email placeholders to see which ones can be used in this type of email. You may also use the ExpressionScript to customize your email.

Registration

If closed-access mode is enabled (there is a survey participants table, which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants to publicly register to your survey, a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a registration email. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the registration tab to edit the format of this email. Don't forget to take a look first at which email placeholders can be used within the text body. The ExpressionScript can provide further customization to the body text you wish to use.

Basic & Detailed Admin Notifications

To get admin notifications, click the Data management tab and type in an email address in the "Send basic admin notification email to" field and another one (or the same) in the "Send detailed admin notification email to" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the ExpressionScript and the email placeholders you can customize these two email templates.

Email Templates Fields

Each email template contains:

  • The subject of the email: The title of the email/batch of emails you want to send;
  • The email body: A text box that contains the text message you want to send to the participants. It may contain text, images, and email placeholders. The ExpressionScript can also be used to further customize the message you want to deliver;
Note: Another tab is displayed above the tab with the email templates tab if your survey uses additional languages. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the Save button located in the upper-right part of the screen to save your changes.


  • Email actions: Two actions are available:
    • Reset this template: Once clicked, the HTML code is reset. No text is deleted;
    • Validate expressions: Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.


Email Placeholders

  Attention : Please note that some email placeholders can be used only within certain email templates! Read below for further details.


In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your survey participants list. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder email templates. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and survey participants table.

{ADMINEMAIL} Email of the Survey admin
{ADMINNAME} Name of Survey Admin
{SURVEYNAME} Title of your survey
{SURVEYDESCRIPTION} Description of your survey

The following placeholders are allowed in invitation/reminder email templates (subject and/or body fields) and they will be replaced when sending out the emails:

{EMAIL} Email of the recipient
{FIRSTNAME} First Name
{LASTNAME} Last Name
{SURVEYURL} The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
@@SURVEYURL@@ The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
{OPTOUTURL} The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
{OPTINURL} If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
{GLOBALOPTOUTURL} The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
{TOKEN} The token to access the survey
{USESLEFT} The number of uses left for the token
{VALIDFROM} The date the token is valid from
{VALIDUNTIL} The date the token is valid until
{EMAILSTATUS} Used for skipping emails on email sending. Default email status is "OK".
{LANGUAGE} Used to define the language to be used for emails and survey URL when using multilingual surveys
{SENT} Invitation send date in ISO8601 format with time (Y-m-d H:i:s in PHP)
{REMINDERSENT } Reminder send date in ISO8601 format with time (Y-m-d H:i:s in PHP)
{REMINDERCOUNT} Number of reminders already sent
{COMPLETED } Survey completion date
{TID} Internal ID at token table
{ATTRIBUTE_1} Attribute 1
{ATTRIBUTE_2} Attribute 2 (...and so on for more attribute fields)

If your survey is not anonymous, the email placeholders can be used in order to add specific entry/participant data into the Survey text elements panel (e.g., survey description, welcome message, end message).

{TOKEN:EMAIL} Displays the email of the participant from the survey participants table
{TOKEN:FIRSTNAME} Displays the first name of the participant from the survey participants table
{TOKEN:LASTNAME} Displays the last name of the participant from the survey participants table
{TOKEN} Displays the token code of the participant from the survey participants table
{TOKEN:ATTRIBUTE_1} Displays "Attribute 1" of the participant from the survey participants table
{TOKEN:ATTRIBUTE_2} Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
To find out more about attributes, read the following wiki section.

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{VIEWRESPONSEURL} Displays an URL that redirects you to the respondent's submitted answer
{EDITRESPONSEURL} Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
{STATISTICSURL} Click this URL to access the statistics of the survey
{ANSWERTABLE} If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
Hints:
Before sending the emails, we highly recommend the validation of your email templates - click on the validate expressions button located under the email text body.


Participant Opt-out

When you use the {OPTOUTURL} tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the survey participants list.

Barebone URL

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

Using Replacement Function

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose Invitation.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

Now, when you send out your invitation emails, the link to start the survey will be shorter.

Email Attachments

File Actions

When clicking Add file the following window will be displayed asking you to choose the document from the files folder that you want to send via email:



Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the upload button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the Files table, below the Add File button:



To have it permanently attached to the respective email template, do not forget to click the Save button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the ExpressionScript can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use question codes used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

  Attention :
  • When a file can not be found on the file system, the email will be sent without an attachment.
  • Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.


Image Attachment

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.



  The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.


Retrieved from "http://manual.limesurvey.org/index.php?title=Email_templates&oldid=174439"