ResourcesKnowledge Base

Integration

Setup your your integration options and API access for 3rd party systems.

API settings

This section shows you the main information required for all your API calls - Your Client ID, MD5 hash as well as the URL of the API interface.

nastaveni-api.jpg

Allowed IPs

povolene-ip.jpgBoth our XML-RPC and JSON APIs accept connections only from allowed IPs or network ranges. To permit access from a specific IP you have to add such IP (or network) to this list. The network ranges can be added using a netmask format of the IP, eg. 192.168.1.0/24 to allow all IPs in range 192.168.1.0-255.

WARNING: The security of the API interface is fully under your control and it's critical to keep the list of IPs up to date to prevent unathorized use. We also strongly discourage you from allowing world-wide IP access to network 0.0.0.0/0 - while this might be required in cases where cloud base services need to access the API, we recommend you contact your provider to get a static IP or an IP range.

Allowed domains

To implementing Event API on your website to tracks visitors, send events, track conversions and run remarketing campaigns it's necessary to permit calls from hostnames where the event API scripts will be used and verify control of such hosts. This is done by creating a file on your server with a specific filename according to instructions and click to validate the address.

WARNING: website call source validation is a critical security requirement that can't be skipped. For this reason the unvalidated sources or sources not accessible from internet (eg.localhost) can not be used not even for testing purposes. Any unauthorized call to event API will result in a 403 Forbidden error response.

povolene-domeny.jpg

Subscribe and Unsubscribe webhook URLs

Whenever a recipient signs up or signs out, Mailkit processes this activity and can immediatelly relay this information to your endpoint using a webhook. The information is passed to these URLs using a POST method with a JSON structured data about the registered activity. The URL entered is validated on save using a GET and POST call to verify availability of the endpoint entered. 
webhooks_cz.png

The subscribe webhook POSTs the following fields in JSON structure:

EMAIL - email address of the recipient
ID_EMAIL - ID of the email address
DATE - date and time of the subscription in format of RRRR-MM-DD HH:MM:SS
IP - IP address used during confirmation
IP_ORIG - IP address used during confirmation
ID_ML - ID of the mailing list
CHANNEL - channel used to confirm subscription
UA - device user-agent-string used to confirm subscription
DATE_REQUEST - date and time of request for subscription
UA_REQUEST - device user-agent-string used to request subscription
IP_REQUEST - IP address used to request subscription
IP_ORIG_REQUEST - IP address used to request subscription
URL_CODE - validation code used in the link to confirm
FIRST_NAME - first name
LAST_NAME - last name
FAX - fax
GENDER - gender
MOBILE - mobile phone
NICK_NAME - nickname
PHONE - phone
PREFIX - title
REPLY_TO - reply-to address
STATE - state
STREET - street
VOCATIVE - vocative
ZIP - ZIP code
CITY - city
COMPANY - company
COUNTRY - country

CUSTOM1 - custom field no.1
...
CUSTOM25 - custom field no.25

For unsubscribe or topic subscription changes the POST will pass following fields in JSON stucture:

EMAIL - email address
ID_EMAIL - ID of email address
DATE - date and time of unsubscribe in format of RRRR-MM-DD HH:MM:SS
IP - IP address of unsubscribe request (when available)
IP_ORIG - IP address of unsubscribe request (when available)
ID_ML - ID of mailing list from which the recipient unsubscribed
ID_SEND - ID of campaign delivery from which the recipient unsubscribed
ID_MESSAGE - ID of campaign from which the recipient unsubscribed
ID_TOPIC_ACTIVE - list of recipient's active topics (in case of topic changes)
ID_TOPIC_INACTIVE - list of recipient's inactive topics (in case of topic changes)
TIMEOUT - duration of the timeout (in days for temporary unsubscribe)
EXPIRE - date and time of timeout expiration
METHOD - method used for unsubscibe (link_in_mail,manual,spam_report,list-unsubscribe_mail,api_unsubscribe,list-unsubscribe_oneclick,timeout)
UNSUBSCRIBE_ANSWER - unsubscribe reason selected
UNSUBSCRIBE_NOTE - optional unsubscribe reason text provided

Please keep in mind that not all values must be present and therefor POST may contain empty values for some of the fields.

Securing webhook interfaces

The interface receiving webhook calls from Mailkit should be secured against abuse. The minimum security precaution is to prevent anyone from finding out your interface's URL address. We recommend protecting the interface by limiting access to it from IP addresses of Mailkit. This can be done by only allowing access from the IP network of 185.136.200.0/22. At Mailkit we operate our own infrastructure on our own IP network so it's safe to say that any request coming from our IP range is legitimate.