====== mailSchedule() ======

''void **mailSchedule**(string //personID//, int //mailing//, int //time//, [array //settings//])''

This function prepares the sending of a mailing directly in the questionnaire -- for example, the invitation to the second questionnaire. In contrast to ''[[:en:create:functions:mailresume|mailResume()]]'', the current interview will not be resumed. Instead, the mailing is sent in the same way as if it had been prepared manually.

**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, enter ''false'' to resolve the ID automatically.
  * //mailing//\\ (Numerical) ID of the mailing which should be sent to the participant.
  * //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.
  * //settings//\\ Optional settings, specified as associative array with the following keys:
    * '''status'''\\ Send reminder/follow-up emails only if the link in the original serial mail ...
      * '''finished''' -- ...opened and the questionnaire was filled out to the end
      * '''incomplete''' -- ...was not opened __or__ not filled in to the end
      * '''no-response''' -- ...was not opened
    * '''expire'''\\ Limit the validity of the personal participation link, the same format as for the //time//
    * '''to.email'''\\ Do not send e-mail to the e-mail address stored in the address entry, but to the e-mail address specified here. This function can be used to notify the project manager if a respondent does not complete a (follow-up) questionnaire within a defined time.
    * '''to.mobile'''\\ Do not send SMS to the phone number (possibly) stored in the address entry, but to the phone number specified here. The phone number must be specified with country code.
    * '''%custom1%''' to '''%custom5%'''\\ If contents for user-defined fields are specified in the ''mailSchedule()'' -command, in the serial mail  these contents are used instead of the address entry.
 
**Note:** A mailing is sent (in contrast to ''mailResume()'') only once per recipient, even if the function is called up repeatedly. Sending different mailings is possible -- e.g. an invitation to take part in the second wave of the survey in 14 days and a further invitation to the third wave in 1 month.

**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 ideally suited to this purpose. 

===== Invitation to Follow-Up Survey =====

A participant was invited to take part in the questionnaire via a mailing. 14 days after he clicked on the link, and thus accessed the questionnaire, he should receive an invitation to the second questionnaire (mailing no. 2)

<code php>
mailSchedule(false, 2, strtotime('+14 days'));
</code>

Instead of using the function ''strtotime()'', the time period can also be specified in seconds: 14 days = 336 hours = 1209600 seconds.

<code php>
mailSchedule(false, 2, 1209600);
</code>

===== Reminder E-Mails =====

The respondent is invited to the first questionnaire (wave 1) with serial mail 1 -- the invitations are staggered so that a-priori it is not known when the respondent will complete the questionnaire. One month after completing the first questionnaire, the respondent should receive an invitation to the second wave of the survey (serial mail 2). If the respondent does not participate, a reminder (serial mail 3) should be sent after one week.

In Serial Mail 3 it is set to be a reminder/follow-up mail for Serial Mail 2.

The following PHP code is used in the questionnaire for the first survey wave:

<code php>
mailSchedule(false, 2, strtotime('+1 month'));
mailSchedule(false, 3, strtotime('+1 month +1 week'), [
  'status' => 'no-response'
]);
</code>


===== Custom Fields =====

The following command sends the serial mail with the ID 2 on the next Monday at 8 o'clock to the person, who just completes the questionnaire. Instead of the placeholder ''%custom1%'' the serial mail shows the date when ''mailSchedule()'' was called.

<code php>
mailSchedule(false, 2, strtotime('next Monday 08:00:00'), [
  '%custom1%' => date('d.m.Y')
])
</code>