ResourcesAPI documentation

Event API

Event API provides functions to create, update, add/remove content and close web events. Events are the building stones for creating remarketing campaigns and provide an easy way to create follow-up and pull-back campaigns based on website visitor activites, eg. abandoned shopping carts.

Initializing Event API

Before you can start to manage events from your website you need to initialize the API by loading the support scripts of the Event API:

<script type="text/javascript">
    var _mailkit = _mailkit || [];
    _mailkit.push(['setAPIID','Customer API ID']);
    _mailkit.push(['setDomain','referrer domain']);
</script>
<script type="text/javascript" async="true" src="//u.mailkit.eu/js/jsapi_v2.js"></script>

The API ID can be found in your Mailkit account in the menu Profile/Integration. You will also have to add and verify the referrer address (eg. www.mywebsite.com) to the list of allowed domains to allow Event API access to your account.

Creating event

Once the Event API has been initialized it's mandatory to call the function to initialize/refresh the actual event. It's required to call this function on every page where any manipulation with the event is to be done - for example on pages where you want to add items to shopping cart. Upon initEvent function call a unique event will be created or in case of an existing event the event will be reactivated for further use.

_mailkit.push(['initEvent', {
	'email': 'john@doe.com',
	'event_tag' : '',
	'return_url': 'http://yoursite.com',
	'description': 'text',
	'language': 'en',
	'currency': 'USD',
	'decimal_separator': ',',
	'first_name': 'John',
	'last_name': 'Doe',
	'gender': 'M',
	'order_no': '123456',
	'promo': '',
	'promo_value': ''
}]);

None of the variables are required as an event can last for a long period of time and therefor updated with the data later on when they become available.

email - email address of the visitor (if available) will be used to send messages. In case the the value is detect insted of an email address an automatic detection of recipient's email address will be performed. Automatic detection is not always realiable and we suggest providing an email address for the event as soon as one is available. Providing an email address also helps to avoid duplicate events but most importantly it's required for reliable email delivery.
event_tag - is used to distinguish between multiple events on a website. The main event should have no tag (for example a shopping cart) and the consequent events (eg. related items) shoudl be identified by a unique tag. Tag must not contain spaces or any special characters. This tag will be used later on during remarketing campaign setup as a condition to send the remarketing campaing only to events tagged with a specific tag.
return_url - return url fo the event. Usually this will be the URL of an abandoned shopping cart (max. 1024 chars)
description - additional description that can be used to add variable text content to the body of the email (max 2048 chars)
language - language of the even in ISO 639-1 format. This two-letter code can be used in message body to create conditionals to insert variable text based on language.
currency - item currency in ISO 4217 format - three-letter shorthand for example EUR, USD. Item currency should be used when running a multi-currency store. Mailkit will show the sale amounts unified to your home currency in the reports.
decimal_separator - since different countries use different decimal separators you can choose to define what separator will you be using. Based on that we will know how to store your numbers and if you are using . or , to separate decimals.
first_name - first name of the visitor if available. The value can be used in the content to personalize the message.
last_name - last name of the visitor if available. The value can be used in the content to personalize the message.
gender - gender of the visitor (M/F) if available. The value can be used in the content to personalize the message.
order_no - order number. Whenever it's possible try to provide a unique order number. This is one of the values that can help to avoid duplicate events that can occur when a visitor switches between devices.
promo - if your want to provide a discount code with an additional incentive you can pass it to the event and use it within your campaign body
promo_value - if you provide a discount code than you might want to post it's value as well to show in the campaign body.

Event items

Once your event has been created you need to add its content. You can do that at different points during your visitors activity on your website. It can be all done at once for example when the visitor enters the shopping cart or at different pages when the visitor adds an item to cart. Please note that events are not intended to replace your shopping cart and don't do any math or counting. It's solely on you as a developer to provide correct amounts, counts, prices when adding items as well to remove items when necessary.

_mailkit.push(['addItem', {
	'event_tag' : '',
	'product_id': 'SKUxxxx1',
	'name': 'Product name',
	'description': 'Nice a long product descriotion',
	'price': '12345.11',
	'item_qty': '1.1',
	'item_total': '12345.11',
	'product_url': 'http://yoursite.com/product/url',
	'product_category': 'Category',
	'product_cat_url': 'http://yoursite.com/category/url',
	'image_url': 'http://yoursite.com/path/to/image.jpg'
}]);

event_tag - event tag identifier as used during initEvent. Optional parameter.
product_id - product identifier (stock keeping unit). This is a unique identifier for each item and therefor there could be only one item with a set product_id. If multiple items with the same product_id are passed the subsequent items will be ignored not added to item count (max. 32 chars)
name - product name to be used in the campaign body. (max. 256 chars(
description - product description to be used in the campaign body. (max. 2048 chars)
price - product price (per unit) to be used in the campaign body. Value must be a number without any characters or symbols.
item_qty - item quantity (decimals allowed). Value must be a number without any characters or symbols.
item_total - total product price for all the items (multiply price and item_qty). Math has to be done by the developer - Mailkit doesn't do any math on top of the passed values. Value must be a number without any characters or symbols.
item_curr - item currency in ISO 4217 format - three-letter shorthand for example EUR, USD. Item currency should be used when running a multi-currency store. Mailkit will show the sale amounts unified to your home currency in the reports.
product_url - Product page URL to be used in the campaign body. (max. 256 chars)
product_category - Product category name to be used in the campaign body. (max. 64 chars)
product_cat_url - Product category page URL to be used in the campaign body. (max. 256 chars)
image_url - Product image URL to be used in the campaign body. (max. 256 chars)

Please don't forget that the product_id is the event item identifier that has to be always unique. If you want to change the quantity for an item you must first remove the item altogether and then add the item with the updated quantity.

To remove an item from an event (eg. remove from cart) you can call the removeItem function:

_mailkit.push(['removeItem', {
	'product_id': 'SKUxxxx1',
	'event_tag' : '',
}]);

Additionally you can remove all event items using clearItems function:

_mailkit.push(['clearItems', {
	'event_tag' : '',
}]);

Updating event

The initEvent function can be called at any time for a visitor with an existing event identified by a cookie using new event values to update the event. This comes very handy for example when a guest customer adds items to his cart and logs in later during his visit, or your eshop assigns a order id. Remember that more event values you have the better you can take advantage of remarketing events and personalization and increase the efficiency of your campaigns.

Finishing event

Once an event is succesfully completed, eg. an order is placed, you need to mark the event as completed using the finishEvent function:

_mailkit.push(['finishEvent', {
    'event_tag' : '',
    'invoice_no': 'xxxx1'
    'invoice_url': 'http://yoursite.com/invoice/url'
    'status_url': 'http://yoursite.com/order/status'
}]);

At this point the event gets marked as completed, the provede invoice number and URLs are stored and the event becomes a succesfull conversion in case a remarketing email has been clicked to complete the event. In case the event has been completed without an remarketing message the conversion will be added to the originating campaign if such a connection can be made.

All of the variables passed to an event and its items can be used in the body of the remarketing campaign, eg. to notify about an invoice issued.