Data Onboarding Guide

Overview

InboxSuite is an advanced marketing tool for sending 1:1 email communication. Being run by machine learning models and AI, in order to work, it needs to get customer data imported first. This document is a curated set of guides that describe how to onboard data for maximized efficiency of InboxSuite.

There are a few points to cover before onboarding your data to InboxSuite. These points are important for you to take full advantage of the platform such as detailed traffic reporting that shows the quality of your traffic channels, sources, and landing pages. 

These points also enable advanced segmentation based on engagement activities combined with traffic details, as well as help AI to learn from the data and comply with the email regulations such as GDPR.

 

Getting started

In InboxSuite a subscriber is defined as a profile. Profiles can be added or modified (Please follow our Subscriber Interest Guide) (adding link to Subscriber Interests) using API. The API address that accepts all incoming data posting requests is:

https://intrust.inboxsuite.com/

To add a new profile you need to send a GET request to this URI. An example of an URI accepting GET request to add a new profile may look like this:

https://intrust.inboxsuite.com/?apikey=kgu8s18gibwy2vdv&email=johndoe@gmail.com&ip=123.123.123.123&sourceurl=yoursite.com&regdate= 2019-08-24T16:27:00&refid=ch-cpc_src-direct_lp-yoursite.com&status=11

Apart from sending the request to the base URI, there are compulsory parameters that are required for every API GET request adding a new profile. All of them are described in the Terminology section.

Before running an API call to add profiles a data source needs to be created in Profiles - Data Posting section of the InboxSuite interface (Please contact your Client Success Manager to create data sources). Note that apart from mapping fields there is a “Clean new subscribers” feature. Checking it will cause every newly added profile to be verified against a database containing invalid or dangerous addresses like spam traps.

TIP: Did you know in InboxSuite we have a Sync & Async API url. To configure the posting process, you can use the debug version that returns an API response (we strongly recommend against regular use of this method due to restrictions), example:

https://intrust.inboxsuite.com/v2?apikey={api-key}&email={profile-email}&ip={profile-ip}&sourceurl={subscribe-source}&regdate={profile-registration-date}&refid={profile-refid}&status={profile-status}

This can be useful at the stage of import debugging.

 

Terminology

Apikey

API key is a unique identifier that serves you as an authenticator. API keys are unique for each account and should not be shared with anyone outside of your organization. You can receive your API key by contacting your dedicated account manager. Similarly, your API key and API url will be available under the Data Posting section.

An example API key may look like this:

kgu8s18gibwy2vdv

Email

Email is a parameter that passes the profile’s email address to InboxSuite. As a standard, email must comply with RFC 822. 

An example of the email that complies with this rule is: 

johndoe@gmail.com

Insight:

Dots do matter! Gmail allows mailbox owners to own all dotted versions of the email.

However, in InboxSuite, if you post email addresses with dotted versions, they will be considered as a separate profile.

IP

The IP parameter transfers the information about the IP address of the profile at the moment of signing up to your contact list. This information is required to follow compliance policies, as well as to share with ISPs upon request regarding complaint issues.

But this is not the only reason why you must post a real IP address. This information is being used in Geo reporting, as well as identifying the time zone of the profile. All these details are used in AI algorithms to provide you the highest engagement results.

In the example above the IP address of a profile is:

123.123.123.123

Finally, if you have email addresses that are collected through offline events, please contact your Client Success Manager for handling those records.

Sourceurl

Information about the website’s URL where the user provided their email address and where the signup form is passed in sourceurl parameter. Similarly to the case of IP, a record with signup URL is required to follow compliance policies, as well as to share with ISPs upon request regarding complaint issues. 

The URL passed in API request should be encoded according to RFC 3986, which means that it can look like this:

Yoursite.com

Regdate

Along with the IP and source URL, a user who signs up to your contact list leaves a timestamp information at the moment of registration. This field is also required to supplement the signup information details needed for compliance reasons. The timestamp provides information about the date and time of the registration.

An example of a timestamp is:

2019-08-24T16:27:00

Regdate can be provided in other formats as well. Here is a list of allowed formats:

YYYY-MM-DD 2006-01-23

YYYY-MM-DDTHH:mm:ss 2006-01-23T15:04:05

YYYY-MM-DDTHH:mm:ss 2006-01-23T15:04:05.123

YYYY-MM-DDTHH:mm:ss 2006-01-23T15:04:05.123456

YYYY-MM-DD HH:mm:ss 2006-01-23 15:04:05

YYYY-MM-DD HH:mm:ss 2006-01-23 15:04:05.123

YYYY-MM-DD HH:mm:ss 2006-01-23 15:04:05.123456

YYYY-MM-DD HH:mm:ss(+/-)TZO 2006-01-23T15:04:05-07:00

M/D/YYYY 1/23/2006

M/D/YYYY HH:mm:ss 1/23/2006 15:04:05

MM/dd/yyyy  HH:mm:ss 01/23/2006 15:04:05

These details are later used in Delivery reporting to understand and analyze the performance of profiles based on their registration date, as well as in the campaign segmentation when you want to target profiles according to registration date.

On top of that AI uses this information when it comes to sending the Confirmation Flow (Please refer to our Initial Flow Guide for more details).

Refid

Refid plays a crucial role in your email campaign optimization. It serves as a source identifier which helps to assign channel name, source name, and landing page to profile’s data. With the proper format of refid information, you will be able to analyze traffic reports. For example, it can tell which channel, source, or landing page performs better in terms of conversion rates or deliverability.
Refid can also be used within campaign segmentation where you can target your subscribers based on their originating channels, sources, or landing pages.

On top of that, refid is also used in Machine Learning algorithms used by InboxSuite’s AI to make decisions that lead to increased engagement of your audience.

All of these details have a direct impact on your engagement results. Understanding your traffic details is the first step to increase your engagement metrics. As stated above, refid details are evaluated by AI to identify the right profile when it comes to clustering them based on their interest groups. Educating AI with missing or wrong data can negatively impact your engagement metrics. It is important for you to follow the refid format.

Refid consists of 3 sub elements that define channel (ch), source (src), and landing page (lp). You can find more information about each of these elements below. Notice that in the example above refid passes the following information: channel is cpc, source is direct and landing page is yoursite.com. Each value is separated by “_” and after the refid sign there is a hyphen. Combined it looks like this: 

Ch-cpc_src-direct_lp-yoursite.com

Channel

Channel part of the refid parameter can contain any value as long as it’s made of alphanumeric characters. Here is a list of typical values for channel:

referral - Referral traffic is the segment of traffic that arrives on your website through another source, like through a link on another domain.

email - Traffic coming to your website from email can be tagged this way.

cpc - Contextual ads traffic is the segment of traffic that lands on your website through the advertisements appearing on websites or other media.

social - Social ads traffic is the segment of traffic that lands on your website through social media platforms, messaging apps, news feeds, and even outside apps.

display - Display ads traffic goes to your website through conveying a commercial message visually using text, logos, animations, videos, photographs, or other graphics.

push - Browser push ads or web push notification ads traffic arrives through commercial messages served by websites (rather than apps) on both desktop and mobile devices.

cpa - CPA offer traffic is the traffic segment that comes to your website after the target customer takes an action on the publisher side.

directcenter - Organic traffic is those visitors that are redirected to your website from unpaid sources.

coreg - Coregistration means that profiles are registered to your contact list along with other lists.

TIP: You can add different custom channels that you are using. The only important thing is to have specific data here. Please avoid using random information. These details are later on used in analyzing your data. 

Source

Traffic source can be used to enhance the tracking capabilities of your email campaigns. Whenever a profile is signed up to your mailing list from a source that you wish to identify by any ID, source is the right place to add this ID. InboxSuite will present the data about performance of a given source in the reporting section. 

Examples: affiliate id, network id, advertising campaign id. 

Landing page

If leads are collected from a specific landing page, this information is worth storing for future use. You can use it in segmentation or for performance tracking. The landing page (lp) parameter is the place where you should add this information when adding a new profile to InboxSuite.

On top of that, lp values can help you when it comes to creating flows like Confirmation Flow.

Having different flow types based on landing page information can help you control your email strategies more effectively.

Status

Profiles can be stored in InboxSuite in a number of subscription states. Their state is described by a status parameter and it’s a numerical value. In the example the status is set to 11 which means it’s a subscriber. You can find more information on statuses below.

Status 11 - subscriber

Subscriber is the profile who is considered as a single opt-in. We recommend targeting such profiles with Confirm and Welcome flows or campaigns to confirm their subscription status. Confirmation will not only change profile’s status to 12 - confirmer, but will also show a positive signal to the ISP. As a result, deliverability to such profiles may be higher than to non-confirmed profiles.

Please reach out to your dedicated account manager and ask about the best solutions and tools to convert subscribers into confirmers. Our team is always happy to help.

Status 12 - confirmer

Confirmer is the profile who has already confirmed subscription and therefore is a double opt-in subscriber. This status means that the profile gave explicit (second time) permission and is eligible to receive campaigns that are promotional in their content.

Insight: 

In InboxSuite, we separate resources and mailings for single opt-in and double opt-in profiles.

Our data research shows that double opt-in traffic has 7.5 times more unique clicks compared to single opt-in profiles.

Status 10 - unsubscriber

Whenever a profile unsubscribes from the contact list, their status changes to 10 - unsubscriber. While adding new profiles via API you can also add the ones who have clearly shown their intent to stop receiving any emails from your side.

TIP: If you have unsubscribers on your side, it is recommended to import those profiles and sync the statuses. 

Insight:

In InboxSuite we have one click unsubscribe logic.

In InboxSuite we can unsubscribe from email replies.

Important:

Resubscription is available! Profiles that unsubscribe can be resubscribed to your website. On top of that we can start the onboarding process for them from scratch and send confirmation emails in case of resubscription.

Status 100 - legacy

Legacy profiles represent the group of subscribers who have not unsubscribed from the contact list yet, but at the same time are not active any more. This status should be assigned to profiles who were actively engaged in campaigns on every stage of the customer journey, but their activity stopped. 

Insight:

In InboxSuite, profiles that have 6 months of inactivity are considered a Legacy.

Status 1000 - complainer 

Profiles with status 1000 are the ones who complained to the ISP about receiving the email from you. The complaints are collected via mechanisms called Feedback Loops and you should always make sure to stop sending campaigns to complaining users. InboxSuite automatically changes statuses of complaining users to 1000. 

Once we register a complaint from the profile, on top of changing subscription status to complainer, this profile will also be considered as unsubscriber and will not be able to resubscribe to your website.

On top of the above, we also have these additional statuses:

Status 0 - for profiles that have no subscription status.

Status 1 - for profiles that have active Open status.

Status 2 - for profiles that have active Click status.

 

Custom fields

On top of the required fields that are added when a profile is created, there is a possibility to add some custom data points to each profile. There are 5 additional, although not required, fields you can use to complement the profile’s data. These fields are:

Token

Token can be used to store additional identification of a profile. It can be the profile’s id in your CRM system or any other identifier. 

An example of such token can be:

0cc0891c8f9720688f33e86297a370

TIP: Token id can be used as site authentication.

Fname

Fname stands for First name and it’s a field allocated to store information about a profile's first name. 

lname

Lname stands for Last name and it’s a field allocated to store information about a profile’s last name. 

phone

Phone field is reserved for storing profile’s phone number.

Gender

Gender field is used to keep information about a profile's gender. Only M or F values are accepted. 

siteXX || Custom Fields

There are 20 fields that can be used for storing additional information about the profile. Their names always start with “site” and are followed by a number, for example site00 or site15. The highest number you can use for this field is site19. You can use them to keep any information you find useful for your email campaigns. It might be data about interests or transactional data. Creating these fields should be discussed and pre-configured on the InboxSuite’s side. Please contact your client success manager for more details.

TIP: siteXX can be used as a substitution in email content or in feed parameters when it comes to targeting specific groups of profiles that share the same interests. Please refer to the Email Feeds Guide for more information.

 

How-tos

How to add profiles in real time? 

Before you start sending API requests you need to create a data source in the InboxSuite interface first. Simply log in to InboxSuite and go to Profiles - Data posting and create your data source. Make sure to map all relevant fields you pass in API requests and note down the API key that will be displayed after the data source is successfully created. 

The next step is to ensure that the API request is sent every time a contact signs up to your list. Whether it’s a form on your website or any other way of generating leads, make sure the API request is triggered when the user hits the submit button. 

Short interface steps:

Step1	Navigate to Profiles / Data posting
Step 2	Create new data source by clicking “+” sign
Step 3	Add data source name
Step 4	Uncheck “clean new subscribers” (if needed)
Step 5	Map fields with corresponding names used in InboxSuite
Step 6	Finalize by clicking “Save”

 

Please note that the best practice is to convert profiles from subscriber to confirmer. That being said, you may want to use subscribe (11) status when it comes to posting data in order to convert them to confirmer (12) status profiles. Therefore, the simple API call to add a subscriber in real time from your website may look like this: 

https://intrust.inboxsuite.com/?apikey=kgu8s18gibwy2vdv&email=johndoe@gmail.com&ip=123.123.123.123&sourceurl=yoursite.com&regdate= 2019-08-24T16:27:00&refid=ch-cpc_src-direct_lp-yoursite.com&status=11

Starting Profile Journey

Real-Time traffic is the most preferred traffic when it comes to building a solid IP/Domain reputation. Considering profiles recently subscribed, sending them a Subscriber Trigger Campaign is the first step to convert them from Single Opt-In to Double Opt-In. This is needed for better delivery resource allocation and further verification of email addresses..

Hint! It is obligatory to put the ${confirm} substitute in the Call-To-Action URL. Considering that not every profile would immediately confirm their subscription, by enabling AI solutions we can send them into Confirm Flows to remind them of their subscription and try to get confirmation. After this stage, it is recommended to set up a Welcome Flow to greet the profiles that confirmed their subscriptions.

Please refer to the Flows Guide for further details. 

How to add an inactive profile and turn it to an active profile?

Profiles can be created with status 10 - legacy. These are contacts who have not been active for some time and it would be beneficial if they were reactivated. 

Here is an example of an API call to add legacy contacts:

https://intrust.inboxsuite.com/?apikey=kgu8s18gibwy2vdv&email=johndoe@gmail.com&ip=123.123.123.123&sourceurl=yoursite.com&regdate= 2019-08-24T16:27:00&refid=ch-cpc_src-direct_lp-yoursite.com&status=100

For legacy type, it is recommended to run Manual Activation Campaign. This option is available under Email → Campaigns → Manual Activation. Once reactivation is successful, profile status for those addresses will be changed from Legacy to Single Opt-In or Double Opt-In.

After the profile status update, AI will take these profiles to the AI flows and start their profile journey.

Please refer to the Campaigns Guide for further details.

How to add a profile with custom values?

Custom values that do not fit in any of the required fields can be stored in siteXX (where XX is a number from 00 to 19) fields. If you wish to add profiles with values assigned to these fields, please contact your dedicated client success manager, so they can be pre-configured first.

Once the setup is complete, you can start sending API requests that will add profiles to your InboxSuite account. An example of an API request that adds a profile with a value “test” in site00 field can look like this:

https://intrust.inboxsuite.com/?apikey=kgu8s18gibwy2vdv&email=johndoe@gmail.com&ip=123.123.123.123&sourceurl=yoursite.com&regdate= 2019-08-24T16:27:00&refid=ch-cpc_src-direct_lp-yoursite.com&status=11&site00=test

 

Summary

InboxSuite has an extensive API to allow you to import your data. The quality of your profiles plays a crucial role in building strong and stable deliverability. Considering that with InboxSuite you will operate on dedicated IP addresses, building reputation can be guided but it still demands high list quality, uniqueness of your creatives, and understanding of how different traffic channels, sources, or landing pages perform. 

Setting up a proper data onboarding process is the first, extremely important step to achieve this. Good luck!

Final Hints;

It is highly recommended to verify email addresses before posting them to InboxSuite. You can implement reCaptcha to avoid spam traps or unknown email addresses ending in your database.

Built-in tools for importing new profiles, like refid, can further help you with understanding which sources or channels outperform others and therefore should be utilized more.