{"_id":"595eb29e2290d30015cd13f7","project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":46,"createdAt":"2015-06-19T16:35:26.435Z","releaseDate":"2015-06-19T16:35:26.435Z","categories":["558444cfafccfd0d00fcb2bc","558444cfafccfd0d00fcb2bd","55ad4ce733616a0d00599d2e","55ad4cef6aadf20d0015b764","55ad4cf36aadf20d0015b765","55ad4cfb24cf160d0013584f","55ad4d0024cf160d00135850","55ad4d0a24cf160d00135851","55ad4d0d24cf160d00135852","55ad4d126aadf20d0015b766","55ad4d1624cf160d00135853","55ad4d1933616a0d00599d2f","55ad4d2233616a0d00599d30","55ad4d2e24cf160d00135854","55d35b6bf77e6d0d00b1b092","55d3649a0168850d0073f14a","55d366d40168850d0073f15a","55d37fcff77e6d0d00b1b13f","55d383e50168850d0073f1e1","55d3ac26c336ec0d007c2251","55d3c51cb2330119009c31db","55d3c59bfe37111900e536f3","55d3c5a7fe37111900e536f4","55d3c5b4fe37111900e536f5","55d3c5d4fe37111900e536f6","55d3c5d6b2330119009c31df","55d3c5d71f478b170077c164","55d3c687b2330119009c31e4","55d3c6a4fe37111900e536f9","55d3c6befe37111900e536fa","55d3c6e8d2c66f0d00497f93","55d49dcfd7c16b2d007de905","55d4ca8f5082980d0009c79b","55d4cab9c95a3d2f0069ad3d","55d4d279c95a3d2f0069ad60","55d4d9355082980d0009c7e1","55d4f6b5988e130d000b3eb1","55d64dc8e60a2f0d00b88ecb","5627ca43fcbbc621004ec07d","56c64a0d8f98b50d0012c37c","56f1b8b13eb62a34003ea041","56f1b9df4476fb2200795e8c","57f6907dca5e5d1700039ae9","591dd06ca266c423002ec4ca","59234825e465c11900922518","5936f82eaa591e0027638d57","59972f54fd7078001992c136"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"category":{"_id":"59234825e465c11900922518","__v":0,"version":"558444ceafccfd0d00fcb2bb","project":"55843604fd8d910d007b9502","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-22T20:20:53.281Z","from_sync":false,"order":1,"slug":"using-the-qualtrics-api","title":"Using the Qualtrics APIs"},"user":"5919f13aff66b00f00f1948c","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-07-06T21:58:54.237Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"This guide provides information about using the Target Audience APIs for managing mailing lists. A mailing list is required to send survey invitations, survey reminders, and thank you messages.\n\nAll of the following APIs require the Target Audience directory ID (also known as a pool ID) and an account authorized for Target Audience. The directory's ID is available in the Target Audience user interface under Account Settings and Qualtrics IDs. See [Finding the Directory ID or Pool ID for Target Audience](doc:finding-qualtrics-ids#finding-the-directory-id-or-pool-id-for-target-aud).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Target Audience\",\n  \"body\": \"These APIs are only available to Target Audience users.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Shared Mailing Lists Unsupported\",\n  \"body\": \"These APIs do not support actions on shared (global) mailing lists. You need to use the V2 APIs to work with global mailing lists.\"\n}\n[/block]\nFor more information about using the code samples in this guide, see [Using the API Code Samples](doc:using-the-api-code-samples).\n\nThis guide contains information on the following APIs:\n\n* [Get Mailing List](doc:managing-lists-for-target-audience#get-mailing-list)\n* [List Mailing Lists](doc:managing-lists-for-target-audience#list-mailing-lists)\n* [Create Mailing List](doc:managing-lists-for-target-audience#create-mailing-list)\n* [Update Mailing List](doc:managing-lists-for-target-audience#update-mailing-list)\n* [Delete Mailing List](doc:managing-lists-for-target-audience#delete-mailing-list)\n[block:api-header]\n{\n  \"title\": \"Get Mailing List\"\n}\n[/block]\nThe Get Mailing List API returns information about your Target Audience mailing lists. The information includes the following:\n\n- The number of contacts on the mailing list\n- When the mailing list was created\n- When the mailing list was last modified\n- The mailing list ID\n- The name of the mailing list\n\nThe example below shows how to use the API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345678\\\"\\nmailingListId = \\\"CG_12345678\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}\\\".format(dataCenter, directoryId, mailingListId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following shows an example response object from the Get Mailing List endpoint.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"620c1e61-4f99-4f29-a3b9-070d3f2f53ef\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"contactCount\\\": 3,\\n        \\\"creationDate\\\": 1498689859000,\\n        \\\"lastModifiedDate\\\": 1498834488000,\\n        \\\"mailingListId\\\": \\\"CG_123456789\\\",\\n        \\\"name\\\": \\\"Summer 2017 Mailing\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe response object contains a result object that contains the following members:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`contactCount`\",\n    \"0-1\": \"Number\",\n    \"0-2\": \"The number of contacts in this mailing list.\",\n    \"1-0\": \"`creationDate`\",\n    \"1-1\": \"Number\",\n    \"1-2\": \"The date and time the mailing list was created. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"2-0\": \"`lastModifiedDate`\",\n    \"2-1\": \"Number\",\n    \"2-2\": \"The date and time the mailing list was last modified. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"3-0\": \"`mailingListId`\",\n    \"3-1\": \"String\",\n    \"3-2\": \"The ID of the mailing list.\",\n    \"4-0\": \"`name`\",\n    \"4-1\": \"String\",\n    \"4-2\": \"The name of the mailing list.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"List Mailing Lists\"\n}\n[/block]\nThe List Mailing Lists API returns information about all of an organization's mailing lists. The following example shows how to use this API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# List Mailing Lists\\n\\nimport requests\\n\\n# Setting user Parameters\\n\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345678\\\"\\npageSize = 100\\noffset = 0\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists?pageSize={2}&offset={3}\\\".format(dataCenter, directoryId, pageSize, offset)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following shows an example of the response from the List Mailing Lists API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"f1deeee6-c853-493c-ab10-965d90df3cab\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"contactCount\\\": 2,\\n                \\\"creationDate\\\": 1499891444000,\\n                \\\"lastModifiedDate\\\": 1499869847000,\\n                \\\"mailingListId\\\": \\\"CG_123456\\\",\\n                \\\"name\\\": \\\"Response Time\\\"\\n            },\\n            {\\n                \\\"contactCount\\\": 5,\\n                \\\"creationDate\\\": 1500056742000,\\n                \\\"lastModifiedDate\\\": 1500035141000,\\n                \\\"mailingListId\\\": \\\"CG_2345678\\\",\\n                \\\"name\\\": \\\"Summer 2017 Mailing\\\"\\n            },\\n            {\\n                \\\"contactCount\\\": 3,\\n                \\\"creationDate\\\": 1498765928000,\\n                \\\"lastModifiedDate\\\": 1498825323000,\\n                \\\"mailingListId\\\": \\\"CG_3456789\\\",\\n                \\\"name\\\": \\\"TA\\\"\\n            },\\n            {\\n                \\\"contactCount\\\": 0,\\n                \\\"creationDate\\\": 1498518083000,\\n                \\\"lastModifiedDate\\\": 1498518083000,\\n                \\\"mailingListId\\\": \\\"CG_4567890\\\",\\n                \\\"name\\\": \\\"TA test 1\\\"\\n            }\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nNote that the List Mailing Lists API returns the same information for all mailing lists as does Get Mailing List for one mailing list.\n[block:api-header]\n{\n  \"title\": \"Create Mailing List\"\n}\n[/block]\nThe Create Mailing List API allows you to create a new mailing list. The only information that can be specified is the mailing list's name as the example below shows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345678\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists\\\".format(dataCenter, directoryId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n\\t\\\"name\\\": \\\"Test List\\\",\\n\\t }\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Update Mailing List\"\n}\n[/block]\nThe 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Update Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345678\\\"\\nmailingListId = \\\"CG_2345678\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}\\\".format(dataCenter, directoryId, mailingListId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n\\t\\\"name\\\": \\\"New Name\\\"\\n\\t}\\nresponse = requests.put(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Delete Mailing List\"\n}\n[/block]\nDeleting a mailing list permanently deletes it. The following example shows how to delete a mailing list using the Delete Mailing List API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Delete Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345678\\\"\\nmailingListId = \\\"CG_6DuOTYoYbwLOzNb\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}\\\".format(dataCenter, directoryId, mailingListId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.delete(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nA successful delete results in a 200 status code. An example response object is shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"c28a0f97-0fd5-4359-844a-ec041ccb8df6\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]","excerpt":"APIs for managing your Target Audience mailing lists","slug":"managing-mailing-lists-for-target-audience","type":"basic","title":"Managing Mailing Lists for Target Audience"}

Managing Mailing Lists for Target Audience

APIs for managing your Target Audience mailing lists

This guide provides information about using the Target Audience APIs for managing mailing lists. A mailing list is required to send survey invitations, survey reminders, and thank you messages. All of the following APIs require the Target Audience directory ID (also known as a pool ID) and an account authorized for Target Audience. The directory's ID is available in the Target Audience user interface under Account Settings and Qualtrics IDs. See [Finding the Directory ID or Pool ID for Target Audience](doc:finding-qualtrics-ids#finding-the-directory-id-or-pool-id-for-target-aud). [block:callout] { "type": "info", "title": "Target Audience", "body": "These APIs are only available to Target Audience users." } [/block] [block:callout] { "type": "warning", "title": "Shared Mailing Lists Unsupported", "body": "These APIs do not support actions on shared (global) mailing lists. You need to use the V2 APIs to work with global mailing lists." } [/block] For more information about using the code samples in this guide, see [Using the API Code Samples](doc:using-the-api-code-samples). This guide contains information on the following APIs: * [Get Mailing List](doc:managing-lists-for-target-audience#get-mailing-list) * [List Mailing Lists](doc:managing-lists-for-target-audience#list-mailing-lists) * [Create Mailing List](doc:managing-lists-for-target-audience#create-mailing-list) * [Update Mailing List](doc:managing-lists-for-target-audience#update-mailing-list) * [Delete Mailing List](doc:managing-lists-for-target-audience#delete-mailing-list) [block:api-header] { "title": "Get Mailing List" } [/block] The Get Mailing List API returns information about your Target Audience mailing lists. The information includes the following: - The number of contacts on the mailing list - When the mailing list was created - 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: [block:code] { "codes": [ { "code": "# Get Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_12345678\"\nmailingListId = \"CG_12345678\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}\".format(dataCenter, directoryId, mailingListId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following shows an example response object from the Get Mailing List endpoint. [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"620c1e61-4f99-4f29-a3b9-070d3f2f53ef\"\n },\n \"result\": {\n \"contactCount\": 3,\n \"creationDate\": 1498689859000,\n \"lastModifiedDate\": 1498834488000,\n \"mailingListId\": \"CG_123456789\",\n \"name\": \"Summer 2017 Mailing\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The response object contains a result object that contains the following members: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`contactCount`", "0-1": "Number", "0-2": "The number of contacts in this mailing list.", "1-0": "`creationDate`", "1-1": "Number", "1-2": "The date and time the mailing list was created. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "2-0": "`lastModifiedDate`", "2-1": "Number", "2-2": "The date and time the mailing list was last modified. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "3-0": "`mailingListId`", "3-1": "String", "3-2": "The ID of the mailing list.", "4-0": "`name`", "4-1": "String", "4-2": "The name of the mailing list." }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "title": "List Mailing Lists" } [/block] The List Mailing Lists API returns information about all of an organization's mailing lists. The following example shows how to use this API: [block:code] { "codes": [ { "code": "# List Mailing Lists\n\nimport requests\n\n# Setting user Parameters\n\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_12345678\"\npageSize = 100\noffset = 0\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists?pageSize={2}&offset={3}\".format(dataCenter, directoryId, pageSize, offset)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following shows an example of the response from the List Mailing Lists API: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"f1deeee6-c853-493c-ab10-965d90df3cab\"\n },\n \"result\": {\n \"elements\": [\n {\n \"contactCount\": 2,\n \"creationDate\": 1499891444000,\n \"lastModifiedDate\": 1499869847000,\n \"mailingListId\": \"CG_123456\",\n \"name\": \"Response Time\"\n },\n {\n \"contactCount\": 5,\n \"creationDate\": 1500056742000,\n \"lastModifiedDate\": 1500035141000,\n \"mailingListId\": \"CG_2345678\",\n \"name\": \"Summer 2017 Mailing\"\n },\n {\n \"contactCount\": 3,\n \"creationDate\": 1498765928000,\n \"lastModifiedDate\": 1498825323000,\n \"mailingListId\": \"CG_3456789\",\n \"name\": \"TA\"\n },\n {\n \"contactCount\": 0,\n \"creationDate\": 1498518083000,\n \"lastModifiedDate\": 1498518083000,\n \"mailingListId\": \"CG_4567890\",\n \"name\": \"TA test 1\"\n }\n ],\n \"nextPage\": null\n }\n}", "language": "json", "name": "Response" } ] } [/block] Note that the List Mailing Lists API returns the same information for all mailing lists as does Get Mailing List for one mailing list. [block:api-header] { "title": "Create Mailing List" } [/block] The Create Mailing List API allows you to create a new mailing list. The only information that can be specified is the mailing list's name as the example below shows: [block:code] { "codes": [ { "code": "# Create Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_12345678\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists\".format(dataCenter, directoryId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n\t\"name\": \"Test List\",\n\t }\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] [block:api-header] { "title": "Update Mailing List" } [/block] 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: [block:code] { "codes": [ { "code": "# Update Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_12345678\"\nmailingListId = \"CG_2345678\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}\".format(dataCenter, directoryId, mailingListId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n\t\"name\": \"New Name\"\n\t}\nresponse = requests.put(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] [block:api-header] { "title": "Delete Mailing List" } [/block] Deleting a mailing list permanently deletes it. The following example shows how to delete a mailing list using the Delete Mailing List API: [block:code] { "codes": [ { "code": "# Delete Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_12345678\"\nmailingListId = \"CG_6DuOTYoYbwLOzNb\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}\".format(dataCenter, directoryId, mailingListId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] A successful delete results in a 200 status code. An example response object is shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"c28a0f97-0fd5-4359-844a-ec041ccb8df6\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block]