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.

Important: The email will only be sent if the respondent is already registered in the list of contacts for mailings.

• 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
  
  • The delay until the dispatch (in seconds, maximum 315576000, corresponding to 10 years).
  • A Unix timestamp that defines the point in time for the next dispatch.
  • A time specification as a string, as accepted by the function strtotime(), see Supported Date and Time Formats (PHP).
• settings
  Optional settings, specified as associative array with the following keys:
  • 'status'
    (string|array) Only send reminder/follow-up mails if the link in the original mailing …
    • 'finished' – …was opened and the questionnaire was filled out to the end
    • 'dropout' – …was opened, but the questionnaire was not 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.
  • 'reply.to'
    Email address that shall be specified in the email for replies. This setting is only effective if the user account is permitted to set an individual sender, e.g., if sending emails via SMTP is configured.
  • 'catch.up'
    If a numeric value (time in seconds) is specified for this key, the function mailSchedule() also allows points in time in the past and catches up on the dispatch immediately in such a case. Otherwise, no email is sent for a point in time in the past. Example: The value 604800 (7×24×3600) would still send an email if the dispatch time is up to 7 days in the past.
  • '%custom1%' to '%custom5%'
    If contents for user-defined fields are specified in the mailSchedule() -command, these contents are used in the mailing instead of the information in 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.

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, '+14 days');

A time interval 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, '+1 month');
mailSchedule(false, 3, '+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, 'next Monday 08:00:00', [
  '%custom1%' => date('d.m.Y')
]);