ResourcesKnowledge Base

Integration

Mailkit provides extensive integration capabilities, both through API in XML and JSON format and through website events and Webhooks that can pass data to your application in real time. All integration settings take place in this section of the Profile.

API settings

The basis for communication with our API interface is identification data – API ID and MD5 code. In the integration settings, you will not only learn this information, but you also have the option to change the MD5 code in the event that it is leaked.

nastaveni-api.jpg

CAUTION - If you change your MD5 code, all your applications that use the current code will stop working until a new hash is entered on the application side.

Allowed IP addresses

For security reasons, the API only accepts connections from allowed IP addresses (or network ranges). For this reason, it is necessary to first add individual IP addresses, or subnets, or networks in this section. The format for entering network ranges is then using the netmask IP address, e.g. 192.168.1.0/24, to enable the full range 192.168.1.0-255.

CAUTION: The security of the API is fully under your control and it is necessary to keep this list up-to-date in order not to misuse your account. We also don't recommend allowing access from the entire Internet by entering the network 0.0.0.0/0 – this solution may be offered where cloud services are used, but you should rather contact your cloud provider and obtain a static IP or your own subnet.

Allowed domains

In order to successfully implement the Event API on your site, which is needed for conversion tracking and remarketing campaigns, you must first have the referrals on which the Event API will be deployed verified. Simply add the name of the referrer and then create a file on the server with the name and content according to the instructions and have it verified.

CAUTION: Authentication of the referrer (i.e. the source of the call) is a key security feature that cannot be omitted. Therefore, it is not possible to use resources for development and testing purposes that cannot be verified by the network (e.g. localhost). An Event API call from an unauthorized source always returns a 403 Forbidden response.

Webhook URLs

Mailkit allows data to be passed to the client's own interface for further processing using a webhook. Currently, webhooks are supported for registration of consent, separately for obtaining consent and withdrawing consent, i.e. Subscribe and Unsubscribe. Within each webhook, a different range of information is passed in the form of a JSON structure passed by POST by calling the URL specified in the Profile / Integration menu in the Webhook URLs section.

Subscribe:

The following values ​​in the JSON structure are passed in the POST call within the login webhook:

EMAIL – email address
ID_EMAIL – ID of the email address
DATE – date and time of adding the email address in the format YYYY-MM-DD HH:MM:SS
IP – IP address that confirmed the consent
IP_ORIG – IP address that confirmed the consent
ID_ML – ID of the recipient list
CHANNEL – channel with which consent was confirmed
UA – user-agent-string of the device to which the consent was granted
DATE_REQUEST – date and time when the login request was created
UA_REQUEST – user-agent-string of the device for which the login request was created
IP_REQUEST – IP address from which the login request was made
IP_ORIG_REQUEST – IP address from which the login request was made
URL_CODE – The verification code that confirmed the confirmation
FIRST_NAME – Name
LAST_NAME – Surname
FAX – fax
GENDER – gender
MOBILE – mobile phone
NICK_NAME – nickname
PHONE – telephone
PREFIX – degree
REPLY_TO – address for replies
STATE – state
STREET – street
VOCATIVE – addressing
ZIP – postcode
CITY – city
COMPANY – company
COUNTRY – country
CUSTOM1 – custom field no.1
...
CUSTOM25 - custom field no.25

Unsubscribe:

When you log out or change topics, the following values are passed in the JSON structure in POST:

EMAIL – email address
ID_EMAIL – ID of the email address
DATE – date and time of logout in the format YYYY-MM-DD HH:MM:SS
IP – IP address from which the logout took place (if available)
IP_ORIG – IP address from which the logout took place (if available)
ID_ML – ID of the list of recipients from which the logout was made
ID_SEND – ID of the campaign delivery from which the recipient logged out
ID_MESSAGE – ID of the campaign from which the recipient has logged out
ID_TOPIC_ACTIVE – list of active topics of the recipient (in case of a change of topics)
ID_TOPIC_INACTIVE – list of unsubscribed topics of the recipient (in case of a change of topics)
TIMEOUT – length of temporary logout (number of days)
EXPIRE – date and time when the temporary logout will be deactivated
METHOD – unsubscribed method (link_in_mail, manual, spam_report, list-unsubscribe_mail, api_unsubscribe, list-unsubscribe_oneclick, timeout)
UNSUBSCRIBE_ANSWER – selected reason for logout
UNSUBSCRIBE_NOTE – note on the reason for logout (if available)

Keep in mind that not all of these values may always be filled in, so they may be blank.

Webhook interface security

The interface that receives webhook calls from Mailkit should be protected against misuse. Of course, the lowest possible protection is to ensure that no one knows the URL of this interface. However, it is much more secure to secure this address against unauthorized access, either by restricting access to this address only from the IP addresses of the Mailkit servers, or by using a client SSL certificate.

To restrict access to the interface only from Mailkit servers, restrict access only to IP addresses from the 185.136.200.0/22 network. Mailkit operates with its own infrastructure and does not use any third-party servers or cloud services, so it is certain that the requests coming from this network are valid requests. In cases where, due to internal security policies, security using IP addresses is not sufficient, we recommend using security using client certificates.

Security with client certificates

For the purpose of verifying the authenticity of the call, it is possible for the webhook call to be authorized using client SSL certificates. For this purpose, it is possible to use standard Mailkit certificates or certificates supplied by the client. If you use standard certificates, it is necessary to install the Mailkit public certificate available at https://static.mailkit.eu/mailkit_webhook_ca.crt on the client server with the webhook interface and set its use (here is an example for setting up on the Apache server):

SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile "/etc/ssl/mailkit_webhook_ca.crt"

If you need to use multiple certification authorities, it is a good idea to replace the SSLCACertificateFile directive with this line:

SSLCACertificatePath "/etc/ssl"

It is possible to place more root certificates in the given directory, then it is necessary to run another command:

/etc/ssl# c_rehash -v

Once the certificate is deployed on the server, it is possible to request verification and activation by email to helpdesk@mailkit.com.

In order to use custom client SSL certificates, the webbook provider must provide Mailkit with a client certificate and a RSA key protected by password. This password will be securely transmitted separately from the certificate.

Creating certificates using openssl

It is possible to generate a self-signed certificate as follows:

openssl genrsa -out ca.key 2048
openssl req -days 3650 -new -x509 -key ca.key -out ca.crt

This ca.crt will be used by the web server at https://url_webhook_interface, i.e. for example the SSLCACertificateFile directive below needs to be directed. If you already use another CA certificate for this purpose, you can use it, but you will also need the key associated with this certificate.

Creating a key with a password and CSR:

openssl req -days 3650 -new -newkey rsa:2048 -keyout mk.eu.key -out mk.eu.csr

You can then create a client certificate:

openssl x509 -req -days 3650 -in mk.eu.csr -CA ca.crt -CAkey ca.key -
CAcreateserial -out mk.eu.crt

If you have a certificate and key created as above (here we assume the use of the above commands), you can verify them:

curl -v --cert mk.eu.crt --key mk.eu.key https://url_rozhrani_webhooku

If everything is OK, the file mk.eu.crt and mk.eu.key must be sent to the Helpdesk. These files will then be deployed on the Mailkit side. Then send the password for the certificate (if it was entered during creation) separately (e.g. SMS) with information about the ticket ID from the helpdesk that was assigned to your certificate deployment request.

On the Mailkit side, the certificate will be decoded and the certificate will be recoded and stored with a system password that is different for each customer.

The functionality of the interface and certificate verification can then be simulated and verified, for example, using the curl utility:

curl -E --cert mk.eu.crt --key mk.eu.key https://url_webhook_interface
-d '{"ID_ML":"1234","ID_MESSAGE":"12345","METHOD":"api_unsubscribe",
"UNSUBSCRIBE_NOTE":"abc","TIMEOUT":"","IP":"1.2.3.4",
"IP_ORIG":"0.0.0.0","ID_EMAIL":"123456","EMAIL":"test@somewhere.com",
"EXPIRE":"","ID_TOPIC_ACTIVE":"0","ID_TOPIC_INACTIVE":"0",
"ID_SEND":"123","DATE":"2018-08-31 12:33:15","UNSUBSCRIBE_ANSWER":""}'

In the call, the --cert and --key parameters include the path to the files containing the generated certificate and key. It is then necessary to add the address to the custom interface, which is to be tested.

The interface provider must ensure that the certificate is authenticated and only respond with status code 200 if a valid request is made. Replies with a different status code will cause the webhook to retry with increasing delay until it expires after 24 hours when the webhook as a whole is deactivated.

Example of certificate authentication configuration on Apache server:

SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile "ca.crt"

The SSLCACertificateFile parameter must contain the path to the file generated as the authority certificate when generating the keys.