Overview
Skill Level: Intermediate
Prerequisites
If you are using a custom opt‐out page and wish to record opt outs against specific mailings, you must ensure that the link to your opt‐out page within your mailing templates includes the following parameters:
%%MAILING_ID%%
%%RECIPIENT_ID%%
%%JOB_ID_CODE%%
Step-by-step
-
Syntax of the request and response XML for OptOutRecipient
Reliability Measures
SUCCESS in the XML response indicates that the system can—and will—opt out the contact. However, the opt-out may not happen immediately; Watson Campaign Automation places all opt‐out events in an event queue and processes them in the order in which the events are received. If an internal error occurs while processing the event from the queue, Watson Campaign Automation places the event in an error queue. When the problem is resolved, it moves back into the event queue.
We recommend that you document any responses other than SUCCESS to assist customer support in a manual investigation, should that be necessary. The following categories of errors can result in an unsuccessful request:
- Invalid field formats
- Database does not exist in Watson Campaign Automation
- Missing parameters when opting out for a particular mailing
- Database prohibits opting out through API
- Limited rights on the related database
To ensure opt‐out reliability, you should continue to retry any opt‐out requests that do not receive a response until you receive a SUCCESS response.
Operation <OptOutRecipient> Elements LIST_ID Identifies the ID of the database from which to opt- out the contact. EMAIL The contact email address to opt out. Note: If using a regular email key database, anode must exist for the Email column. If passing MAILING_ID, RECIPIENT_ID, andJOB_ID, Watson Campaign Auomation does not require EMAIL. You must provide each of the three elements if EMAIL is not included. MAILING_ID The internal Mailing ID passed to the opt‐out page using personalized links in the mailing template. Used to track opt‐outs at the mailing level. RECIPIENT_ID The internal ID of the Contact passed to the opt‐out page using personalized links inthe mailing template. Used to track opt‐outs at the mailing level. JOB_ID The internal Job ID passed to the opt‐out page using personalized links in the mailing template. Used to track opt‐outs at the mailing level. COLUMN XML nodes defining the column name and value. Ignored for regular email keydatabases. Note: Unique key columns must be part of the submission with columnnames and values. If you only specify the email address, the system will opt-out all contacts with that email address. Child Elements NAME Specifies the field name of the unique key for the database. VALUE Specifies the value of the field name for the unique key in the database. Example 1
Standard Opt-Out<Envelope>
<Body>
<OptOutRecipient>
<LIST_ID>45654</LIST_ID>
<EMAIL>someone@adomain.com</EMAIL>
<COLUMN>
<NAME>CustomerId</NAME>
<VALUE>123-45-6789</VALUE>
</COLUMN>
</OptOutRecipient>
</Body>
</Envelope>Example 2
Mailing Level
Opt-Out<Envelope>
<Body>
<OptOutRecipient>
<LIST_ID>45035</LIST_ID>
<MAILING_ID>132767</MAILING_ID>
<RECIPIENT_ID>0Ng3S0</RECIPIENT_ID>
<JOB_ID>NTQ5NTk5MwS2</JOB_ID>
</OptOutRecipient>
</Body>
</Envelope>Response <RESULT> Elements SUCCESS SUCCESS if successful. ORGANIZATION_ID Identifies your Watson Campaign Automation Organization. Example <Envelope>
<Body>
<RESULT>
<SUCCESS>SUCCESS</SUCCESS>
</RESULT>
</Body>
</Envelope>