Mailing List Contacts

Number of APIs: 8

The Mailing List Contacts endpoints allow you to manage contacts you have in your mailing lists. You can do CRUD operations on the contacts in the mailing lists, as well as query the mailing list for bounced or opted out contacts . Additionally, you can retrieve a contact's history of distributions and survey completions.

Workflows

Create Contact in Mailing List
List Contacts in Mailing List
Get Contact in Mailing List
Update Contact in Mailing List
Get Contact History for Mailing List Contact
Delete Contact in Mailing List
Get Bounced Contacts In Mailing List
Get Opted Out Contacts In Mailing List

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.

XM Directory Only

These APIs are only available to XM Directory users.

Create Contact in Mailing List

This API allows you to create a new contact in the specified mailing list. This API is the only way to add a contact to a mailing list. There is not a way to reuse a contact from the organization's contacts directory in a mailing list.

When you use this API, you create a contact in both the mailing list and the organization's contacts directory. This means that if the contact already exists in the organization's contacts directory, a duplicate will be created. You can use XM Directory's de-duplication tool to remove these duplicate contacts. See Manage Directory Duplicates for more information.

curl --location --request POST 'https://iad1.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0e94ac90-ccc7-49a1-9822-ea6bb88db313' \
--data-raw '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "JohnDoe@email.com",
    "phone": "6153214454",
    "extRef": "myExtRefID123",
    "embeddedData": {},
    "language": "en/US",
    "unsubscribed": failse
}'

The following response object shows a typical result from this API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "641ca8da-fb07-4319-907b-ab45af1a93c2"
    },
    "result": {
        "id": "CID_123456"
    }
}

List Contacts in Mailing List

The List Contacts API returns all of the contacts in the specified mailing list. The contact information returned by the API is limited to basic information, including the contactId which you can use to get more detailed information with the Get Contact in Mailing List API. You can list the contacts with a call like:

curl --location --request GET 'https://iad1.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/contacts' \
--header 'Authorization: Bearer 8b0f6c98-de76-4ad0-b8fc-7a5258399d3d'

The following shows an example response returned from this API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "7de14d38-f5ed-49d0-9ff0-773e12b896b8"
    },
    "result": {
        "elements": [
            {
                "contactId": "CID_123456",
                "email": "js@example.com",
                "extRef": "1234567",
                "firstName": "James",
                "language": "en",
                "lastName": "Smith",
                "phone": "8005552000",
                "unsubscribed": false
            },
            {
                "contactId": "CID_3456789",
                "email": "person@example.com",
                "extRef": "12345678",
                "firstName": "John",
                "language": "en",
                "lastName": "Smith",
                "phone": "8005551212",
                "unsubscribed": true
            }
        ],
        "nextPage": null
    }
}

Get Contact in Mailing List

The Get Contact in Mailing List API returns detailed information about a specific contact in the mailing list used in the path. The information is almost identical to the information returned by the Get Contact API, with two differences:

This API does not return mailing list membership information.
This API returns an ID that uniquely identifies the contact in this mailing list (contactLookupId).

The following sample shows how to use the Get Contact in Mailing List API:

curl --location --request GET 'https://st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/contacts/CID_cAshhfxh7uJfXG5' \
--header 'Authorization: Bearer 0e94ac90-ccc7-49a1-9822-ea6bb88db313'

The following shows an example of the response that this endpoint returns:

{
    "result": {
        "contactId": "CID_cAshhfxh7uJfXG5",
        "creationDate": 1597326549000,
        "lastModified": 1597326549000,
        "directoryUnsubscribed": false,
        "directoryUnsubscribeDate": null,
        "firstName": "Johnny",
        "lastName": "Boy",
        "email": "JohnnyBoy@gmail.com",
        "emailDomain": "gmail.com",
        "phone": null,
        "language": null,
        "writeBlanks": false,
        "extRef": "Example",
        "embeddedData": {
            "ExampleField1": "example_field_val_1",
            "ExampleField2": "example_field_val_2"
        },
        "stats": {
            "AvgTimeToRespond": null,
            "DataIntegrity": "100",
            "EmailCount": "0",
            "InviteCount": "0",
            "LastEmailDate": null,
            "LastInviteDate": null,
            "LastResponseDate": null,
            "MonthEmailCount": "0",
            "MonthInviteCount": "0",
            "Points": "0",
            "ResponseCount": "0",
            "ResponseRate": "0.0"
        },
        "contactLookupId": "CGC_cwrDD2BmKdM1oUJ",
        "mailingListUnsubscribed": false,
        "mailingListUnsubscribeDate": null
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "a0a05648-b40e-427e-acd8-0a8646560214"
    }
}

The result contains the following data:

Member	Type	Description
contactId	String	The contact ID.
contactLookupId	String	The contact lookup ID
creationDate	Number	Date and time this contact's record was created. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
directoryUnsubscribeDate	Number	Date and time the user opted out of the directory. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
directoryUnsubscribed	Boolean	Indicates whether the user opted out of the directory.
email	String	The contact's email address.
emailDomain	String	The contact's email domain.
embeddedData	Object	The embedded data object contains extra metadata that you want to associate with contacts. This user-defined data could include such data as birthplace, gender, employment status, etc. See Update Contact below for an example of setting the embedded data object.
extRef	String	External reference. You can place any string data here that you need to attach to a contact.
firstName	String	The contact's first name or given name.
language	String	The contact's language if set.
lastModified	Number	Date and time this record was last modified. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
lastName	String	The contact's last name or surname.
mailingListUnsubscribeDate	Number	Date and time the user opted out of this mailing list. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
mailingListUnsubscribed	Boolean	Whether the user has opted out of receiving email through this mailing list.
phone	String	The contact's phone number.
stats	Object	The stats object for the contact. See the next section for information about this object.
writeBlanks	Boolean	Whether to write blanks.

The stats object

The stats object contains information about interactions with this contact.

Mailing list contact stats equivalent to directory contact's stats

The stats object documented here does not contain statistical information specific to the specified mailing list. Instead, it contains the same information as the stats object returned from the Get Contact API.

The information contained in the stats object appears in the following table:

Member	Type	Description
AvgTimeToRespond	String	Average time, in hours, that passed before the contact started taking a survey after the invitation was sent.
DataIntegrity	String	The contact's data integrity score. 100 is the highest score.
EmailCount	String	Number of emails sent to this contact since the contact was created.
InviteCount	String	Number of invitations to take surveys that have been sent to this contact since the contact was created.
LastEmailDate	String	Last date and time an email was sent to this contact. Emails include invitations to take surveys, thank you notes for taking a survey, and reminders to take a survey. The date and time is in UTC formatted as yyyy-MM-dd HH:mm:ss.
LastInviteDate	String	Last date and time an invitation to take a survey has been sent to this contact. The date and time is in UTC formatted as yyyy-MM-dd HH:mm:ss.
LastResponseDate	String	Last date and time this contact completed a survey. The date and time is in UTC formatted as yyyy-MM-dd HH:mm:ss.
MonthEmailCount	String	The number of emails sent to this contact in the month that the API was called.
MonthInviteCount	String	The number of invitations to take surveys sent to this contact in the month that the API was called.
Points	String	The number of incentive points this contact has earned.
ResponseCount	String	Number of surveys in total that this contact completed since the contact was created.
ResponseRate	String	The ratio of surveys this contact completed compared to the total number of surveys sent. The number ranges from 0.0 to 1.0.

Update Contact in Mailing List

The Update Contact in Mailing List API allows you to change data associated with a contact.

The functionality provided by this API is also provided by the Update Contact API. The Update Contact API, however, does not require a mailing list ID.

curl --location --request PUT 'https://st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/contacts/CID_cAshhfxh7uJfXG5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 0e94ac90-ccc7-49a1-9822-ea6bb88db313' \
--data-raw '{
    "firstName": "John"
}'

The following response shows a successful result from this API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "2b88e3d5-4c8f-4896-ad8a-f4a2f08b41d3"
    }
}

Get Contact History for Mailing List Contact

The Get Contact History API returns information about either the email sent to a contact or the survey responses supplied by a contact. The type query parameter specifies the type of history that should be returned. The following code example demonstrates how to return a contact's survey response history (type is set to response).

curl --location --request GET 'https://st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/contacts/CID_cAshhfxh7uJfXG5/history?type=email' \
--header 'Authorization: Bearer 0e94ac90-ccc7-49a1-9822-ea6bb88db313'

The following response object shows the contact's email history (with type set to email):

{
    "result": {
        "elements": [
            {
                "distributionId": "EMD_8IEZvzmzXR67MJX",
                "date": "2020-12-22T15:56:50Z",
                "type": "Invite",
                "result": "Error",
                "surveyId": "SV_eajskCRbMSRKkRf",
                "read": false,
                "lookupId": "CGC_cwrDD2BmKdM1oUJ"
            },
            {
                "distributionId": "EMD_uFouQAelI5YbqiS",
                "date": "2020-12-22T16:02:17Z",
                "type": "Invite",
                "result": "Error",
                "surveyId": "SV_bwrylOA5nNnI9M1",
                "read": false,
                "lookupId": "CGC_cwrDD2BmKdM1oUJ"
            }
        ],
        "nextPage": null
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "829cabb5-6083-4f95-8ac7-19eecfb96ff8"
    }
}

Delete Contact in Mailing List

The Delete Contact in Mailing List API removes the specified contact from the specified mailing list. It does not remove the contact from the organization's contact directory even if the contact appears on no other mailing list.

curl --location --request DELETE 'https://st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/contacts/CID_cAshhfxh7uJfXG5'

The following response object shows the result of a successful delete:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "ed27363d-9043-4c03-b965-aba4d331cbd8"
    }
}

If you attempt to delete a contact which has already been deleted it will return a 404 to indicate that this contact does not exist.

{
  "meta": {
    "httpStatus": "404 - Not Found",
    "error": {
      "errorMessage": "Contact does not exist"
    }
  }
}

Bounced Contacts in Mailing List

When a contact is unreachable, that contact will become a bounced contact. You can find out what contacts on your mailing list are bounced by making a call like this:

curl --location --request GET 'https://st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/bouncedContacts' \
--header 'Authorization: Bearer 39f0ecd0-07d8-472e-ae4c-67cfa87a4a0f'

You will receive a response listing all the contacts who opted out of contact with the mailing list:

{
    "result": {
        "elements": [
            {
                "contactId": "CID_cCPLoRoDAOGuQWF",
                "firstName": "John",
                "lastName": "Boy",
                "email": "jboy@example.com",
                "phone": null,
                "extRef": "Example",
                "language": null,
                "directoryUnsubscribed": false,
                "directoryUnsubscribeDate": null,
                "mailingListUnsubscribed": false,
                "mailingListUnsubscribeDate": null
            }
        ],
        "nextPage": null
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "7b026c21-88e6-4af0-ac38-0b2f478b758f"
    }
}

Opted Out Contacts In Mailing List

When a contact decides against further communication, either from the mailing list or the directory entirely, that contact will then show up on the opted out contact list. To retrieve the list of opted out contacts for your mailing list, you can make a call like this:

curl --location --request GET 'https://st3.qualtrics.com/API/v3/directories/POOL_eOHAGsIto4GlLh3/mailinglists/CG_0P8zwqVDmBzhOFT/optedOutContacts' \
--header 'Authorization: Bearer 39f0ecd0-07d8-472e-ae4c-67cfa87a4a0f'

You will receive a response listing all the contacts who opted out of contact with the mailing list:

{
    "result": {
        "elements": [
            {
                "contactId": "CID_3CdiAKmbKFvA29f",
                "firstName": "John",
                "lastName": "Doe",
                "email": "jdoe@example.com",
                "phone": null,
                "extRef": null,
                "language": "EN",
                "directoryUnsubscribed": true,
                "directoryUnsubscribeDate": "2021-04-27T21:40:42.000Z",
                "mailingListUnsubscribed": true,
                "mailingListUnsubscribeDate": null
            }
        ],
        "nextPage": null
    },
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "4bd3e857-6f9f-4621-91df-de8c9c39c3ab"
    }
}

© 2020 Qualtrics, LLC

Contact Support: Name: Support

directories-{directoryId}-mailinglists-{mailingListId}-contacts-{contactId}-history - Get Contact History In Mailing List GET {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/contacts/:contactId/history?type=response&skipToken=<string>&pageSize=100
directories-{directoryId}-mailinglists-{mailingListId}-contacts-{contactId} - Update Contact In Mailing List PUT {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/contacts/:contactId
directories-{directoryId}-mailinglists-{mailingListId}-contacts-{contactId} - Delete Contact In Mailing List DELETE {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/contacts/:contactId
directories-{directoryId}-mailinglists-{mailingListId}-contacts - Create Contact In Mailing List POST {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/contacts
directories-{directoryId}-mailinglists-{mailingListId}-contacts - List Contacts In Mailing List GET {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/contacts?pageSize=50&skipToken=<string>&includeEmbedded=<boolean>
directories-{directoryId}-mailinglists-{mailingListId}-bouncedContacts - List Bounced Contacts In Mailing List GET {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/bouncedContacts?since=<dateTime>&pageSize=50&skipToken=<string>
directories-{directoryId}-mailinglists-{mailingListId}-optedOutContacts - List Opted-Out Contacts In Mailing List GET {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/optedOutContacts?pageSize=50&skipToken=<string>&since=<dateTime>
directories-{directoryId}-mailinglists-{mailingListId}-contacts-{contactId} - Get Contact In Mailing List GET {{baseUrl}}/directories/:directoryId/mailinglists/:mailingListId/contacts/:contactId