Follow

Report List Opt Outs

The Report List Opt Outs command allows you to get the Opt Out Data for all Subscribers who have opted out of a specific List or who have Globally Opted Out of all Lists.

GET /lists/[listId]/optouts?querystring

https://[siteurl]/rest/lists/[listId]/optouts?querystring

The following queries are supported:

start=[yyyy-mm-dd]
end=[yyyy-mm-dd]

Request Body Parameters

The Report List Opt Outs command requires the URI call with the List ID, Start and End Date parameters. No additional fields are required in the JSON.

The query strings 'start' and 'end' are case sensitive and must be defined as in the example above using the date format yyyy-mm-dd.  If the query string is incorrect or missing, it is ignored and the command returns all Opt Outs in the List.

The query assumes the time of midnight of the date defined.  For instance, to get only Subscribers with an event on June 15th, 2016, set the dates to the following:

start=2016-06-15
end=2016-06-16

To include events that occurred on the 16th also, set the end date to one day greater than 16, June 17th. 

Request Body Example

Using Report List Opt Outs:

curl --request GET \ 
--url 'https://mail.mydomain.com/rest/lists/10/optouts?start=2016-06-15&end=2016-06-16' \
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \
--header 'accept: application/vnd.whatcounts-v1+json' \
--header 'content-type: application/json' \
--include

Response Body

The response returns Opt Out data in JSON format for each Subscriber that matches any of the query fields.  The data includes the following fields:

  • email: Subcriber Email 
  • firstName: Subscriber First Name, if stored
  • customerKey: Only included if the Account is set to use Customer Key
  • listId: Identifier for the List defined in the command
  • realmId: Identifier for the Account
  • optoutDate: Date the Opt Out occurred
  • source: Identifier Code to determine how Opt Out occurred
  • sourceType: User friendly source code

If more than 500 results are found, the first 500 are displayed, and you must use the "skip" value to view the next 500.  

For example, to find the three groups of 500 Subscribers in a List with 1455 matching Subscribers, the URIs would be formatted as:

  1. https://[siteurl]/rest/lists/[listId]/optouts?start=2016-06-01&end=2016-06-30&skip=0
  2. https://[siteurl]/rest/lists/[listId]/optouts?start=2016-06-01&end=2016-06-30&skip=500
  3. https://[siteurl]/rest/lists/[listId]/optouts?start=2016-06-01&end=2016-06-30&skip=1000

For more information about "skip", see Pagination.

List Opt Outs

Based on the example above, and two matching Subscribers in the Opt Out report, the response returns:

HTTP/1.1 200 OK
Server: serverName
Content-Type: application/json
Link: <https://mail.mydomain.com/rest/lists/10/optouts?start=2016-06-01&end=2016-06-30>;
Date: Fri, 17 Jun 2016 12:54:44 GMT
{
"email": "jon.doe@mydomain.com"
"firstName": "Jon"
"listId": 10
"realmId": 1561
"optoutDate": "Jun 22, 2016 11:11:17 AM"
"source": 10
"sourceType": "EMAIL_HARDBOUNCE"
"skip": 1
"max": 0
}

{
"email": "jonDoe@mydomain.com"
"firstName": "Jon"
"listId": 10
"realmId": 1561
"optoutDate": "Jun 24, 2016 09:19:17 AM"
"source": 31
"sourceType": "WEB_CONFIRMATION"
"skip": 0
"max": 0
}

Global Opt Outs

Global Opt Outs are recorded using List ID 0.  Replacing the listId in the command with 0, and two matching Subscribers in the List, the response returns:

HTTP/1.1 200 OK
Server: serverName
Content-Type: application/json
Link: <https://mail.mydomain.com/rest/lists/0/optouts?start=2016-06-01&end=2016-06-30>;
Date: Fri, 17 Jun 2016 12:54:44 GMT
{
"email": "notReal@invaliddomain.com"
"firstName": "Jon"
"listId": 0
"realmId": 1561
"optoutDate": "Jun 22, 2016 11:11:17 AM"
"source": 10
"sourceType": "EMAIL_HARDBOUNCE"
"skip": 1
"max": 0
}

{
"email": "jane@mydomain.com"
"firstName": "Jane"
"listId": 0
"realmId": 1561
"optoutDate": "Jun 24, 2016 09:19:17 AM"
"source": 31
"sourceType": "WEB_CONFIRMATION"
"skip": 0
"max": 0
}

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx).  Descriptions of each can be found in Response Codes

For example, if the Authorization is incorrect, the error would appear as:

{
"error": "Unauthorized"
"status": "Unauthorized"
"statusCode": 401
}

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk