Distributions¶

The methods available in the Distributions module give you the ability to create new (email) distributions, create reminders, create thanks you’s, list all of the available distributions for a survey, get a distribution’s information, and a helper method to properly format the set send by date for a distribution.

Format a Distribution’s Send Date¶

Distributions.set_send_date(weeks=0, days=0, hours=0, minutes=0, seconds=0)¶

This method is a helper function to format the send date arguements for several methods in the Distribution Module. The send_date parameter must be in the format “”%Y-%m-%dT%H:%M:%SZ” in order for the API to properly parse the send date. Thus, this method defines the offset for the send_date, and formats it properly. An example would be if you wanted to send a reminder one week from now, simply pass “1” as an argument in to the “weeks” parameter. The default behaviour is for the send_date to be now, thus all params are set to zero offset.

Parameters

weeks (int) – The week offset for the send_date. [Default = 0]
days (int) – The day offset for the send_date. [Default = 0]
hours (int) – The hour offset for the send_date. [Default = 0]
minutes (int) – The minute offset for the send_date. [Default = 0]
seconds (int) – The second offset for the send_date. [Default = 0]

Returns

The formatted DateTime. (str)

Example Implementation¶

Here is an example on how to implement the set_send_date() method, which is a helper method for properly defining the send_date parameter in the create_distribution, create_reminder, create_thank_you methods. So in this example, we will create a new properly formatted send date.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.Survey import Distributions

#Create an instance
d = Distributions()

#Call the method
d.set_send_date(weeks=0, days=2, hours=0, minutes=0, seconds=0)

Technically, you do not need to pass “0” as arguments to the other parameters that were not defined, however in this example I left them in there for you to see. This will return a properly formatted string “strftime” containing the a string representing a timedelta from the time that you execute this method plus the specified timedelta. So, put simply this will return a date two days from the current time.

'2019-10-01T12:00:00Z'

Create a Distribution¶

Distributions.create_distribution(subject, reply_email, from_email, from_name, mailing_list, library, survey, message, send_date, link_type='Individual')¶

This method gives users the ability to create a distribution for a given mailing list and survey. In order to use this method you must already have access to pre-defined Messages and their MessageID’s existing within a User-Defined (starts with UR) or Global (starts with GR) Library. You can list the messages and their MessageID’s(starts with MS) that are available to your user account by using the “QualtricsAPI.Library.Messages.list_messages()” method. As a final note, this method gives users the ability to define the different types of messages.

Parameters

subject (str) – The subject for the reminder email.
reply_email (str) – The reply email address.
from_email (str) – The email address that the distribution is sent from.
from_name (str) – The name that shows up on the distribution.
library (str) – The (Global or User) Library ID which the messages are located within.
message (str) – The Message ID corresponding with the message that is to be sent.
mailing_list (str) – The Mailing List ID corresponding with the Mailing List that the distribution is to be sent to.
survey (str) – The Survey ID corresponding with the Survey that the distribution is to be sent to.
send_date (str) – The date that the distribution is supposed to be sent on. Pass gmtime() for immediate distribution or use the set_send_date() method to format properly.
link_type (str) – This parameter refers to the type of link that is to be sent within the distribution.

Returns

The Distribution ID. (str)

Example Implementation¶

Here is an example on how to implement the create_distribution() method. It is important to mention that you can only create an email distribution using this method. Here we pass in arguments to all of the necessary parameters and we are returned a Distribution ID. To find the IDs associated with the Library, Survey, Message, and Mailing List IDs you can go to you Qualtrics account and find them under the Account Settings tab. As a final comment, if you want to send the distribution immediately, you can pass in gmtime() as the argument to the send_date parameter.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.Survey import Distributions

#Create an instance
d = Distributions()

#Call the method
d.create_distribution(subject="Test Survey", reply_email="fake@fake.com", from_email"fake@fake.com", from_name="Survey Joe", mailing_list="CG_ThisIsaFakeID!!", library="GR_ThisIsaFakeID!!", survey="SV_ThisIsaFakeID!!", message="MS_ThisIsaFakeID!", send_date=gmtime(), link_type='Individual'))

This will return a string containing the Distribution ID associated with the distribution that you just setup.

'EMD_ThisIsaDistID'

Create a Reminder¶

Distributions.create_reminder(subject, reply_email, from_email, from_name, library, message, distribution, send_date)¶

This method gives users the ability to create a reminder for a given distribution. In order to create a reminders you must have already created a distribution for a given mailing list and survey. Once created, you will pass the Distribution ID corresponding to the correct distribution to the distribution parameter and the reminder will be set to that specific distribution. Unlike the QualtricsAPI.Survey.Distribution.create_distribution() method, this method does not require you to specify the mailing list or survey because it will use the parameters defined when the associated distribution was set up.

Parameters

subject (str) – The subject for the reminder email.
reply_email (str) – The reply email address.
from_email (str) – The email address that the reminder is sent from.
from_name (str) – The name that shows up on the reminder.
library (str) – The (Global or User) Library ID which the messages are located within.
message (str) – The Message ID corresponding with the message that is to be sent.
distribution (str) – The Distribution ID corresponding with the distribution that the reminder is to be attached to.
send_date (str) – The date that the reminder is supposed to be sent on. Pass gmtime() for immediate distribution or use the set_send_date() method to format properly.

Returns

The “Reminder” Distribution ID. (str)

Example Implementation¶

Here is an example on how to implement the create_reminder() method. As with the create distribution method, it is important to mention that you can only create an email reminder distribution using this method. Here we pass in arguments to all of the necessary parameters and we are returned a Distribution ID. Again, to find the IDs associated with the Library, Message, and Distribution IDs you can go to you Qualtrics account and find them under the Account Settings tab. As a with the create_distribution method, if you want to send the distribution immediately, you can pass in gmtime() as the argument to the send_date parameter. However, in most circumstances you will need to use the set_send_date method to create a send_date delay.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.Survey import Distributions

#Create an instance
d = Distributions()

#Call the method
send_date = d.set_send_date(weeks=0, days=2, hours=0, minutes=0, seconds=0)
d.create_reminder(subject="Test Survey", reply_email="fake@fake.com", from_email"fake@fake.com", from_name="Survey Joe", library="GR_ThisIsaFakeID!!", message="MS_ThisIsaFakeID!", distribution="EMD_ThisIsaFakeID!!", send_date=send_date)

This will return a string containing the Reminder ID associated with the reminder distribution that you just setup.

"EMD_ThisIsaRmdrID!!"

Create a Thank You¶

Distributions.create_thank_you(subject, reply_email, from_email, from_name, library, message, distribution, send_date)¶

This method gives users the ability to create a thank you for a given distribution. In order to create thank you distributions you must have already created a distribution for a given mailing list and survey. Once created, you will pass the Distribution ID corresponding to the correct distribution to the distribution parameter and the reminder will be set to that specific distribution. Unlike the QualtricsAPI.Survey.Distribution.create_distribution() method, this method does not require you to specify the mailing list or survey because it will use the parameters defined when the associated distribution was set up.

Parameters

subject (str) – The subject for the reminder email.
reply_email (str) – The reply email address.
from_email (str) – The email address that the reminder is sent from.
from_name (str) – The name that shows up on the reminder.
library (str) – The (Global or User) Library ID which the messages are located within.
message (str) – The Message ID corresponding with the message that is to be sent.
distribution (str) – The Distribution ID corresponding with the distribution that the reminder is to be attached to.
send_date (str) – The date that the reminder is supposed to be sent on. Pass gmtime() for immediate distribution or use the set_send_date() method to format properly.

Returns

The “Thank You” Distribution ID. (str)

Example Implementation¶

Here is an example on how to implement the create_thank_you() method. As with the create distribution method, it is important to mention that you can only create an email thank you distribution using this method. Here we pass in arguments to all of the necessary parameters and we are returned a Distribution ID. Again, to find the IDs associated with the Library, Message, and Distribution IDs you can go to you Qualtrics account and find them under the Account Settings tab. As a with the create_reminder method, if you want to send the distribution immediately, you can pass in gmtime() as the argument to the send_date parameter. However, in most circumstances you will need to use the set_send_date method to create a send_date delay.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.Survey import Distributions

#Create an instance
d = Distributions()

#Call the method
send_date = d.set_send_date(weeks=0, days=2, hours=0, minutes=0, seconds=0)
d.create_thank_you(subject="Test Survey", reply_email="fake@fake.com", from_email"fake@fake.com", from_name="Survey Joe", library="GR_ThisIsaFakeID!!", message="MS_ThisIsaFakeID!", distribution="EMD_ThisIsaFakeID!!" send_date=send_date)

This will return a string containing the Thank You Distribution ID associated with the Thank You distribution that you just setup.

"EMD_ThisIsaTyouID!!"

List Distributions¶

Distributions.list_distributions(survey)¶

This method will list all of the distributions corresponding with a given survey. Given that distributions are specific to individual surveys, we must pass the SurveyID as an arguement into the survey parameter for this method to work appropriately. This method will return a Pandas DataFrame filled with a list of the distributions associated with the specific SurveyID passed to the survey parameter.

Parameters: survey (str) – The Survey ID corresponding with the Survey that the distribution is to be sent to.
Returns: A Pandas DataFrame

Example Implementation¶

Here is an example on how to implement the list_distributions() method. This method lists all of the distributions associated with a given survey. In this list, there will be all different types of distributions (invite, reminder, thank you, etc.) returned from the method call.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.Survey import Distributions

#Create an instance
d = Distributions()

#Call the method
df = d.list_distributions(survey="SV_ThisIsaSurvID!!")
print(df.columns)

This will return a Pandas DataFrame containing the list of distributions associated with a given survey. Below is a list of the columns available within the DataFrame when returned.

Index(['id', 'parentDistributionId', 'ownerId', 'organizationId', 'requestStatus', 'requestType',
 'sendDate', 'createdDate', 'modifiedDate', 'headers', 'fromEmail', 'replyToEmail', 'fromName',
 'subject', 'recipients', 'mailingListId', 'contactId', 'sampleId', 'message', 'messageId',
 'messageText', 'surveyLink', 'surveyId', 'expirationDate', 'linkType', 'stats', 'sent', 'failed',
 'started', 'bounced', 'opened', 'skipped', 'finished', 'complaints', 'blocked'],
 dtype='object')

Get a Distribution¶

Distributions.get_distribution(survey, distribution)¶

This method gives users the ability to get a specific distribution corresponding with a given survey. Given that distributions are specific to individual surveys, we must pass the SurveyID as an arguement into the survey parameter for this method to work appropriately. This method will return a Pandas DataFrame consisting of multiple variables associated with the specified distirbution.

Parameters

survey (str) – The Survey ID corresponding with the Survey that the distribution is to be sent to.
distribution (str) – A specific Distribution ID associated with the given survey.

Returns

A Pandas DataFrame

Example Implementation¶

Here is an example on how to implement the get_distribution() method. This method will get all of the relevant information regarding a given distribution.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.Survey import Distributions

#Create an instance
d = Distributions()

#Call the method
df = d.get_distribution(survey="SV_ThisIsaSurvID!!", distribution="EMD_ThisIsaDistID!!")
print(df.index)

This will return a Pandas DataFrame containing the relevant information for a distribution associated with a given survey. The DataFrame returned is a single column wide with whose index contains the distributions information.

Index(['id', 'parentDistributionId', 'ownerId', 'organizationId',
   'requestStatus', 'requestType', 'sendDate', 'createdDate',
   'modifiedDate', 'headers', 'fromEmail', 'replyToEmail', 'fromName',
   'subject', 'recipients', 'mailingListId', 'contactId', 'sampleId',
   'message', 'messageId', 'messageText', 'surveyLink', 'surveyId',
   'expirationDate', 'linkType', 'stats', 'sent', 'failed', 'started',
   'bounced', 'opened', 'skipped', 'finished', 'complaints', 'blocked',
   'mailing_list_library_id', 'message_library_id'],
  dtype='object')