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 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: unixtime.de. The PHP Date/Time Functions (in particular mktime() and strtotime()) are ideally suited to this purpose.

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)

mailSchedule(false, 2, strtotime('+14 days'));

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

mailSchedule(false, 2, 1209600);

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:

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

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.

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