Quick introduction

Our API interface runs as a REST web service that is really easy to use. It is founded on simple communication with HTTP protocol and uses JSON for data exchange.

Supported HTTP methods

We support HTTP methods which are usually used amongst REST web services. Each HTTP method has a different function. The way of interpretation is described in this list:

  • GET - loads one or more records
  • POST - creates a new record
  • PUT - updates an existing record
  • DELETE - deletes a record

System authentication

Access to the system

If you don't have the API key or login to our system please contact us at info@webkomplet.cz

1) Use of the API key

Step 1 - Generating the API key

In Mail Komplet, go to the settings section -> API keys, and generate a new API key there. Please keep the “baseCrypt” with you for it serves as and identificator for your account - you can find it in the upper part of the website in the text area.

Step 2 - Creating the RESP API request

We will start creating the request now. When creating the URL for request in the system we must know the API key and the baseCrypt. The final address, where 'xxxx' is replaced with baseCrypt, will look like this:

https://api.mail-komplet.cz/api/xxxx/(methodName)

Header of this request has to have this information, which is:

  • Header “Authorization” containing the API (in the sample below replace 000000000000000 with your generated API key)
  • Header “X-Requested-With:XMLHttpRequest“
  • Header “Accept: application/json;charset:utf-8“ - this string tells us in which format will the data be received
Sample of the header request

Accept: application/json;charset:utf-8
X-Requested-With:XMLHttpRequest
Authorization: Basic 00000000000000
                                            
Step 3 - Choosing a relevant HTTP method and a request method in the REST API systems

You can find a list of all methods in the REST API system documentation which are available within REST API including every relevant HTTP method with which you need to call them. Please choose a relevant action (method) that you want to do with API and fill it in the sample request instead of "(methodName)"

Step 4 - Sending request and processing the response

If all the steps above are fulfilled, you can send the request with a HTTP method. Return HTTP codes can be found above in the documentation.

2) Cookies usage

Step 1 - Authentication with login

When creating URL for the request in the system we must know your login. We then send the data to this URL:

https://api.mail-komplet.cz/api/authentication/signIn

This request must containt following headers:

Accept: application/json;charset:utf-8
X-Requested-With:XMLHttpRequest
                                            

To send this request use the "POST" HTTP method, where in the body of the request will be a JSON object with following content (replace xxx with your login name and yyy with your login password):


{
    "server": "01",
    "userName": "xxx",
    "password": "yyy"
}
                                            

Send this request using the POST method. In case of receiving the return code 403 check please the validity of your login name and login password. In case of receiving the return code 200 a cookie, which allows you for further work with the REST API, will be set and consequently data will be recieved from which please save the "baseCrypt" value - we will need this value for further work with the REST API.

Step 2 - Choosing the right account

Send a request for "businessUnits" method in a way that is showcased below where xxxx should be replaced with "baseCrypt" which you got in case of a successful sending of the previous request and processing its response. The URL request is as follows (do not forget the relevant header and check if the request contains the authentication cookie):

https://api.mail-komplet.cz/api/xxxx/businessUnits

After sending the request and receiving the answer with a return code 200, you will get a mailing list which are available to you. In case of receiving a different return code please check if your request contains a correct baseCrypt, authentication cookie and needed headers.

Choose a mailing list which you want to work with (from the received objects field) and save the baseCrypt for the chosen mailing list.

Step 3 - Sending the first request for working with a mailing unit

Now we can try sendind the first test request. For testing reasons we can try working with mailing lists first.

When calling the "mailingLists" method it returns created mailing lists and while using the POST http method you will get a request for creating a new mailing list.

While trying to create a new mailing list the body of the request must containt a data in JSON format in a way that is showcased below:


{
    "name": "List created with API",
    "description": "I have created this list using a test API request"
    "isTest": false
}
                                            

Send a request to the following URL with a POST HTTP method (do not forget the relevant headers and authentication cookie), where to body of the request will contain JSON data mentioned above and replace xxxx with a baseCrypt for the choesn account you want to work with (we got that in the step 2):

https://api.mail-komplet.cz/api/xxxx/mailingLists

In case of a succesful sending you will get a return code 200 which means the mailing list is created which can be verified by sending a GET HTTP method. This request will send you back a list of mailing lists where your chosen list should be listed.

Step 4 - Sending a request and processing the response

If all steps above are fulfilled, you can send the request with a HTTP method. Return HTTP codes can be found above in the documentation.

Mailing lists /mailingLists

GET - getting all mailing list from your account
GET api/xxxxxx/mailingLists

Mailing lists are returned, which are available in your account in our system.

Available parameters:
Parameter name Data type Parameter type Description
mailingListId integer optional mailing list ID you want to find
campaignId integer optional campaign ID with which the mailing list is connected
contactId integer optional sender ID which can be found in returned mailing list
isTesting boolean optional if mailing list are marked as "testing" a value "true" is returned
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - creating a new mailing list
POST api/xxxxxx/mailingLists

Creates a new mailing list within the account.

Sample JSON object that has to be found in the body request:

{
  "name": "Testing mailing list",
  "description": "Mailing list description",
  "isTest": true
}
                                    
PUT - updating an existing mailing list
PUT api/xxxxxx/mailingLists/{mailingListId}

Update of a mailing list where xx in URL should be replaced with mailing list ID you want to update.

Sample JSON object that has to be found in the body request:

{
  "name": "Testing mailing list",
  "description": "Mailing list description",
  "isTest": true
}
                                    

Tip

It is possible to use the same properties as in the POST method in JSON when creating a new mailing list. Properties that are not found in the JSON object will not be updated.

DELETE - deleting a mailing list
DELETE api/xxxxxx/mailingLists?mailingListIds=xx&unassign=xx

Deletes a mailing list from the system.

Available parameters:
Parameter name Data type Parameter type Description
mailingListIds integer obligatory IDs of a mailing list you want to delete, IDs are separated by comma, semicolon or pipe
unassign bool optional If the value of the parameter is set to "true" (default value), the mailing lists are deleted but recipients are still in the database. If the value of the parameter is "false", the mailing lists are deleted and the recipients are also completely deleted from the database.

Contacts /contacts

GET - getting all recipients from your account
GET api/xxxxxx/contacts

Return recipients which can be found in the system under entered parameters.

Available parameters:
Parameter name Data type Parameter type Description
contactId integer optional ID of a recipient you want to get
mailingListId integer optional ID of a mailing list in which recipients can be found
email string optional e-mail of a wanted recipient (just a bit of e-mail address will do)
page integer optional Page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - import of a new recipient
POST api/xxxxxx/contacts

Creates a new recipient (if already existing it will update the existing data).

Sample JSON object that has to be found in the body request:

{
  "name": "John",
  "surname": "Newman",
  "title": "Dear sir",
  "email": "john.newman@mail-komplet.cz",
  "sex": true,   
  "company": "Mail Komplet",
  "mailingListIds": [1, 2, 3],
  "customColumns": {
    "description": "long text",
    "nextItem": "text"
  }
}
                                    

Parameter of a mailingListIds

Parameter "sex" can contain these values:

  • null - unknown gender
  • false - woman
  • true - man

Parameter of a mailingListIds

Parameter of a “mailingListIds” contains a field of IDs of mailing lists in which the recipient can be listed.

Parameters of customFields

Parameter "customFields" is an object which contains names of user columns a their values. User column has to be created first about which you can read here.

POST - mass recipient import
POST api/xxxxxx/contacts/bulk

Executes a mass import based on showcased parameters.

Sample JSON object that has to be found in the body request:

{
    "preImportAction": 1, 
    "contactOverwriteMode": 1, // 1 - Merge, 2 - Overwrite, 3 - Skip  
    "mailingListIds": [1, 2, 3],
    "contacts": 
    [
        { 
            "name": "Jerome",
            "surname": "Tansill",
            "title": "Dear Mr.",
            "email": "tansill@webkomplet.cz",
            "sex": true,
            "company": "Webkomplet",
            "customData": null,
            "mailingListIds": [1, 2, 3],
            "customColumns": { "description" : "long text", "nextItem" : "text"}
        },
        { 
            "name": "Scott",
            "surname": "George",
            "title": "Dear Mr.",
            "email": "george@webkomplet.cz",
            "sex": true,
            "company": "Webkomplet",
            "customData": null,
            "mailingListIds": [2],
            "customColumns": { "description" : "long text"}
        },
        {
            "email": "homer@webkomplet.cz",
        }
    ]
}
                                    

Parameter preImportAction

Parameter “preImportAction” can take these values:

  • 1 - add new records, ignore existing records (existing records, that exist in a chosen mailing list, will be skipped. New records will be added and put in a mailing list
  • 2 - discard current records, add imported records (all records from a chosen mailing list will be discarded during import. All imported records will be added to the mailing list.
  • 3 - delete existing records, add new records (all records in a chosen mailing list will be DELETED during import. All imported records will be added to the mailing list).

Pamareter mailingListIds

Parameter “mailingListIds” contains ID field of mailing lists in which the recipient should be placed.

Parameter customColumns

Parameter “customColumns” is an object, which contains names of user columns and their values. User column must be created first with the action "customColumns" about which you can find some information here.

GET - acquiring information about the import of recipients
GET api/xxxxxx/contacts/getBulkInfo

Returns information about the state in which the import currently is.

Available parameters:
Parameter name Data type Parameter type Description
operationId GUID obligatory unique ID of a mass recipient import
PUT - updating a recipient
PUT api/xxxxxx/contacts/{contactId}

Updates an already existing recipient. Variable {contactId} in URL replace with an ID of the specific recipient which you want to update:


{
  "name": "John",
  "surname": "Newman",
  "title": "Dear sir",
  "email": "john.newman@mail-komplet.cz",
  "sex": true,   
  "company": "Mail Komplet",
  "mailingListIds": [1, 2, 3],
  "customColumns": {
    "description": "long text",
    "nextItem": "text"
  }
}
                                    

Tip

It is possible to use the same parameters in JSON object as with the POST method for creating a new recipient. Parameters which will not be included in the JSON object will not be updated.

DELETE - deleting a recipient
DELETE api/xxxxxx/contacts

Deletes a contact from the system

Available parameters:
Parameter name Data type Parameter type Description
contactIds integer obligatory recipient's ID (there can be more - split them with comma), which you want to delete
mailingListId integer optional mailing list ID from which the recipients should be deleted

Warning!

In case the mailing list ID has not occured the recipients will be deleted from the database! (this action is irreversible)

Templates /templates

GET - getting all templates from your account
GET api/xxxxxx/templates

Returns available templates in your account.

Available parameters:
Parameter name Data type Parameter type Description
templateId integer optional ID of a template you want to get
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)

Campaigns /campaigns

GET - getting all campaigns from your account
GET api/xxxxxx/campaigns

Returns available campaigns in your account.

Available parameters:
Parameter name Data type Parameter type Description
campaignId integer optional ID of a campaign you want to get
campaignGroupId integer optional ID of a campaign group from which you want to return the campaigns
name string optional part of a campaign name you want to get
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - creating a new campaign
POST api/xxxxxx/campaigns

Creates new campaing in the system

Sample JSON object that has to be found in the body request:

{ 
    "unsubscribeTypeId": 2, 
    "ignoreExcludeList": false,
    "autoLinkTracking": true,
    "name": "New campaign",
    "description": "Short description campaign",
    "webTrackParam": "null",
    "senderDisplayName": "Webkomplet",
    "senderEmail": "info@webkomplet.cz",
    "insertTrackingImage": true,
    "contactFilter": null,
    "templateId": 516
}
                                    

Parameter unsubscribeTypeId

Parameter “unsubscribeTypeId” can acquire these values:

  • 0 - don't allow unsubscribing from the campaign
  • 1 - unsubscribe from the campaign
  • 2 - unsubcribre from all mailing lists assigned to the campaign
  • 3 - mass unsubscribe

PUT - updating the campaign
PUT api/xxxxxx/campaigns/{campaignId}

Updates an already created campaign. Replace the variable {campaignId} in URL with an ID of a campaign you want to update.

Sample JSON object that has to be found in the body request:

{ 
    "unsubscribeTypeId": 2,
    "ignoreExcludeList": false,
    "autoLinkTracking": true,
    "name": "New campaign",
    "description": "Short description campaign",
    "webTrackParam": "null",
    "senderDisplayName": "Webkomplet",
    "senderEmail": "info@webkomplet.cz",
    "insertTrackingImage": true,
    "contactFilter": null,
    "templateId": 516
}
                                    

Tip

It is possible the use the same parameters in the JSON object as with the post method for creating a new campaign. Parameter, which will not be found in the JSON object, will not be updated.

DELETE - deleting a campaign
DELETE api/xxxxxx/campaigns

Deletes a campaign based on an ID

Available parameters:
Parameter name Data type Parameter type Description
campaignId integer obligatory ID of a campaign you want to delete

Domain redirects /dispatchers

GET - returns all domain redirects in your account
GET api/xxxxxx/dispatchers

Returns domain redirects which are available in your account.

Available parameters:
Parameter name Data type Parameter type Description
dispatcherId integer optional ID of a domain redirect you want to get
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)

Transactional e-mails /transactionalEmails

GET - returns all transactional e-mail from your account
GET api/xxxxxx/transactionalEmails

Return a list of transactional e-mail which are available based on chosen parameters.

Available parameters:
Parameter name Data type Parameter type Description
emailId integer optional ID of a transactional e-mail
createdFrom datetime optional date of creation from
createdTo datetime optional date of creation to
toAddress string optional e-mail of a recipient (just a part of the e-mail will do)
state integer optional state of a transactional e-mail
isOpened bool optional specify true if you want to get only opened transactional e-mails
isClicked bool optional specify true if you want to get only clickthrough transactional e-mails
guid GUID optional an ID which is returned when a transactional e-mail is created
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - sending a transactional e-mail
POST api/xxxxxx/transactionalEmails

Sending a transactional e-mail.

Sample JSON object that has to be found in the body request:

{
    email: {
        fromAddress: "peter@mail-komplet.cz",
        fromDisplayName: "Mail Komplet",
        to: [{ 
                address: "recipient@mail-komplet.cz",
                variables: {
                    nothingVariable1: "variable text 1 for this email",
                    nothingHtml: "Hi, dear recipient"                    
                }
            }
        ],
        subject: "Your first email message.",
        bodyHtml: "Hello world.",
        bodyText: "Hello world.",
        attachments: [
        {
            "contentType": "text/plain",
            "name": "file.txt",
            "content": "VGhpcyBpcyB0ZXN0"
        }
        ],
        variables: {
            nothingVariable: "variable text 1 fro all emails",
            nothingText: "text 1 fro all emails",            
        },      
        trackOpens: true,
        trackClicks: true,
        campaignId: 2525
    }
}
                                    

Optional items: campaignId, attachments, variables

When filling the item "campaignId" information listed below will load from a predefined campaign. You should fill a campaign ID in this item which you can get by calling /campaigns.

GET - getting all records about the open rate of transactional e-mails in your account
GET api/xxxxxx/transactionalEmails/opens

Returns a list of transactional e-mails's open rate which is available based on specified parameters.

Available parameters:
Parameter name Data type Parameter type Description
openId integer optional ID of an transactional e-mail's open rate
emailId integer optional ID of a transactional e-mail
from datetime optional data of creation from
to datetime optional date of creation to
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
GET - getting all records about clickthroughs in transactional e-mails in your account
GET api/xxxxxx/transactionalEmails/clicks

Returns a list of clicktrough of transactional e-mails which are available based on chosen parameters.

Available parameters:
Parameter name Data type Parameter type Description
clickId integer optional ID of a record about a clicktrough in a transactional e-mail
emailId integer optional ID of a transactional e-mail
from datetime optional date of creation from
to datetime optional date of creation to
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)

Transactional SMS /transactionalSms

GET - getting all transactional SMS from your account
GET api/xxxxxx/transactionalSms

Returns a list of transactional SMS which are available based on chosen parameters.

Available parameters:
Parameter name Data type Parameter type Description
smsId integer optional ID of a transactional SMS
createdFrom datetime optional date of creation from
createdTo datetime optional date of creation to
to string optional Number of a wanted recipient (a bit of the number will do)
guid GUID optional ID of a transactional SMS that is returned when the transactional SMS is created
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - sending a transactional SMS
POST api/xxxxxx/transactionalSms

Sending a transactional SMS.

Sample JSON object that has to be found in the body request:

{
    sms: {
        to: [{ 
                number: "+420777666555"
            }
        ],
        text: "Your first SMS message.",
        groupId: 1      
    }
}
                                    

Distributions /generatorExecutions

GET - getting all distributions
GET api/xxxxxx/generatorExecutions

Returns distributions which are available based on chosen parameters.

Available parameters:
Parameter name Data type Parameter type Description
campaignId integer optional ID of a campaign you want to get
isTesting bool optional if the value is "true" only testing distributons will be returned
status integer optional status of the distribution
phase integer optional phase of the distribution
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)

Parameter status

Parameter "status" can acquire these values:

  • 1 - active
  • 2 - stopped
  • 3 - canceled
  • 4 - error

Parameter phase

Parameter "phase" can acquire these values:

  • 1 - waiting for generator to start
  • 2 - generating
  • 3 - sending
  • 4 - sent
  • 5 - you need to get more credits and restart the distribuo

User columns /customColumns

GET - getting all user columns
GET api/xxxxxx/customColumns

Returns user columns which are available based on chosen parameters.

Available parameters:
Parameter name Data type Parameter type Description
customColumnId integer optional ID of a recipient you want to get
isSystem bool optional the value "true" returns only predefined columns
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - creating a new user columns
POST api/xxxxxx/customColumns

Creates a new user column.

Sample JSON object that has to be found in the body request:

{
    "dataTypeId": 1,
    "name":”Name of the user column”,
    "caption":”title”,
    "description": “Description of the user column”, 
    "defaultValue":1,
    "minValue":1,
    "maxValue":1,
    "required" : false,
    "unique" : false
    "disabled": false,
    "precision" : null,
    "order": null
}
                                    

Parameter dataTypeId

Parameter "dataTypeId" can acquire following values:

  • 1 - text
  • 2 - number
  • 3 - yes/no
  • 4 - date and time
  • 5 - date
  • 6 - time

PUT - updating user columns
PUT api/xxxxxx/customColumns

Updates a user column.

Sample JSON object that has to be found in the body request:

{
    "dataTypeId": 1,
    "name":”Name of the user column”,
    "caption":”title”,
    "description": “Description of the user column”, 
    "defaultValue":1,
    "minValue":1,
    "maxValue":1,
    "required" : false,
    "unique" : false
    "disabled": false,
    "precision" : null,
    "order": null
}
                                    

Tip

It is possible to use the same parameters in the JSON object as with the POST method when creating a user columns. Parameters which will not be found in the JSON object will not be updated.

DELETE - deleting a user column
DELETE api/xxxxxx/contacts

Deletes a user column from your account

Available parameters:
Parameter name Data type Parameter type Description
customColumnId integer obligatory ID of a user column you want to delete

Unsubscribed recipients /excludeLists

GET - getting all unsubscribed recipients
GET api/xxxxxx/excludeLists

Returns unsubscribed recipients which are available based on chosen parameters.

Available parameters:
Parameter name Data type Parameter type Description
excludeListId integer optional ID of a unsubscribed recipient
mailingListId integer optional ID of a mailing list from which a recipient was unsubscribed
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
POST - unsubscribing a recipient
POST api/xxxxxx/excludeLists

Unsubscribes a recipient based on an e-mail address. If you want to unsubscribe a recipient globally from all mailing lists and all campaigns, leave out parameters "mailingListId" and "campaingId".

Sample JSON object that has to be found in the body request:

{
  "mailingListsId": 1,
  "campaignId": 1,
  "generatorExecutionId": 1,
  "email": "info@webkomplet.cz",
  "reason": "text"
}
                                    
DELETE - deleting a unsubscribed recipient
DELETE api/xxxxxx/excludeLists

Deletes a record about unsubscribing.

Available parameters:
Parameter name Data type Parameter type Description
excludeListId integer obligatory ID of a unsubscribed recipient's record

Abandoned cart

Warning!

To enable a function of the abandoned cart it is necessary to contact our customer support via chat in the system or via e-mail: info@mail-komplet.cz

The function of tracking abandoned carts is run with a tracking JavaScript code which you put in your website. If you are interested in this function, please make sure that you are allowed to interfere with your website's code.

After getting access we will send you a unique ID with which we will know it is your e-shop.

During implementation abandoned carts you have two options - first is sending all the content (updateBasketContent method - we recommend you this method) - or you will be using methods addBasketItem and removeBasketItem a send us individual changes in the cart.

Definition of a CartItem object
{ "amount": 1, "name": "name of an item in the cart", "url": "https://www.myshop.cz/link-to-product", "productImageUrl": "https://www.myshop.cz/images/image-of-the-product.jpg", "code": "EA1234567813", "currency": 5, "price": 100.00, "priceVat": 121.00, "category": "My category", "manufacturer": "Brand", "customFields": { "customField1": "Unpacked", "customField2": null, "customField3": null, "customField4": null, "customField5": null } }
Obligatory items: amount, name, code, price, priceVat, currency
Optional items: url, productImageUrl, code, price, priceVat

Item customFields is optional - you can store information for which there are no predefined fields.
Dial currency
CZK = 5, EUR = 7, USD = 32, GBP = 33
UpdateBasketContent - updating the whole cart
MkTracker.updateBasketContent(items[])

Updates the whole cart.

Available parameters:
Parameter name Data type Parameter type Description
items object[] obligatory Objects field - form of each object can be found in a section Definition of an object CartItem
AddBasketItem - adding item to the cart
MkTracker.addBasketItem(item)

Add an item to the cart. In case the item with the same combination "code" and "variant" already exists, the items will merge and will be updated.

Available parameters:
Parameter name Data type Parameter type Description
item object obligatory object in a form that can be found in a section Definition of the CartItem object
RemoveBasketItem - removing an item from the cart
MkTracker.removeBasketItem(item)

Remove an item from the cart. In this case the parameter "amount" defines what amount of this item was removed.

Available parameters:
Parameter name Data type Parameter type Description
item object obligatory object in a form that can be found in a section Definition of the CartItem object
SessionCompleted - converting the cart to an order
MkTracker.sessionCompleted(orderId, email)

Get a notification about converting the cart to an order. In this case it is obligatory to pass the ID of the order generated by your system + you can mention the parameter e-mail.

Available parameters:
Parameter name Data type Parameter type Description
orderId string obligatory ID of an order from your e-shop or web
email string optional E-mail address of the customer
IdentifyVisitor - identification of a web visitor
MkTracker.identifyVisitor(email)

Identifies an unknown visitor and pairs it to an e-mail address. We recommend you to call this everytime if we know the e-mail address of the visitor (login, sending an order, subscribing to your newsletters etc.).

Available parameters:
Parameter name Data type Parameter type Description
email string obligatory E-mail address of the visitor