Manage Subscribers On Lists

Why Manage Subscribers on Lists

You can add and remove subscribers from lists as part of importing subscribers. You can also manage subscribers and lists as part of creating Subscription Centers. The SubscriberList object, when acted upon as the child of a Subscriber object, enables the before mentioned use cases.

How To Manage Subscribers on Lists

The information and sample code below presents the necessary information to manage subscribers on lists. Use the examples as models to construct your own API calls.

SubscriberList

The SubscriberList object represents the union between subscribers and lists.

SubscriberList Actions

Create: creates an existing subscriber on a list
Update: updates an existing subscriber on a list (for status purposes primarily)
Delete: deletes an existing subscriber from a list
Upsert: Creates the subscriber on the list if they don’t exist or updates them if they already exist on the list.

Identifiers

When using the SubscriberList object on Create and Update methods, the ID property represents the ID of the list. On the Retrieve method, the ID property represents the ID of the Subscriber (with the List.ID representing the List ID). Retrieve also supports Subscriber.SubscriberKey as an identifer.

Sample Code

Adding an Existing Subscriber to a List

This example assumes the subscriber exists in the account but not on the list.

Sample .NET Code

1public static void UpdateSubscriber_AddToList(SoapClient soapClient,
2            string iEmailAddress,
3            int iListID)
4        {
5            Subscriber sub = new Subscriber();
6            sub.EmailAddress = iEmailAddress;
7            // Define the SubscriberList and set the status to Active
8            SubscriberList subList = new SubscriberList();
9            subList.ID = iListID;
10            subList.IDSpecified = true;
11            subList.Status = SubscriberStatus.Active;
12            subList.StatusSpecified = true;
13            // Action is set on the SubscriberList to 'create' meaning they are added if they don't exist.
14            // If they already exist, it returns an error.
15            subList.Action = "create";
16            //Relate the SubscriberList defined to the Subscriber
17            sub.Lists = new SubscriberList[] { subList };
18            string sStatus = "";
19            string sRequestId = "";
20            UpdateResult[] uResults =
21                soapClient.Update(new UpdateOptions(), new APIObject[] { sub }, out sRequestId, out sStatus);
22            Console.WriteLine("Status: " + sStatus);
23            Console.WriteLine("Request ID: " + sRequestId);
24            foreach (UpdateResult ur in uResults)
25            {
26                Console.WriteLine("StatusCode: " + ur.StatusCode);
27                Console.WriteLine("StatusMessage: " + ur.StatusMessage);
28                Console.WriteLine("ErrorCode: " + ur.ErrorCode);
29            }
30        }

Sample Java (Axis2) Code

1public static void Run(PartnerAPIStub ps, String iEmailAddress, int iListID) {
2              try {
3                     Subscriber sub = Subscriber.Factory.newInstance();
4                     sub.setEmailAddress(iEmailAddress);
5                     SubscriberList subList = SubscriberList.Factory.newInstance();
6                     subList.setID(iListID);
7                     subList.setStatus(SubscriberStatus.ACTIVE);
8
9            // Action is set on the SubscriberList to 'create' meaning they are added if they don't exist.
10            // If they already exist, it returns an error.
11                     subList.setAction("create");
12                     sub.setListsArray(new SubscriberList[] { subList });
13
14                     UpdateRequestDocument updateRequestDocument = UpdateRequestDocument.Factory
15                                  .newInstance();
16                     UpdateRequestDocument.UpdateRequest UpdateRequest = UpdateRequestDocument.UpdateRequest.Factory
17                                  .newInstance();
18                     UpdateRequest.setObjectsArray(new APIObject[] { sub });
19                     UpdateOptions updateOptions = UpdateOptions.Factory.newInstance();
20                     UpdateRequest.setOptions(updateOptions);
21                     updateRequestDocument.setUpdateRequest(UpdateRequest);
22                     UpdateResponseDocument responseDoc = ps
23                                  .update(updateRequestDocument);
24                     UpdateResponse uResults = responseDoc.getUpdateResponse();
25                     System.out.println("Status: " + uResults.getOverallStatus());
26                     System.out.println("Request ID: " + uResults.getRequestID());
27                     for (UpdateResult ur : uResults.getResultsArray())
28                     {
29                           System.out.println("StatusCode: " + ur.getStatusCode());
30                           System.out.println("StatusMessage: " + ur.getStatusMessage());
31                           System.out.println("ErrorCode: " + ur.getErrorCode());
32                     }
33              } catch (Exception e) {
34                     e.printStackTrace();
35              }
36       }

Sample SOAP Envelope

1<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2   <Header>
3      <fueloauth>YOUR_ACCESS_TOKEN</fueloauth>
4   </Header>
5   <Body>
6      <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
7         <Objects xsi:type="Subscriber">
8            <PartnerKey xsi:nil="true"/>
9            <ObjectID xsi:nil="true"/>
10            <EmailAddress>example@example.com</EmailAddress>
11            <Lists>
12               <PartnerKey xsi:nil="true"/>
13               <ObjectID xsi:nil="true"/>
14               <ID>123456</ID>
15               <Status>Active</Status>
16               <Action>create</Action>
17            </Lists>
18         </Objects>
19      </UpdateRequest>
20   </Body>
21</Envelope>

Unsubscribe an Existing Subscriber from a List

This example assumes the subscriber exists on the list already.

Sample .NET Code

1public static void UpdateSubscriber_UnsubscribeFromList(SoapClient soapClient,
2            string iEmailAddress,
3            int iListID)
4        {
5            Subscriber sub = new Subscriber();
6            sub.EmailAddress = iEmailAddress;
7            // Define the SubscriberList and set the status to Active
8            SubscriberList subList = new SubscriberList();
9            subList.ID = iListID;
10            subList.IDSpecified = true;
11            subList.Status = SubscriberStatus.Unsubscribed;
12            subList.StatusSpecified = true;
13            // Action is set on the SubscriberList to 'update'.
14            // An error is returned if the subscriber does not already exist on list.
15            subList.Action = "update";
16            //Relate the SubscriberList defined to the Subscriber
17            sub.Lists = new SubscriberList[] { subList };
18            string sStatus = "";
19            string sRequestId = "";
20            UpdateResult[] uResults =
21                soapClient.Update(new UpdateOptions(), new APIObject[] { sub }, out sRequestId, out sStatus);
22            Console.WriteLine("Status: " + sStatus);
23            Console.WriteLine("Request ID: " + sRequestId);
24            foreach (UpdateResult ur in uResults)
25            {
26                Console.WriteLine("StatusCode: " + ur.StatusCode);
27                Console.WriteLine("StatusMessage: " + ur.StatusMessage);
28                Console.WriteLine("ErrorCode: " + ur.ErrorCode);
29            }
30        }

Sample Java Code (Axis2)

The code below unsubscribes the subscriber from all lists the subscriber is on. Specify a ListID in the code to remove the subscriber from a specific list.

1public static void Run(PartnerAPIStub ps, String iEmailAddress, int iListID) {
2              try {
3                     Subscriber sub = Subscriber.Factory.newInstance();
4                     sub.setEmailAddress(iEmailAddress);
5                     SubscriberList subList = SubscriberList.Factory.newInstance();
6                     subList.setID(iListID);
7
8                     subList.setStatus(SubscriberStatus.UNSUBSCRIBED);
9
10            // Action is set on the SubscriberList to 'update'.
11                     // An error is returned if the subscriber does not already exist on list.
12                     subList.setAction("update");
13                     sub.setListsArray(new SubscriberList[] { subList });
14
15                     UpdateRequestDocument updateRequestDocument = UpdateRequestDocument.Factory
16                                  .newInstance();
17                     UpdateRequestDocument.UpdateRequest UpdateRequest = UpdateRequestDocument.UpdateRequest.Factory
18                                  .newInstance();
19                     UpdateRequest.setObjectsArray(new APIObject[] { sub });
20                     UpdateOptions updateOptions = UpdateOptions.Factory.newInstance();
21                     UpdateRequest.setOptions(updateOptions);
22                     updateRequestDocument.setUpdateRequest(UpdateRequest);
23                     UpdateResponseDocument responseDoc = ps
24                                  .update(updateRequestDocument);
25                     UpdateResponse uResults = responseDoc.getUpdateResponse();
26                     System.out.println("Status: " + uResults.getOverallStatus());
27                     System.out.println("Request ID: " + uResults.getRequestID());
28                     for (UpdateResult ur : uResults.getResultsArray())
29                     {
30                           System.out.println("StatusCode: " + ur.getStatusCode());
31                           System.out.println("StatusMessage: " + ur.getStatusMessage());
32                           System.out.println("ErrorCode: " + ur.getErrorCode());
33                     }
34              } catch (Exception e) {
35                     e.printStackTrace();
36              }
37       }

Sample SOAP Envelope

1<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2   <Header>
3      <fueloauth>YOUR_ACCESS_TOKEN</fueloauth>
4   </Header>
5   <Body>
6      <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
7         <Objects xsi:type="Subscriber">
8            <PartnerKey xsi:nil="true"/>
9            <ObjectID xsi:nil="true"/>
10            <EmailAddress>example@example.com</EmailAddress>
11            <Lists>
12               <PartnerKey xsi:nil="true"/>
13               <ObjectID xsi:nil="true"/>
14               <ID>123456</ID>
15               <Status>Unsubscribed</Status>
16               <Action>update</Action>
17            </Lists>
18         </Objects>
19      </UpdateRequest>
20   </Body>
21</Envelope>

Manage Subscribers On Lists

Why Manage Subscribers on Lists

How To Manage Subscribers on Lists

SubscriberList

SubscriberList Actions

Identifiers

Sample Code

Adding an Existing Subscriber to a List

Sample .NET Code

Sample Java (Axis2) Code

Sample SOAP Envelope

Unsubscribe an Existing Subscriber from a List

Sample .NET Code

Sample Java Code (Axis2)

Sample SOAP Envelope

See Also