Managing Mailing Lists for XM Directory

This guide provides information about using the XM Directory APIs for managing mailing lists. A mailing list is required to send survey reminders, and thank you messages.

All of the following APIs require the XM Directory directory ID (also known as a pool ID) and an account authorized for XM Directory. The directory's ID is available in the XM Directory user interface under Account Settings and Qualtrics IDs. See Finding Your Qualtrics IDs.

XM Directory and XM Directory Lite Only

These APIs are only available to XM Directory users.

This guide contains information on the following APIs:

• Get Mailing List
• List Mailing Lists
• Create Mailing List
• Update Mailing List
• Delete Mailing List

Get Mailing List

The Get Mailing List API returns information about your XM Directory mailing lists. The information includes the following:

• The number of contacts on the mailing list
• When the mailing list was created
• The ID of the Owner of the list
• When the mailing list was last modified
• The mailing list ID
• The name of the mailing list

The example below shows how to use the API:

Code and Qualtrics Support

Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

# Get Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_12345678"
mailingListId = "CG_12345678"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}".format(dataCenter, directoryId, mailingListId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following shows an example response object from the Get Mailing List endpoint.

{
  "result": {
    "mailingListId": "CG_012345678901234",
    "name": "example",
    "ownerId": "UR_012345678",
    "lastModifiedDate": 1489532998,
    "creationDate": 1489532997,
    "contactCount": 1
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "3184796f-93c6-4424-aad1-50b771872d9d"
  }
}

The response object contains a result object that contains the following members:

Member	Type	Description
contactCount	Number	The number of contacts in this mailing list.
creationDate	Number	The date and time the mailing list was created. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
lastModifiedDate	Number	The date and time the mailing list was last modified. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
mailingListId	String	The ID of the mailing list.
name	String	The name of the mailing list.

List Mailing Lists

The List Mailing Lists API returns information about all of an organization's mailing lists. The following example shows how to use this API:

# List Mailing Lists

import requests

# Setting user Parameters

apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_12345678"
pageSize = 100
offset = 0

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists?pageSize={2}&offset={3}".format(dataCenter, directoryId, pageSize, offset)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following shows an example of the response from the List Mailing Lists API:

{
  "result": {
    "elements": [
      {
        "mailingListId": "CG_012345678901234",
        "name": "example1",
        "ownerId": "UR_012345678",
        "lastModifiedDate": 1489532998,
        "creationDate": 1489532997,
        "contactCount": 1
      },
      {
        "mailingListId": "CG_112345678901234",
        "name": "example2",
        "ownerId": "UR_012345678",
        "lastModifiedDate": 1489532998,
        "creationDate": 1489532997,
        "contactCount": 1
      }
    ],
    "nextPage": null
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "3184796f-93c6-4424-aad1-50b771872d9d"
  }
}

Note that the List Mailing Lists API returns the same information for all mailing lists as does Get Mailing List for one mailing list.

Create Mailing List

The Create Mailing List API allows you to create a new mailing list. You must specify the name of the mailing list as shown below. Optionally, you can include a user group ID as the ownerId to put the mailing list in a shared library.

# Create Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_12345678"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists".format(dataCenter, directoryId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = {
  "name": "Test List",
  "ownerId": "yourOwnerId"
   }
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

This will result a response like:

{
  "result": {
    "id": "CG_012345678901234"
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "623c60ba-6df1-4949-8d91-1ba43c53c445"
  }
}

Update Mailing List

The Update Mailing List API allows you to change the name of the specified mailing list. The following example shows a mailing list being assigned a different name. Optionally, you can change the ownership of a mailing list by including an ownerId property in the post data.

# Update Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_12345678"
mailingListId = "CG_2345678"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}".format(dataCenter, directoryId, mailingListId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = {
  "name": "New Name"
  }
response = requests.put(baseUrl, json=data, headers=headers)
print(response.text)

This will result a response like:

{
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "623c60ba-6df1-4949-8d91-1ba43c53c445"
  }
}

Delete Mailing List

Deleting a mailing list permanently deletes it. The following example shows how to delete a mailing list using the Delete Mailing List API:

# Delete Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_12345678"
mailingListId = "CG_6DuOTYoYbwLOzNb"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}".format(dataCenter, directoryId, mailingListId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.delete(baseUrl, headers=headers)
print(response.text)

A successful delete results in a 200 status code. An example response object is shown below:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "c28a0f97-0fd5-4359-844a-ec041ccb8df6"
    }
}