====== mailSend() ======

''void **mailSend**(string //email//, int //mailingID//, [int //time//], [string //link//], [string //C1//, string //C2//, string //C3//, string //C4//, string //C5//])''

''void **mailSend**(string //email//, int //serialmailID//, array //settings//)''

The ''mailSend()'' function sends the mailing with the //mailingID// ID to a specified email address straightaway or at a defined point in time. The email address does not have to -- in contrast to the ''[[:en:create:functions:mailResume]]'' and ''[[:en:create:functions:mailSchedule]]'' functions -- be known in the project's **List of Contacts** beforehand.


  * //email//\\ Email address where the email should be sent to 
  * //mailingID//\\ Numerical ID of the mailing to be sent 
  * //time// (optional)\\ Either the delay until the mailing is sent (in seconds, maximum 153900000) __or__ a Unix timestamp that defines the time when it should next be sent. 
  * //link// (optional)\\ URL used for the ''%link%'' placeholder in the mailing. If no URL is specified,  the [[:en:survey:url]] is used without further specification of a questionnaire.
  * //C1// to //C5// (optional)\\ If you have specified text here (optional), you can use this text in the mailing with the help of placeholders ''%custom1%'' to ''%custom5%''. When used with ''value()'', you can, for example, display responses from the ongoing interview in the email.
  * //settings// (optional)\\ If an array is passed as third parameter, the further settings are taken from this array. The following keys are possible:
    * ''%%'sendtime'%%'' -- corresponds to the parameter //time//
    * ''%%'update'%%'' -- SBy default an email is sent with every call of ''mailSend()''. If there is a value for '''update''' and an e-mail has already been scheduled for sending (not yet sent) in the survey project with ''mailSend()'', which contains the same value for '''update''', then the sending date and all data will be updated instead of preparing another e-mail. For example, if you only want to send one e-mail per interview, then use e.g. ''%%'update' => caseToken()%%''.
    * ''%%'%link%'%%'' -- corrsponds to the parameter //Link//
    * ''%%'%custom1%'%%'' to '''%custom5%''' -- Content for the placeholders of the same name in the serial mail
    * ''%%'attach'%%'' -- variable ID (string) or several identifiers (array) of uploaded files (question of type "upload file"), which should be attached to the e-mail. Specify a key in the array to specify the file name for the attachment.
    * ''%%'unique'%%'' -- Any value identifying the content and/or recipient of the message. By default, the e-mail address is used as a characteristic for sending. If a user-defined unique value is specified, the same mailing can be sent multiple times to that email address. The precondition is that a different unique value is specified for each dispatch.

  
  
  

===== Tips =====

  * A specific mailing can only be sent to a specific email address once per interview with the ''mailSend()'' function. You can customize this with ''%%'unique'%%''.
  * A maximum of 20 emails can be sent during an interview using ''mailSend()''.
  * The e-mail addresses are stored in the server's log files together with a time stamp. The storage time of the log files depends on the configuration of the server.

===== Example: Info to project management =====

Each time an interview is completed, an email should be sent to the project lead ''lead@example.com''.

  * Create a mailing under **Send invitations** -> **Mailings**
  * To do this, insert another page before the "last page" in the questionnaire. Place the following PHP code on this.

<code php>
mailSend('lead@example.com', 1);
</code>

Of course, the ''1'' must be replaced with the identifier/number of the mailing that is to be sent.


===== Example: Data to project management =====

A participant fills out a test, the point value was calculated in variable ''$points'' and should now be sent to an email address together with the participant ID (SERIAL) so that the researcher is automatically informed about completed tests.

For this purpose, a mailing (ID 1) was created under **Send invitations** -> **Mailings**, which has (among other things) the following content:

<code>
participant: %custom1%
test result: %custom2%
</code>

On the last page of the questionnaire the following PHP code would now be placed under the calculation of the points value (''$points'') to send the result to ''store@example.com''.

<code php>
mailSend('store@example.com', 1, 0, NULL, caseSerial(), $points);
</code>


===== Example: Do not save email address =====

A colleague's email address should be requested in the interview, but not saved. An invitation should be sent to this email address with a reference to the current interview (case number CASE).

**Note:** This use case is usually easier to implement with a question of type [[:en:create:questions:email]] and without any PHP code. Here only an alternative solution using ''mailSend()'' is shown.


In order to get the email address, an HTML input field is put on page 5 in the questionnaire.


<code html>
<div>
  Colleague's email address:
  <input type="text" name="email_colleague" style="width: 160px" />
</div>
</code>

On the next page in the questionnaire (no later!), the specified email address is read using ''[[:en:create:functions:readget]]'' and the mailing with the ID ''2'' will be sent to this email address. The current case number is attached in the URL to the questionnaire as a reference.


<code php>
$email = readGET('email_colleague', false);
if (trim($email) !== '') {
  $link = 'https://www.soscisurvey.de/PROJEKT/?r='.caseNumber();
  mailSend($email, 2, 0, $link);
}
</code>


===== Data Protection Details =====

When using mailSchedule(), SoSci Survey stores the specified e-mail address until the time of sending.

The address (along the time when to send it) is stored in the database in which SoSci Survey also stores the questionnaires and the collected data.