Oracle Responsys Integration Guide

Table of Contents:

1. How to Create an Admin User
2. How to Find a List Name
3. How to Set Up URL Identification
4. Authentication
5. Writing New Subscribers
6. Checking Mailability

How to Create an Admin User

Admin ESP privileges enable Wunderkind to properly address concerns surrounding Personally Identifiable Information (PII) and comply with Google’s latest policies regarding this information. Admin access is also necessary to manage unsubscribe lists and be sure that customers are receiving only relevant emails.
 

Step 1. From an admin account, select Account, then User Management
 

Step 2. Select Add User
 

Step 3. Create TWO accounts with the following credentials. One account will be used for UI access, the other for API access. <AccountName> is your company name.
 

Account 1 - UI :
Login Name : ui_wknd@<AccountName>
Display Name : WKND UI USER
Email address: esp+<AccountName>@wunderkind.co
Roles: Super User OR Email Marketing Director, Data Director, Forms Director, AND Content Designer

Account 2 - API :
Login Name : API_wknd@<AccountName>
Display Name : WKND API USER
Email address: esp+<AccountName>@wunderkind.co
Roles: Every role that has Web Services in the name - Campaign Web Services Manager, Content Web Services Manager, List Web Services Manager, AND Table Web Services Manager (this will prevent UI login so the password won’t expire). Do not select the Super User role.

How To Find a List Name

List IDs allow Wunderkind to

• Pass users from email capture experiences to the correct location and
• Check the subscriber status of users in our send pool prior to sending emails

Step 1. From the side menu, select Manage Lists under the Data tab

Step 2. Under Change List, you will see every List ID. Wunderkind will need the List ID for the master contact list, which is set to CONTACTS_LIST by default by Responsys. If this is not the case, please provide whichever List ID reflects the master.

How To Setup URL Identification

The URL Identification Integration enables Wunderkind to map users who click through from marketing emails to our identification engine via a secret key, the RIID. This integration is in line with Google’s industry regulations and standards regarding PII, as it does not expose a user’s email address in plain text in the URL.

Step 1. Open the Responsys menu and click Account

Step 2. Once in the account management section, select “Set external tracking parameters”

Step 3. In the External Tracking Parameters section you can add custom parameters either for Classic Campaign or New Campaign. Click “Add Parameter”

• Classic Campaign – This will only appear in older Responsys accounts and is the old way of creating campaigns in the platform
• New Campaign – This is for campaigns created with the newer campaign management tool

Step 4. Enter bxid in the name field.

• Classic Campaign – Default value should be $RIID_$
• New Campaign – Default value should be ${RIID_}

Save the changes after making the updates above.

Authentication

Wunderkind uses a standard bearer token to authenticate with your Responsys instance. The API username and password created previously will be used for authentication. 

POST  https://login2.responsys.net/rest/api/v1.3/auth/token
Content-Type: application/json

{
  "user_name": "API_wknd@<AccountName>",
  "password": "<PASSWORD>"
}

Writing New Subscribers

When a user submits their email through a Wunderkind experience, we will:

1. Check Responsys for an existing contact by email (and/or external ID) using the master contact list.
   • If no contact exists:
       - A new contact is created in the master list with the submitted email address.
       - Additional fields such as acquisition source or timestamp can be set per requirements.
   • If a contact exists:
       - Optionally update selected fields (e.g., acquisition source, last_acquired timestamp) for resubscribe if required

API Call for Writing New Subscribers

Request
POST /rest/api/v1.3/lists/CONTACTS_LIST/members HTTP/1.1
Host: https://api.rsys9.net
Authorization: Bearer <authToken>
Content-Type: application/json

{
   "recordData":{
      "fieldNames":[
         "EMAILADDRESS",
         "EMAIL_PERMISSIONSTATUS",
         "FIRST_EMAIL_ACQ_SOURCE",
         "LAST_EMAIL_ACQ_SOURCE",
         "LAST_EMAIL_ACQ_TS"
      ],
      "records":[
         [
            "wkndtest@example.com",
            "I",
            "WUNDERKIND",
            "WUNDERKIND",
            "2025-02-05T14:32:00Z"
         ]
      ]
   },
   "matchColumnName1":"EMAILADDRESS",
   "insertOnNoMatch":true,
   "updateOnMatch":"REPLACE_ALL"
}

Checking Mailability

Before Wunderkind sends a triggered email, we will:

• Query Responsys to verify that the contact is mailable according to the fields designated
    (for example: a permission / opt-in flag, deliverability status, and any brand‑specific flags). 
  • One or more profile list fields can be used to determine mailability. 
  • List ID is needed to confirm mailability

API Call for Checking Mailability

ET /rest/api/v1.1/lists/{LIST ID}/members?qa=e&id=wkndtest@wunderkind.co&fs=all HTTP/1.1
Host: api2-026.responsys.net
Authorization: Bearer <authToken>

Updating Unsubscribe Status

When a user unsubscribes from a Wunderkind email that is sent via Responsys, they can be unsubscribed by:

1. Using a Responsys unsubscribe link that takes users to a preference center form
2. Wunderkind making an API call to update certain profile fields to signify that user has unsubscribed
   1. API call for unsubscribe update is structurally similar to the subscriber API call above, but sets the relevant permission field to an “unsubscribed” value and/or clears marketing flags