Updating subscriber attributes via the SOAP API allows you to better maintain your subscriber information while maintaining a tight integration with your system or development environment.
Use these code examples to construct your own API update calls. You must include the unique identifier (either an email address or subscriber key) and the name-value pairs for the attributes to be updated. You must create a new record if you want to create a new value for the subscriber’s primary key.
1//Create Subscriber object [Subscribers > My Subscribers > All Subscribers]
2 Subscriber sub = new Subscriber();
3 sub.SubscriberKey = "12345";//required //may not be active in all accounts //use EmailAddress instead
4 sub.EmailAddress = "tester@example.com";//required
5 sub.EmailTypePreference = EmailType.Text;//EmailType.HTML is the default this only needs to be set to override to Text
6 sub.EmailTypePreferenceSpecified = true;
7 //Create an Array of Lists
8 sub.Lists = new SubscriberList[2];//If a list is not specified the Subscriber is added to the "All Subscribers" List
9 sub.Lists[0] = new SubscriberList();
10 sub.Lists[0].ID = 123;//Available in the UI via List Properties
11 sub.Lists[0].IDSpecified = true;
12 sub.Lists[1] = new SubscriberList();
13 sub.Lists[1].ID = 1234;//Available in the UI via List Properties
14 sub.Lists[1].IDSpecified = true;
15 //Subscriber Attributes differ per account. Some may be required to create a Subscriber
16 sub.Attributes = new etAPI.Attribute[2];
17 sub.Attributes[0] = new etAPI.Attribute();
18 sub.Attributes[0].Name = "First Name";
19 sub.Attributes[0].Value = "Updated";
20 sub.Attributes[1] = new etAPI.Attribute();
21 sub.Attributes[1].Name = "Last Name";
22 sub.Attributes[1].Value = "ViaAPI";
23 try
24 {
25 string uRequestID = String.Empty;
26 string uStatus = String.Empty;
27 //Call the Update method on the Subscriber object
28 UpdateResult[] uResults = client.Update(new UpdateOptions(), new APIObject[] { sub }, out uRequestID, out uStatus);
29 //Display Results
30 lblMessage.Text += "Overall Status: " + uStatus;
31 lblMessage.Text += "<br/>";
32 lblMessage.Text += "Number of Results: " + uResults.Length;
33 lblMessage.Text += "<br/>";
34 //Loop through each object returned and display the StatusMessage
35 foreach (UpdateResult ur in uResults)
36 {
37 lblMessage.Text += "Status Message: " + ur.StatusMessage;
38 lblMessage.Text += "<br/>";
39 }
40 }
41 catch (Exception ex)
42 {
43 //Set Message
44 lblMessage.Text += "<br/><br/>UPDATE ERROR:<br/>" + ex.Message;
45 }
46 }
47 catch (Exception exc)
48 {
49 //Set Message
50 lblMessage.Text += "<br/><br/>###ERROR<br/>" + exc.Message;
51 }
52 }
53}1using System;
2using System.Configuration;
3using System.Data;
4using System.Linq;
5using System.Web;
6using System.Web.Security;
7using System.Web.UI;
8using System.Web.UI.HtmlControls;
9using System.Web.UI.WebControls;
10using System.Web.UI.WebControls.WebParts;
11using System.Xml.Linq;
12using etAPI;
13public partial class SubscriberUpdate : System.Web.UI.Page
14{
15 //Global Variables
16 private SoapClient client = new SoapClient();
17 protected void Page_Load(object sender, EventArgs e)
18 {
19 //Authenticate
20 client.ClientCredentials.UserName.UserName = System.Configuration.ConfigurationSettings.AppSettings["wsUserName"];
21 client.ClientCredentials.UserName.Password = System.Configuration.ConfigurationSettings.AppSettings["wsPassword"];
22 if (!IsPostBack)
23 {
24 }
25 }
26 protected void btnSubmit_Click(object sender, EventArgs e)
27 {
28 try
29 {
30 //Create Subscriber object [Subscribers > My Subscribers > All Subscribers]
31 Subscriber sub = new Subscriber();
32 sub.SubscriberKey = "0613d278-888e-4825-b796-74a21a071391";//required //may not be active in all accounts //use EmailAddress instead
33 sub.EmailTypePreference = EmailType.Text;//EmailType.HTML is the default this only needs to be set to override to Text
34 sub.EmailTypePreferenceSpecified = true;
35 //Create an Array of Lists
36 sub.Lists = new SubscriberList[2];//If a list is not specified the Subscriber is added to the "All Subscribers" List
37 sub.Lists[0] = new SubscriberList();
38 sub.Lists[0].ID = 182857;//Available in the UI via List Properties
39 sub.Lists[0].IDSpecified = true;
40 sub.Lists[1] = new SubscriberList();
41 sub.Lists[1].ID = 947244;//Available in the UI via List Properties
42 sub.Lists[1].IDSpecified = true;
43 //Subscriber Attributes differ per account. Some may be required to create a Subscriber
44 sub.Attributes = new etAPI.Attribute[2];
45 sub.Attributes[0] = new etAPI.Attribute();
46 sub.Attributes[0].Name = "First Name";
47 sub.Attributes[0].Value = "Updated";
48 sub.Attributes[1] = new etAPI.Attribute();
49 sub.Attributes[1].Name = "Last Name";
50 sub.Attributes[1].Value = "ViaAPI";
51 try
52 {
53 string uRequestID = String.Empty;
54 string uStatus = String.Empty;
55 //Call the Update method on the Subscriber object
56 UpdateResult[] uResults = client.Update(new UpdateOptions(), new APIObject[] { sub }, out uRequestID, out uStatus);
57 //Display Results
58 lblMessage.Text += "Overall Status: " + uStatus;
59 lblMessage.Text += "<br/>";
60 lblMessage.Text += "Number of Results: " + uResults.Length;
61 lblMessage.Text += "<br/>";
62 //Loop through each object returned and display the StatusMessage
63 foreach (UpdateResult ur in uResults)
64 {
65 lblMessage.Text += "Status Message: " + ur.StatusMessage;
66 lblMessage.Text += "<br/>";
67 }
68 }
69 catch (Exception ex)
70 {
71 //Set Message
72 lblMessage.Text += "<br/><br/>UPDATE ERROR:<br/>" + ex.Message;
73 }
74 }
75 catch (Exception exc)
76 {
77 //Set Message
78 lblMessage.Text += "<br/><br/>###ERROR<br/>" + exc.Message;
79 }
80 }
81}The code sample below demonstrates how to unsubscribe a subscriber. Note that StatusSpecified must be set to true in order to change the status.
1Subscriber subscriber = new Subscriber()
2 {
3 EmailAddress = emailAddress,
4 // If your account does not have subscriber key enabled, ensure the following line is commented-out
5 CustomerKey = subscriberKey,
6 Status = SubscriberStatus.Unsubscribed,
7 StatusSpecified = true
8 };
9
10 //Specifies this as an upsert call
11 UpdateOptions options = new UpdateOptions
12 {
13 SaveOptions = new SaveOption[] { new SaveOption {SaveAction = SaveAction.UpdateAdd, PropertyName = '*'} }
14 };
15 string requestID, requestStatus;
16 //Executes the update API call
17 UpdateResult[] results = soapClient.Update(options, new APIObject[] { subscriber }, out requestID, out requestStatus);This code example updates subscriber information and creates a new subscriber if the application can’t find the appropriate record:
1public void testUpdateDataExtension() throws RemoteException {
2 Subscriber subscriber = new Subscriber();
3 subscriber.setEmailAddress("aruiz@example.com"); // updating to new email address.
4 subscriber.setSubscriberKey("aruiz_key"); //subscriber unique, can’t update
5 /*subscriber.Status = SubscriberStatus.Unsubscribed;
6 SubscriberList list = new SubscriberList();
7 list.ID = 12345; //List in which subscriber is there
8 subscriber.Lists = new SubscriberList[] { list };*/
9 Attribute attribute = new Attribute();
10 attribute.setName("username");
11 attribute.setValue("Angel");
12 subscriber.setAttributes(new Attribute[]{attribute});
13 //upsert option, it adds if subscriber is not present or updates if subscriber exists in system
14 CreateOptions co = new CreateOptions();
15 SaveOption saveOption = new SaveOption();
16 saveOption.setSaveAction(SaveAction.UpdateAdd);
17 saveOption.setPropertyName("*");
18 co.setSaveOptions(new SaveOption[]{saveOption});
19 Soap stub = init();
20 CreateRequest createRequest = new CreateRequest(co, new APIObject[]{subscriber});
21 CreateResponse createResponse = stub.create(createRequest);
22 System.out.println("CreateResposne :::: " + createResponse.getOverallStatus());
23}This code example updates a subscriber status to Unsubscribed.
1public void testUpdateSubcriberByKey() throws RemoteException {
2 Soap stub = init();
3 UpdateOptions updateOptions = new UpdateOptions();
4 Subscriber sub = new Subscriber();
5 sub.setSubscriberKey("aruiz@example.com");
6 sub.setStatus(SubscriberStatus.Unsubscribed);
7 UpdateRequest updateRequest = new UpdateRequest(updateOptions, new APIObject[]{sub});
8 UpdateResponse updateResponse = stub.update(updateRequest);
9 System.out.println("updateResponse :::: " + updateResponse.getOverallStatus());
10}1// Updates a subscriber's information (status in this example).
2public void testUpdateSubcriberByKey() throws RemoteException {
3 try {
4 Soap stub = init();
5
6 UpdateOptions updateOptions = new UpdateOptions();
7
8 Subscriber sub = new Subscriber();
9 sub.setSubscriberKey("jdoe@example.com");
10 sub.setStatus(SubscriberStatus.UNSUBSCRIBED);
11
12 APIObject[] apiObjects = {sub};
13
14 UpdateRequest updateRequest = new UpdateRequest();
15 updateRequest.getObjects().addAll(Arrays.asList(apiObjects));
16 updateRequest.setOptions(updateOptions);
17
18 UpdateResponse updateResponse = stub.update(updateRequest);
19 System.out.println("updateResponse :::: " + updateResponse.getOverallStatus());
20
21 } catch (Exception e) {
22 e.printStackTrace(); //To change body of catch statement use File | Settings | File Templates.
23
24 }
25}1<soap-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2 <SOAP-ENV:Header>
3 <wsse:Security SOAP-ENV:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4 <wsse:UsernameToken>
5 <wsse:Username>xxx</wsse:Username>
6 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">xxx</wsse:Password>
7 </wsse:UsernameToken>
8 </wsse:Security>
9 </SOAP-ENV:Header>
10 <SOAP-ENV:Body>
11 <ns1:UpdateRequest>
12 <ns1:Options/>
13 <ns1:Objects xsi:type="ns1:Subscriber">
14 <ns1:Attributes>
15 <ns1:Name>First Name</ns1:Name>
16 <ns1:Value>Updated</ns1:Value>
17 </ns1:Attributes>
18 <ns1:Attributes>
19 <ns1:Name>Last Name</ns1:Name>
20 <ns1:Value>ViaAPI</ns1:Value>
21 </ns1:Attributes>
22 <ns1:SubscriberKey>012345</ns1:SubscriberKey>
23 <ns1:Lists>
24 <ns1:ID>12345</ns1:ID>
25 </ns1:Lists>
26 <ns1:Lists>
27 <ns1:ID>12346</ns1:ID>
28 </ns1:Lists>
29 </ns1:Objects>
30 </ns1:UpdateRequest>
31 </SOAP-ENV:Body>
32</SOAP-ENV:Envelope>
j