Retrieve All Lists a Subscriber is On

By retrieving all of the lists a subscriber is on, you can understand which email sends a subscriber receives and whether that subscriber is removed from these lists. You can use this in your Subscription Center to show to which lists an individual subscriber is subscribed.

This call also returns any groups associated with the subscriber’s email address. Perform a follow-up call using the specific ID to determine if that ID refers to a list or group.

Use the sample code below as an example to construct your own API calls. The describe call can be used to retrieve the retrievable properties for the ListSubscriber object.

Sample .NET Code

1// Filter by SubscriberKey (default value is email address)
2SimpleFilterPart sfp  = new SimpleFilterPart();
3sfp.Property = "SubscriberKey";
4sfp.SimpleOperator = SimpleOperators.equals;
5sfp.Value = new string[] { "users@example.com" };
6// Create the RetrieveRequest ListSubscriber objects
7RetrieveRequest rr = new RetrieveRequest();
8rr.ObjectType = "ListSubscriber";
9rr.Properties = new string[] { "ListID", "SubscriberKey", "Status" };
10rr.Filter = sfp;
11// Execute the Retrieve call
12APIObject[] results;
13string requestID;
14//Change integrationFramework to the name of your own development environment
15string status = integrationFramework.Retrieve(rr, out requestID, out results);
16// Iterate over the results
17Console.WriteLine("List Subscriber Details:\tList ID\tSubscriberKey\tStatus");
18for (int i = 0; i < results.Length; i++)
19{
20       ListSubscriber ls = (ListSubscriber)results[i];
21       Console.WriteLine("List Subscriber Details:\t{0}\t{1}\t{2}", ls.ListID, ls.SubscriberKey, ls.Status);
22}

Output

1List Subscriber Details:      List ID    SubscriberKey       Status
2List Subscriber Details:      503        users@example.com   Unsubscribed
3List Subscriber Details:      566        users@example.com   Unsubscribed

Sample Java Code (Axis 1.4)

This example uses the subscriber key to return all of the requested lists.

1/**
2     * Return List of Lists for a given SubscriberKey
3     */
4    public void testGetListsForSubscriber() {
5        try {
6            Soap stub = init();
7            String OBJECT_LIST_SUBSCRIBERS = "ListSubscriber";
8            java.util.List list = new ArrayList();
9            list.add("SubscriberKey");
10            list.add("ListID");
11            list.add("Status");
12            String SubscriberKey = "acruz@example.com";
13            RetrieveRequest retrieveRequest = new RetrieveRequest();
14
15            retrieveRequest.setObjectType(OBJECT_LIST_SUBSCRIBERS);
16            String[] stringArray = (String[]) list.toArray(new String[list.size()]);
17            retrieveRequest.setProperties(stringArray);
18            SimpleFilterPart filter = new SimpleFilterPart();
19            filter.setProperty("SubscriberKey");
20            filter.setSimpleOperator(SimpleOperators.equals);
21            java.util.List filterValues = new ArrayList();
22            filterValues.add(SubscriberKey);
23            String[] filerValuesArray = (String[])filterValues.toArray(new String[filterValues.size()]);
24            filter.setValue(filerValuesArray);
25            retrieveRequest.setFilter(filter);
26            RetrieveRequestMsg retrieveRequestMsg = new RetrieveRequestMsg();
27            retrieveRequestMsg.setRetrieveRequest(retrieveRequest);
28            RetrieveResponseMsg retrieveResponseMsg = stub.retrieve(retrieveRequestMsg);
29            System.out.println("[overall status message] " + retrieveResponseMsg.getOverallStatus());
30            APIObject[] apiObjectList = retrieveResponseMsg.getResults();
31            for (APIObject dumpStepThrough : apiObjectList) {
32                ListSubscriber listSubscriber = (ListSubscriber) dumpStepThrough;
33                System.out.print("  [List ID ::: ] " + listSubscriber.getListID());
34                System.out.print("  [Subscriber Key ::: ] " + listSubscriber.getSubscriberKey());
35                System.out.println("  [Subscriber Status ::: ] " + listSubscriber.getStatus());
36            }
37        } catch (Exception e) {
38            e.printStackTrace();
39        }
40    }

Sample SOAP Envelope

1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2   <soapenv:Header>
3      <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4         <wsse:UsernameToken wsu:Id="UsernameToken-24440876" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5            <wsse:Username>XXXXX</wsse:Username>
6            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
7         </wsse:UsernameToken>
8      </wsse:Security>
9   </soapenv:Header>
10   <soapenv:Body>
11      <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <RetrieveRequest>
13            <ObjectType>ListSubscriber</ObjectType>
14            <Properties>SubscriberKey</Properties>
15            <Properties>ListID</Properties>
16            <Properties>Status</Properties>
17            <Filter xsi:type="ns1:SimpleFilterPart" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI">
18               <Property>SubscriberKey</Property>
19               <SimpleOperator>equals</SimpleOperator>
20               <Value>users@example.com</Value>
21            </Filter>
22         </RetrieveRequest>
23      </RetrieveRequestMsg>
24   </soapenv:Body>
25</soapenv:Envelope>

Retrieve All Lists a Subscriber is On

Sample .NET Code

Output

Sample Java Code (Axis 1.4)

Sample SOAP Envelope

See Also