====== Opt-In for mailing list ======


Should you collect e-mail addresses for an addresslist, you ususally want to make sure, that a) the address really exists and b) that the address was entered by the owner himself and not a third party.
The common (and in part legally required) procedure for this is called Double-Opt-in. First, the person enters their e-mail address on a website (respectively the quetionnaire) (first „opt in“) and, after that, receives an Email. Secondly, in this E-mail, the person will find a link, which is to be clicked on for confirming the first entry (second „opt in“). Only then will the E-mail address be admitted to the addresslist.


In SoSci Survey this procedure can be applied, using a question type called „Opt-In E-Mail-Verteiler“ (Opt-In E-mail addresslist). This is a type of question, which asks for E-mail addresses (and optionally further data) in your questionnaire and takes care of sending out E-mails. 
After the confirmation of the Email address entry, that particular E-mail address may be used for mailings [[:en:survey:mailing]] – for example to send out invitations for a post enquiry. 

This type of question may be useful in...

  * a seperate questionnaire, which only serves as an appication/registration form for your study.
  * to enable a post enquiry of the just surveyed participants  ([[:en:survey:opt-in-live]]).


**CAUTION:** Should you collect E-mail addresses solely for a prize game or to send partcipants a summary of the results at their desire, pease consider using the questionnaire type "[[contact]]" which is generally more suitable.

**CAUTION:** In the default setting, E-mail addresses are being saved anonymously.
That means, you may not match the interviews with the respective E-mail address – the data remains anonymous.
Matching the first interview with subsequent follow up studies is possible via an indentification code ([[:en:survey:mailing#privacy mode|Privacy Mode]]).

**CAUTION:** E-mail addresses may only be entered once into the addresslist.
If the E-mail address is already listed, a corresponding status signal will appear.

**CAUTION:** The confirmation link in the Opt-In-Mail is valid for 7 days.

**Tip:** The address list for mailings may also be administered manually under **List of Contacts**. Also the registered addresses may be exported here ([[:en:survey:panel-download]]). 


===== Anonymity and assignment of datasets =====

A question creates a variable in your dataset. Here, a distinct ID will be filed for the registered address, the  //Personenkennung// (personal key). In the default setting this personal key (Personenkennung) is not displayed in the **List of Contacts**, hence the interview stays anonymous. In this context,  SoSci Survey serves as a trustee for the personal reference, saving the allocation (or connection) of the personal key and the respective address internally.
Should the participant be invited to complete another questionnaire, the //Personenkennung// personal key will be filed anew in the dataset (in the variable //SERIAL//, see [[:en:results:variables#interview_identification|Additional Variables in the Data Set]]), so a clear assignment is made possible.  

**Caution:** Should you wish to assign your interviews to the individual e-mail addresses, please change the privacy mode of the opt-in question to "individual-related".


===== Usage =====

Create a question of the type "opt-in for mailing list" and place it in the questionnaire under **Compose Questionnaire** either by dragging and dropping it into the questionnaire or using the PHP command ''[[:en:create:functions:question]]''.

The entries in the **List of Contacts** can be assigned to different subgroups -- for example, to send invitation e-mails only to parts of the panel or to send different mailings to different target groups. In the opt-in question, you can specify to which subgroup //subgroup// a new address entry is to be assigned.

**Tip:** The //subgroup// can be determined in later interviews, which were started by means of a personalized link in a serial mail, by means of ''[[:en:create:functions:paneldata]]''. See below for more information.

Furthermore, you can specify in the question to ask not only for the email address but also for the title, name, and gender. This information is stored directly in the address entry (not in the data record!) and is used to personalize invitation emails. Requesting a mobile number only makes sense if you want to send invitation SMS.

The placeholder ''%opt-in%'' must be used in the //contents of the confirmation mail//. An individual link is placed in its place, which the participants must click to confirm their address entry. The confirmation mail should also clearly indicate which research project it belongs to and what the participant confirms by clicking on the link. In the inbox, this email may be located next to a number of dubious spam mails.

If the participant clicks on the confirmation link, there are two possibilities: (1) It arrives on a website that displays the //text// in the layout of your questionnaire and/or (2) it is forwarded to a questionnaire. If you want the participant to be forwarded directly to a questionnaire without further text, do not enter anything for //text at confirmation//.

==== Placeholder ====

The following placeholders are available for the //content of the confirmation mail//.

^Placeholder^Function^
| ''%opt-in%'' | URL for confirmation |
| ''%opt-out%'' | URL to explicitly delete the entry |
| ''%email%'' | given e-mail address |
| ''%email.cc%'' | given CC-address|
| ''%valid%'' | Validity of the Opt-In URL |
| ''%salut%'' | Salutation consisting of any gender, title and/or name information provided |

For the HTML content, the placeholders for Opt-In and Opt-Out are assigned slightly differently.

^Placeholder^Function^
| ''%opt-in%'' | Link to the confirmation-URLs |
| ''%opt-out%'' | Link to the delete-URL |
| ''%opt-in.url%'' | URL for confirmation |
| ''%opt-out.url%'' | URL to explicitly delete the entry |



===== Directly to the Questionnaire =====

If you want the participant to be forwarded directly to a questionnaire after confirming his/her address record, create a new mailing under **Invitation Mailings** -> **Mailings**, select the desired questionnaire in the tab "Questionnaire URL" and save.

Then open the opt-in question and select //Personalized link from// and select the mailing you just created.

If the participant is forwarded to the questionnaire after the confirmation, it is technically as if he/she had received the selected mailing and clicked on the personalized invitation link. This means: The //Personal ID// is stored in the variable //SERIAL// and the functions ''[[:en:create:functions:caseserial]]'', ''[:en:create:functions:mailschedule]]'', ''[[:en:create:functions:paneldata]]'' and so on are available.


===== Test Functionality =====

The interaction of online questionnaire and e-mail is not always trivial. Especially if you work with several questionnaires, a detailed check of the opt-in question in the [[:en:survey:function-test]] is advised.

Remember that each email address can only appear once in the **List of Contacts** (unless you explicitly allow for duplicates). You can delete your test address after each test -- but it's more elegant to use [[https://en.wikipedia.org/wiki/Disposable_email_address|disposable addresses]].

If you work with a time delay in your survey (e.g., sending the serial mail after one month), you can simply set times in the range of a few minutes for testing.


===== Application in Experimental Designs =====

In a multi-wave survey, it can be useful to ask the respondent for his/her email address right at the beginning. This is particularly useful if participants who have not completed both/all questionnaires are dropped from the evaluation. On the other hand, participants may only be willing to reveal their email address at the end of the first questionnaire -- after all, a certain amount of trust is needed compared to the researcher, i.e., that the information will remain truly anonymous and that the email address will not be passed on to third parties (violations of this can be subject to high penalties, by the way).

This example explains how to assign the participant to an experimental group in the first questionnaire, how to retrieve the e-mail address via an opt-in question and how to know in the second questionnaire (about a month later) which experimental group the participant was in.

  * Create two (!) questions of the type "opt-in for mailing list" and enter a different subgroup in both of them, e.g., "CG" and "EG". In the example it is assumed that the questions have the identifiers "OI01" and "OI02".

  * Create a question of the type [[:en:create:questions:random]] with two items for the random drawing. One item is drawn from the random generator for each interview. In the example, the ID "ZG01" is assumed.

  * Drag the random generator into the first questionnaire on that page where you need the group assignment -- for example to show the correct stimulus (details see [[:en:create:questions:random]]). At the end of the questionnaire, display one of the two opt-in questions depending on the group assignment:

<code php>
if (value('ZG01') == 1) {
  question('OI01');
} else {
  question('OI02');
}
</code>

  * If you want to automatically schedule the invitation to the second survey, use the function ''[[:en:create:functions:mailschedule]]''. The first parameter to be entered is the person ID from the opt-in question -- therefore, the ''mailSchedule()'' function must not be on the same page as the opt-in question, but at the earliest on the following page. If you want the opt-In question to appear on the last page, add a blank page (apart from the PHP code) behind it.

<code php>
$personID = value('OI01');  // Get person ID from the opt-in question
$zeitpunkt = strtotime('+1 month');  // Determine Unix time in exactly one month
// Send serial mail 1 at the determined time
mailSchedule($personID, 1, $zeitpunkt);
</code>

  * After one month the participant will receive an email with the personalized participation link -- it doesn't matter if you used ''mailSchedule()'' or send the emails via the mailing function to a certain date. Using the subgroup, you can now determine which experimental group the participant is in:

<code php>
$info = panelData();
if ($info) {
  $group = $info['subgroup'];
  if ($group == 'EG') {
    question('AB01'); // Show question AB01
    text('after-stim01'); // Display text element
  } else {
    question('AB02'); // Show question AB02
    text('after-stim02'); // Show other text
  }
}
</code>