Ometria Integration Guide

How Wunderkind Integrates With Ometria

The Ometria integration with Wunderkind will enable us to collect and send new email addresses to your Ometria, 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 Ometria, and more.

Wunderkind requires UI access to Ometria in order to build and test our integration with your Ometria 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 Callouts

1. Authentication

In order to authenticate our API calls, we’ll utilize a provided Ometria API key in the header of reach request.

X-Ometria-Auth: #{Auth_key}

2. Writing New Subscribers

Upon email submission, Wunderkind will write new subscribers to Ometria by creating a contact and then adding them to a collection. 

We may optionally send additional attributes through the “properties” key in our API request body, and we can pass optional list ids to add to a contact’s profile. We can pass phone number as an additional property, but we cannot update a user’s SMS preferences in Ometria. 

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 to the endpoint v2/profiles/?email={email} to check if the email already exists.

API Calls for Writing New Subscribers

Request
POST /v2/contacts/{collection_id}/{unique_id}
Host: https://api.ometria.com
X-Ometria-Auth: #{Auth_key}

Body
{
   "@type": "contact",
   "@add_to_lists": [
   "5268"
   ],
   "@collection": "wunderkind_subscribers",
   "email": "wknd+104@blackhole.ibx2.net",
   "marketing_optin": "EXPLICITLY_OPTEDIN",
   "timestamp_acquired": "2022-06-29T17:04:15+00:00",
   "timestamp_subscribed": "2022-06-29T17:04:15+00:00",
   "contact_id": "62bc860ebb53a1.00906789",
   "firstname": "wunder",
   "properties": {
   "subscribe_source": "wunderkind"
   }
}

3. Checking Customer Status

We will check a user’s profile by their email address to determine if they are a prospect or customer. If the user’s profile, under 'stats', shows a value greater than 0 in the 'orders' field, the user will be considered a customer for our email segmentation purposes.

API Calls for Checking Mailability

Request
GET
https://api.ometria.com/v2/profiles?email={email}
Headers:
X-Ometria-Auth: #{Auth_key}

Body
[
   {
     "id": "2a3d-9a4782-00b53d57",
     "email": "IamACustomer@wunderkind.co",
     ....
     "stats": {
       "orders": 17,
       "orders_attempted": 17,
       "total_items": 855,
       "aov": 1721.89,
       "visits": 9,
       "revenue": 29272.19
   }
...
   }
]

4. Checking Mailability

Wunderkind will check for a user’s mailable status by checking a user’s profile marketing_optin status. 

If a user’s profile has a property marketing_optin:true, we consider the user mailable. If false, the user is not mailable. 

If we check for a user that isn’t present in Ometria or has a null value for marketing_optin, we’d consider them not mailable if utilizing an opt-in check. If we utilize an opt-out check, these users would be considered mailable. Unless specified otherwise, we will default to an opt-in check.

API Calls for Checking Mailability

Request
GET
https://api.ometria.com/v2/profiles?email={email}
Headers:
X-Ometria-Auth: #{Auth_key}


Mailable Property Body
[
  {


       "id": "sample",
       "email": "sample@hotmail.com",
       "phone_number": null,
       "phone_number_country": null,
       "customer_id": null,
       "name": "sample",
       "prefix": "Mrs",
       "lastname": "sample",
       "firstname": "E",
       "suffix": null,
       "gender": "f",
       "country": "GB",
       "tags": [],
       "marketing_optin": true,
......
}
]

5. Updating Unsubscribe Status

If a user unsubscribes from a Wunderkind email, we’ll update the user’s profile marketing_optin to false.

Additional option properties may be passed to Ometria, for example, 'unsubscribe source'.

API Calls for Updating Unsubscribe Status

Request
POST /v2/push
Host: https://api.ometria.com
X-Ometria-Auth: #{Auth_key}


Update Unsubscribe Status, with additional Properties
[{
"@force_optin": false,
"email": "bouncex123@gmail.com",
"marketing_optin": "EXPLICITLY_OPTEDOUT",
"name": "123",
"id": "bouncex415@gmail.com",
"@type": "contact",
"properties":{"unsubscribe_source":"Wunderkind"}
}]

6. Sender Options

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

Client Sender

With a Client Sender Integration, Wunderkind will pass a fully-rendered email to Ometria for deployment, leveraging Ometria’s push API and custom events. Emails are hosted in Wunderkind’s platform and sent through the API with the full html body. 

Please work with your Ometria team to create Custom Events in your Ometria account, to use to deploy Wunderkind emails. By default, automation campaigns in the Ometria UI are configured to enter only users who have explicitly subscribed to receive email marketing. This means that when utilizing the Ometria Client Sender, you must use an opt-in check.

Wunderkind Sender

With the Wunderkind Sender, we’ll deploy Wunderkind emails through our own ESP.

API Calls for Client Sender

Request
POST /v2/push
Host: api.ometria.com
X-Ometria-Auth: #{Auth_key}

Body
[{
"@type": "custom_event",
"timestamp": "2022-11-28T11:23:35",
"id": "testfos98d6d845591d3feedd34",
"event_type": "wunderkind_abandon_basket",
"identity_email": "bryant.klein@wunderkind.co",
"properties": 
{
"html": "<body>test</body>"
}
}]

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.

Within Ometria, please append the user’s “id” to all email links. We recommend using “bxid” as the URL key (eg, bxid=id), but any URL key name is supported so long as the value appended is the user’s “id” value. This can be done in Ometria by updating default tracking parameters under account Settings > Email Settings to add "bxid" with the value {{ profile.hash }}. This will add the subscriber's unique identifier to all links in all marketing emails.

API Calls for URL Appending

Request
GET /v2/profiles/{id}
Host: api.ometria.com
X-Ometria-Auth: #{Auth_key}


Body
{
"id": "2ef1-e77592-02bd141e",
"email": "wkndtest@blackhole.ibx2.net",
"phone_number": null,
"phone_number_country": null,
"customer_id": null,
...
"properties": {},
...
}

8. Important Callouts

• Our Sender Integration requires Ometria’s team to set up custom events used to trigger sends.
• Ometria’s sender integration by default is an Opt-In check unless specifically set up as an Opt-out check in the Ometria UI.
  • Likewise, Wunderkind will default to an opt-in check in our mailability check.