Distributing Surveys

Source: vignettes/distributions.Rmd

There is a vast number of distribution related operations you can automate through the Qualtrics API. In this package, we provide the following calls:

  • list_distributions
  • get_distribution
  • delete_distribution
  • create_email_distribution
  • create_reminder_distribution
  • create_thankyou_distribution
  • generate_distribution_links
  • list_distribution_links
  • send_email_mailinglist

A number of equivalent calls for sms based distributions are available. Although implemented in the packge, these functions are not yet made available to the user due to our inability to perform any kind of testing.

Scheduling a Qualtrics email distribution

The method described below is a standard approach for people sending their survey to a predefined list of participants through the Qualtrics emailing service. The use of the API can facilitate the process of managing such distributions for multiple contact lists with different mailing strategies, for example.

To create a new email distribution, you will need to have created an email body, saved as a Qualtrics library item in your account (see functions list_messages and create_message). You will also need the id of the contact list to send the survey to (see functions list_mailinglists and create_mailinglist).

We show below a step-by-step process to set-up your first email distribution. First, we retrieve the account library id needed throughout all steps.

list_libraries()
#> # A tibble: 2 × 2
#>   libraryId          libraryName      
#>   <chr>              <chr>            
#> 1 UR_1Z96ysDAytOdL2l Qualtrics in R   
#> 2 GR_8jjjgh5XPTwmjit Qualtrics Library

For a simple user account, you will usually have available the account library and the default Qualtrics library. You’ve probably saved your email message in your account library.

You can now list all messages available in the account:

list_messages("UR_1Z96ysDAytOdL2l")
#> # A tibble: 3 × 3
#>   id                 description      category
#>   <chr>              <chr>            <chr>   
#> 1 MS_1AMM3cE022E0rUF Invitation Email invite  
#> 2 MS_bvFkAsjp0Womse1 Thank You Email  thankYou
#> 3 MS_5oNdvwUJhJBHq5L Reminder Email   reminder

We’ve prepared three messages to use in the example which we now know the id of. Obviously, we will first create the distribution using the Invitation Email message.

Finally, we need to retrieve the contact list id for the email recipients.

list_mailinglists()
#> # A tibble: 2 × 5
#>   libraryId          id                 name                  category  folder  
#>   <chr>              <chr>              <chr>                 <chr>     <chr>   
#> 1 UR_1Z96ysDAytOdL2l ML_1ZlloFpR0AOl2GV contacts_test_api     api_tests /api_te…
#> 2 GR_8jjjgh5XPTwmjit ML_eer9soMmLieCcuh y5r2 cc radio placem… Unassign… <NA>

We will use the contact list contacts_test_api. Your can use the list_surveys function to retrieve the survey id for which you want to shcedule the distribution:

list_surveys()
#> # A tibble: 9 × 6
#>   id                 name       ownerId    lastModified   creationDate  isActive
#>   <chr>              <chr>      <chr>      <chr>          <chr>         <lgl>   
#> 1 SV_39rgGREdlmzH63X api_copy_… UR_1Z96ys… 2020-06-11T08… 2020-06-10T0… TRUE    
#> 2 SV_3fmfHkdddhnRbKJ api_copy_… UR_1Z96ys… 2020-06-11T08… 2020-06-11T0… FALSE   
#> 3 SV_6WpcSqtVBsibNcN api_copy_… UR_1Z96ys… 2020-06-11T08… 2020-06-11T0… FALSE   
#> 4 SV_9Ak7vCha9W42Twp api_copy_… UR_1Z96ys… 2020-06-11T08… 2020-06-11T0… FALSE   
#> 5 SV_aYwagyEbamVLpFX api_copy_… UR_1Z96ys… 2020-06-11T08… 2020-06-11T0… FALSE   
#> 6 SV_blW4HuzdeqLiTJ3 api_expor… UR_1Z96ys… 2020-04-16T18… 2020-04-16T1… TRUE    
#> 7 SV_cScDRSV5hsN3YEd api_distr… UR_1Z96ys… 2020-06-10T08… 2020-04-16T0… TRUE    
#> 8 SV_elpspu2EuJXLEWx api_expor… UR_1Z96ys… 2020-04-16T18… 2020-04-16T1… TRUE    
#> 9 SV_esXQqpyoyNFeW69 api_copy_… UR_1Z96ys… 2020-06-11T08… 2020-06-11T0… FALSE

We are now ready to create our email distribution:

distribution_id <- create_email_distribution(
  "SV_cScDRSV5hsN3YEd", # survey id
  "UR_1Z96ysDAytOdL2l", # library id
  "MS_1AMM3cE022E0rUF", # email message id
  "ML_1ZlloFpR0AOl2GV", # contact list id
  "john.doe@qualtrics.com",  # sender email
  "John Doe", # sender name
  "Participate in this survey",  # email subject
  "2022-04-01T00:00:00Z" # send date
    )
print(distribution_id)
#> [1] "EMD_UHNZm9NI2Rc7yty"

This call will return the id of the newly created distribution which allows you interact with the distribution: create a reminder distribution, schedule an thank you message, etc. Note that you can always recover the distribution id by listing all distributions using the list_distributions function.

Note that our Qualtrics account may be set with a different time zone than your local environment. Make sure to specificy your date fields accordingly.

There are a number of optional parameters you can find in the function documentation. It is important to note that by the default, the sender email will be set to . You can only use custom email address if your account is appropriately configured to do so (see qualtrics documentation)

We can already schedule a reminder email for the survey using the Reminder Email email message id:

create_reminder_distribution(
  distribution_id, # parent distribution id
  "UR_1Z96ysDAytOdL2l", # library id
  "MS_5oNdvwUJhJBHq5L", # email message id
  "Reminder - Participate to the survey", # email subject
  "2022-04-08T00:00:00Z" # send date
)
#> [1] "EMD_ZWgIdqY1F7HtI2c"

Note that if you do not want to have to create the email message in Qualtrics before sending the email, the you can use the function send_email_mailinglist.