Overview

Skill Level: Any

Prerequisites

This interface moves a contact in a database to an opted‐out state. 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%%

Reliability Measures
SUCCESS in the XML response indicates that the system can—and will—opt out the contact. However, the optout may not happen immediately; Engage 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, Engage 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.

Step-by-step

  1. Syntax of the request and response SOAP for OptOutRecipient

    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, a node must exist for the Email column. If passing MAILING_ID, RECIPIENT_ID, and JOB_ID, Watson Campaign Automation 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 in the 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 key databases. Note: Unique key columns must be part of the submission with column names 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
    <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
    xmlns:sil=”SilverpopApi:EngageService.SessionHeader”
    xmlns:sil1=”SilverpopApi:EngageService.ListMgmt.RecipientActions”>
    <soapenv:Header>
    <sil:sessionHeader>
    <sil:sessionid>10F7FB1E69637264D36CD36C9F68739E</sil:sessionid>
    </sil:sessionHeader>
    </soapenv:Header>
    <soapenv:Body>
    <sil1:OptOutRecipient>
    <sil1:LIST_ID>45654</sil1:LIST_ID>
    <sil1:EMAIL>someone@adomain.com</sil1:EMAIL>
    <sil1:COLUMN>
    <sil1:NAME>SSN</sil1:NAME>
    <sil1:VALUE>123‐45‐6789</sil1:VALUE>
    </sil1:COLUMN>
    </sil1:OptOutRecipient>
    </soapenv:Body>
    </soapenv:Envelope>
       
    Example 2
    Mailing Level
    Opt Out
    <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
    xmlns:sil=”SilverpopApi:EngageService.SessionHeader”
    xmlns:sil1=”SilverpopApi:EngageService.ListMgmt.RecipientActions”>
    <soapenv:Header>
    <sil:sessionHeader>
    <sil:sessionid>10F7FB1E69637264D36CD36C9F68739E</sil:sessionid>
    </sil:sessionHeader>
    </soapenv:Header>
    <soapenv:Body>
    <sil1:OptOutRecipient>
    <sil1:LIST_ID>45654</sil1:LIST_ID>
    <sil1:MAILING_ID>132767</sil1:MAILING_ID>
    <sil1:RECIPIENT_ID>NTM3NjI0NTg3S0</sil1:RECIPIENT_ID>
    <sil1:JOB_ID>NTQ5NTk5MwS2</sil1:JOB_ID>
    </sil1:OptOutRecipient>
    </soapenv:Body>
    </soapenv:Envelope>
       
    Response <RESULT>    
    Elements SUCCESS SUCCESS if successful.  
      ORGANIZATION_ID Identifies your Watson Campaign Organization.  
    Example <envelope:Envelope xmlns:envelope=”http://schemas.xmlsoap.org/soap/envelope/”>
    <envelope:Header/>
    <envelope:Body xmlns=”SilverpopApi:EngageService.ListMgmt.RecipientActions”>
    <RESULT>
    <SUCCESS>true</SUCCESS>
    <ORGANIZATION_ID>1dcd49d‐108b594203df528764d624db129b32c21fbca0cb8d6</
    ORGANIZATION_ID>
    </RESULT>
    </envelope:Body>
    </envelope:Envelope>
       

Join The Discussion

Your email address will not be published. Required fields are marked *