Skip to main content

Bloomreach Integration Guide

Updated

How Wunderkind Integrates With Bloomreach

The Bloomreach (formerly Exponea) integration with Wunderkind will enable us to collect and send new email addresses to your ESP, verify subscription status before sending an email, and update a user’s subscriber status if they unsubscribe. 

This guide includes an overview of everything that Wunderkind can and cannot support, considerations, requirements placed on us by Bloomreach, and more.

Wunderkind requires UI access to Bloomreach in order to build and test our integration with your Bloomreach instance.

 

Table of Contents:

  1. Authentication
  2. Writing New Subscribers
  3. Checking Customer Status
  4. Checking Mailability
  5. Updating Unsubscribe Status
  6. Sender Options
  7. URL Appending
  8. Important Callout

1. Authentication

In order to authenticate our API calls, we use an encoded Public and Private Key pair in the header of the API call.  If applicable, we can also use a client-specific Base URL that is provided to us. 

Requirements

  • We require a Project Token to use in the URL path for our API calls.
  • We need to know what ID or customer attribute field corresponds to a user’s email
    • Bloomreach stores IDs in several ways, but for our integration we need one of them to correspond to a plaintext email address. We will use this in our API calls to properly identify users. It cannot be an attribute or a property, it must be an ID type. This can be either a soft ID or a hard ID. “email_id” is the most common ID type used. Further descriptions and examples of customer identifiers can be found HERE. 

2. Writing New Subscribers

Upon email submission, Wunderkind will write new subscribers to Bloomreach through the API calls below. We can write new subscribers in the following ways:

  • Adding a new subscriber
  • Optionally updating a new subscriber with an event (eg, consent)
  • Additional properties may be added when creating a new subscriber. 

Wunderkind will perform a duplicate check to ensure we are not attempting to create a record for an already-existing subscriber. This is done by submitting a request with a “customer_ids” value that corresponds to the email and checks to see if that returns an email address.

API Calls for Writing New Subscribers

Request
POST /track/v2/projects/{project_key}/customers/events HTTP/1.1
Host: https://api.us1.exponea.com/
Authorization: Basic Base64("public key:private key")

with Consent Event - Body
   "customer_ids": {

        "email_id": "wkndtest@wunderkind.co"
    },

    "event_type": "consent",
    "timestamp": "1697646090",
    "properties": {
        "action": "accept",
        "category": "newsletter",
        "valid_until": "unlimited",
        "message": "Wunderkind",
        "timestamp": "1697646090",
        "website_country": "au"
    }
}'
without Consent Event - Body
'{
    "customer_ids": {
            "email_id": ""wkndtest@wunderkind.co"
    },
    "properties": {
        "email": "wkndtest@wunderkind.co"
          }
}'
{

 

3. Checking Customer Status

Wunderkind emails are segmented to send a different series to prospects (never purchased from your brand before) vs. returning customers (have made at least one purchase). This enables value propositions and messaging customized to each group.

Wunderkind does not have the ability to check Bloomreach for a customer status, so instead we’ll rely on:

  1. Wunderkind Conversion Pixel Data
  2. Historical and Recurring File Uploads

Conversion Pixel Data

The pixel will be provided by your Wunderkind account manager. Ensure that it is set up to fire for all checkout flows and payment types, so that all orders are captured by the pixel. This pushes order data into Wunderkind’s systems and is used to determine whether a user is a returning customer. 

Historical and Recurring File Uploads

The conversion pixel captures data for online orders from the point in time that it’s added to your website. In order to capture historical and offline order data, you can send csv files that will be ingested into our system. 

Please work with your Wunderkind contact to provide customer files. We support one-time or manual list sends, or we can partner with you to set up a recurring file sends. For example, sending customer files on a daily basis to an SFTP that Wunderkind automatically picks up to ingest.

The first historical upload allows us to know from Day 1 who is a returning customer. From that point on, a combination of the conversion pixel and optional recurring uploads will fill in the blanks.

 

4. Checking Mailability

We can check for a user’s mailable status in two ways: 

  1. Checking a user’s subscription status
  2. Checking a user’s specific consent properties

Subscription Status Check 

Within a user’s profile we can check the value of a user’s ‘unsubscribed’ property

  • If a user’s profile returns as unsubscribe: true we consider them NOT mailable
  • If a user’s profile returns unsubscribe: false or null we consider them mailabe
  • Note: The property returns null when a property doesn’t exist or doesn’t have an initial value 

Consent Property Check

Users can have “consent” statuses within Bloomreach that correspond to messaging types or groupings (e.g. Marketing Emails, Newsletter, etc.) Within the platform, updating consent is an “event,” with the consent action as either “accept” or “reject” for the specified field. We can only update a user’s consent status for ONE field. 

We can check if a user has opted-in to a specific consent field to determine mailability.

  • If a user does not have a value of “true” for the specified consent field, we consider them NOT mailable (“opt-in check”)
  • If a user does not have a valid consent field (due to not existing in the ESP or the consent field is not defined), we can consider the user mailable (through an “opt-out check”). We default to an opt-out check unless otherwise specified.

*See index for more information on opt-in vs. opt-out check

API Calls for Checking Mailability

Request
POST data/v2/projects/{project-key}/customers/attributes HTTP/1.1
Host: https://api.us1.exponea.com/
Authorization: Basic Base64("public key:private key")
Subscription Status Check - Body 

{
     "customer_ids": {
     "email": "wkndtest@gmail.com"
      },
     "attributes": [
     {
         "type": "property",
         "property": "unsubscribe"
          }
     ]
}
Consent Property Check - Body 

{
     "customer_ids": {
     "email": "wkndtest@gmail.com"
     },
     "attributes": [
     {
        "type": "consent",
        "category": "newsletter"
        }
     ]
}

 

5. Updating Unsubscribe Status

The methods in which we mark a user as not mailable mirror how we check a user’s mailability seen in the Checking Mailability section. We can do one of the following: 

  • Update a user’s unsubscribe status from false to true 
  • Update a user’s specific consent field from true or null to false 
    • This is also known as creating a ‘reject’ consent event for a user. If a user does not exist, a record is created with a reject consent event. 

In addition to the above methods, we can also update certain attributes on a user’s profile upon unsubscribe. This is commonly used for updating a timestamp or source of unsubscribe. 

With the exception of a timestamp, we cannot update fields with dynamic data. For example, we can update ‘Unsubscribe Source’ to Wunderkind, but we cannot pass specific campaign names. 

If a user does not exist in Bloomreach when unsubscribing or updating an email after a send, we do not create a new user within Bloomreach. They will be unsubscribed from Wunderkind emails moving forward. 

API Calls for Updating Unsubscribe Status

Request (Revoke Consent for Given Field)

POST /track/v2/projects/{project_key}/customers/events HTTP/1.1
Host: https://api.us1.exponea.com/
Authorization: Basic Base64("public key:private key")

Update Consent - Body

{
"customer_ids": {
"email":"wkndtest@gmail.com"
},
"event_type":"consent",
"properties": {
"action":"reject",
"category":"newsletter",
"valid_until":"unlimited",
"data_source":"WKND"
}
}

 

6. Sender Options

Wunderkind is able to deploy an email in two ways: either through Wunderkind’s ESP, or through your Bloomreach account (this is called “Client Sender”).

Client Sender

With a Client Sender Integration, Wunderkind will pass a fully-rendered email to Bloomreach for deployment, leveraging Bloomreach’s Transactional API. This does not require any additional setup within the Bloomreach platform, but you must ensure that Wunderkind has Transactional API access. Emails are hosted in Wunderkind’s platform and sent through the API with the full html body. 

As part of our API payload, we will enable “all clicks” tracking within emails (see “Transfer identity to URL - Limitations” section of Bloomreach’s email campaign documentation).

If Wunderkind sends to a user does not exist in Bloomreach, a user will be created upon send. This new user will not have a valid consent event. If they unsubscribe, a reject consent event will be added to their profile. If a user does exist in Bloomreach, a duplicate record will not be created. 

Wunderkind Sender

With the Wunderkind Sender, we’ll deploy Wunderkind emails through our own ESP. We do have the ability to make an update post-send and record an event on the user’s profile. With this option we can add dynamic data in the event, such as campaign name and timestamp. This pushes information about the send into Bloomreach without needing to physically deploy the email via Bloomreach.

API Calls for Sender

Request
POST /email/v2/projects/{project_key}/sync HTTP/1.1
Host: https://api.us1.exponea.com/
Authorization: Basic Base64("public key:private key")
Client Sender - Body

{
     "email_content": {
        "sender_address": "example@client.com",
        "sender_name": "Client Name",
        "subject": "subject",
        "html": "<html>hello world</html>"
     },
     "campaign_name": "test",
     "recipient": {
        "email": "wkndtest@wunderkind.co",
        "customer_ids": {
          "email_id": "wkndtest@wunderkind.co"
        }
     }
}
Wunderkind Sender, update post-send - Body

{
    "customer_ids": {
        "email":  "wkndtest@wunderkind.co"
    },
    "event_type": "property",
    "timestamp": 1690925297,
    "properties": {
        "last_send": "1704294045",
“campaign_name”: “wknd_product_abandonment_1”
    }
}

 

7. URL Appending

URL Appending is one of Wunderkind’s most impactful identification methods. It allows us to identify users returning to your site from marketing messages (non-WKND marketing emails). It is a reverse lookup that we're able to do using a key (unique identifier) that maps to a plaintext email address and appended to all clickout email links.

We use a Customer ID that is passed to us (as a soft ID or hard ID as referenced in the Authentication section, not an attribute or property) and link it with a plaintext email address. By default, our integration will look to reconcile the Customer ID with the value of the Email ID field. Note: This is different from the email_id field, which is a separate ID type. 

We can also use the Customer ID and search for properties within the user’s profile that corresponds to the user’s email. For example, if we are passed a hashed or unique string that corresponds to user’s email_id in Bloomreach, we can look to see if they have an ‘email’ property on their profile.

Within Bloomreach, please append the Customer ID value to all emails.

API Calls for URL Appending

Request
POST data/v2/projects/{project-key}/customers/attributes HTTP/1.1
Host: https://api.us1.exponea.com/
Authorization: Basic Base64("public key:private key")

Body
{
"customer_ids": {
"hash_id": "12345"
},
"attributes": [
{
"type": "property",
"property": "email"
}
]
}

 

8. Important Callouts

  • Our integration requires an ID field that corresponds to a plaintext email address (see: Authentication)
  • We can only update a user’s consent status for ONE field (see: Checking Mailability)
  • When performing a subscription status check, if the status is not set (null), we will consider them mailable, even if we are doing an opt-in check (see: Checking Mailability)
    • Note: This is NOT true for a consent property check. 

If a user does not exist in the ESP when unsubscribing or updating an email after a send, we do not create a new user within Bloomreach. They will be unsubscribed from Wunderkind emails moving forward. (see: Updating Unsubscribe Status)

 

Related articles

Powered by Zendesk