====== mailResume() ======

''void **mailResume**(string //personID//, int //mailing//, int //time//, [string //C1//, string //C2//, string //C3//, string //C4//, string //C5//])''

This function sends an email during the current questionnaire with a link in order to resume the questionnaire at a later point in time. This is particularly useful when combined with a specific break in multi-wave surveys (''[[:en:create:functions:buttonhide|buttonHide()]]'').

**Note:** The email will only be sent if the participant is already registered in the mailing list.

  * //personID//\\ The personal ID of the addressee who should receive the email. If the participant began the questionnaire after receiving an invitation via mailing, you can fill in ''false'' and a suitable ID will then be automatically determined. Alternatively, the personal ID can be determined using ''[[:en:create:functions:caseserial|caseSerial()]]''.
  * //mailing//\\ (Numerical) mailing ID which should be sent to the participant. In the tab //Reminder/Follow-up Email// for the mailing, the value must be configured to "Reminder or Continuation" as the //Type of Follow-up Email//. Please take the notes below into consideration.
  * //time//\\ Either the delay in email delivery (in seconds: maximum 153900000) __or__ a Unix timestamp, which defines the time until the next email is sent.
  * //C1// to //C5// (optional)\\ If you enter text here (optional), you can use this in the mailing with the help of placeholders ''%custom1%'' to ''%custom5%''. When combined with ''value()'', you can display responses from the current questionnaire in the email, for example. 

===== Tips =====

**Note:** A mailing can be sent multiple times to the same addressees by using ''mailResume()''.

**Note:** In the mailing, the placeholder ''%link%'' is not replaced with a regular personalized link (by calling up the questionnaire in this way it possibly starts again from the beginning). Instead, it is replaced by a direct link to the current questionnaire.  

**Note:** If the participants' email addresses are not known a priori, these have to be collected at the beginning of the first questionnaire so that ''mailResume()'' can be used. Alternatively, using separate questionnaires and the function ''[[:en:create:functions:mailschedule|mailSchedule()]]'' is possible ([[:de:survey:opt-in-live|Multi-Wave Surveys with Self-Selection]]).

**Tip:** There are numerous websites on the internet that can covert a date into a Unix timestamp. For example: [[http://www.unixtime.de/|unixtime.de]]. The PHP [[http://www.php.net/manual/en/ref.datetime.php|Date/Time Functions]] (in particular ''[[http://php.net/manual/en/function.mktime.php|mktime()]]'' and ''[[http://www.php.net/manual/en/function.strtotime.php|strtotime()]]'') are also suited to this purpose. 

**Tip:** If you do not want to send the invitation out on a particular date, but rather after a specific delay, specify the delay because ''mailResume()'' is then able to prevent duplication of emails more efficiently. 


===== Pause Questionnaire =====

In the following example, the participant was invited to the questionnaire via a mailing. A page where the questionnaire is paused is placed in the middle of the questionnaire (''[[:en:create:functions:buttonhide|buttonHide()]]'') and the text "end1" is displayed. The participant receives an email after 24 hours stating he may now fill out the second part of the questionnaire. The link in the email leads him to the next page in the previously interrupted questionnaire. 

**Important:** The ''caseTime()'' function only works if you have not unchecked "Record time and dwell time during the survey" in the **Project settings** in the //Privacy// tab. The dwell time is required information for the interrupt pages suggested here.

<code php>
// If the back button is enabled in the questionnaire
// it should not appear on this page
option('backbutton', false);

// Check how much time has elapsed since the start of the survey
// If this is less than 24 hours (24 * 3600 seconds), the questionnaire will be paused
if (caseTime('begin') < 24 * 3600) {
  text('end1'); // displayed at the end of the first part
  option('resume', true); // prevent indication to resume questionnaire
  option('nextbutton', false); // hide the Next button (pause questionnaire)
  // Send ID 3 mailing tomorrow at the same time (i.e. in exactly 24 hours)
  mailResume(false, 3, 24 * 3600);
} else {
  // Did the participant return after 24 hours? If so, continue questionnaire
  goToPage('next');
}
</code>

Alternatively, you can also check the time elapsed since the the page was first accessed (and thus the time since the email was prepared):

<code php>
// Deactivate the back button as required
option('backbutton', false);

// Save the time the page was first accessed
// Due to isset() und registerVariable(), the block is only executed for the first time
if (!isset($timeBreak1)) {
  // Save the time
  $timeBreak1 = time();
  registerVariable($timeBreak1);
  // Prepare email
  // Send ID 2 mailing in exactly 14 days
  mailResume(false, 3, 14 * 24 * 3600);
}

// Check how much time has elapsed since the page was first accessed 
// Pause, if this is less than than 14 days (14 * 24 * 3600 seconds)
if (time() - $timeBreak1 < 14 * 24 * 3600) {
  text('end1'); // displayed at the end of the first part
  option('nextbutton', false); // hide Next button (pause questionnaire)
} else {
  // Perhaps the progress bar should be adjusted?
  option('progress', 0);
  // Did the participant return after 14 days? If so, continue questionnaire
  goToPage('next');
}
</code>


===== Emailing the Project Manager =====

The function ''mailResume()'' can be "misused" to inform the project manager about incoming questionnaires.  Therefore, it is necessary to import the project manager's email address into the list of contacts ([[:en:survey:mailing|Send Mailings]]). It is essential that the email address imported is not //anonymous//. 

The address entry's personal ID can then be determined from the list of contacts. This is displayed when the mouse is placed over the address entry or when it is opened for editing. In the example, the person ID "ABCDE123" is used. 

If an additional mailing (number 3) was created, the following PHP code informs that a partipant has reached the current page in the questionnaire. 


<code php>
mailResume('ABCDE123', 3, 0);
</code>


===== Serial Mail After Opt-In Question =====

With a question of type [[:en:create:questions:opt-in]] you can ask for e-mail addresses in the questionnaire and enter them directly into the address list (**List of Contacts**), so that you can send serial mails to the e-mail addresses later.

This section explains how to use ''[[:en:create:functions:mailschedule]]'' to automatically trigger the scheduled or immediate sending of a serial mail to the entered e-mail address.

There are two mechanisms for the opt-in question: The Double-Opt-In (the respondent must first confirm the address entry via confirmation email, recommended) and the Single-Opt-In, where the (possibly wrong) email address is stored directly.

  - With Double-Opt-In it makes sense to trigger the dispatch only after confirmation of the mail address. How this works is explained in the following chapter: [[:/en:survey:opt-in-live]].
  - If you want to send the serial mail directly, you can use the confirmation mail of the (double-)opt-in question as invitation mail for a questionnaire at the same time (//Further settings// -> //Forwarding after confirmation// -> //Questionnaire link off//). However, the link in the confirmation email is only valid for 24 hours. A "real" serial mail invitation is usually valid for the entire survey period, unless the validity is limited in the serial mail settings.
  - If a "real" serial mail should be sent after a Single-Opt-In, the function ''mailSchedule()'' is used. This is explained in more detail below.

The PHP code with the ''mailSchedule()'' is placed (at the earliest) on the page that follows the opt-in question. Only there the survey server knows the new e-mail address and has assigned it a personal ID (SERIAL). This personal ID is required as first parameter for the function ''mailSchedule()'' (as otherwise often used ''false'').Where do you get the ID from? If the respondent entered an email address in the opt-in question, it is noted in the record in a variable that has the same identifier as the opt-in question.

In the following example, the opt-in question on page 9 would have the ID "OI01". On page 10 (or later) the following PHP code would then immediately send the serial mail with the ID 2. The ''value('OI01')'' returns the subscriber ID (SERIAL) of the new address entry.

<code php>
mailSchedule(value('OI01'), 2, 0);
</code>

The following PHP code would send the serial mail with the ID 3 after 14 days:

<code php>
mailSchedule(value('OI01'), 3, strtotime('+7 days'));
</code>

Of course you can also prepare several serial mails:

<code php>
mailSchedule(value('OI01'), 2, 0);
mailSchedule(value('OI01'), 3, strtotime('+7 days'));
mailSchedule(value('OI01'), 4, strtotime('+14 days'));
</code>

If there is a possibility that the respondent does not enter an e-mail address, an ''if'' should be added to avoid error messages:

<code php>
$serial = value('OI01');
if ($serial) {
  mailSchedule($serial, 2, 0);
  mailSchedule($serial, 3, strtotime('+7 days'));
  mailSchedule($serial, 4, strtotime('+14 days'));
}
</code>

Note that the personal ID (SERIAL) here is cached in a PHP variable (''$serial'') to be used directly in the ''mailSchedule()'' calls. Of course you could also use ''value('OI01')'' here.