Quick introduction

Our API interface runs as a REST web service that is really easy to use. It is based 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

Response codes

Response codes are part of server response to client's request. Most of the responses usually contain these response codes:

  • 200 - OK
  • 201 - Created - an item was created successfully
  • 400 - Bad Request - an error in user request (e.g. in JSON object)
  • 403 - Forbidden - usually an error in API key or in base crypt

System authentication

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

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

You have to specify content type via Content-type header, when using POST and PUT methods.


Content-type: application/json
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 that are available within REST API. Every relevant HTTP method you need to call is included. Please choose a relevant action (method) 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 here.

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 please check 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 shown below where xxxx should be replaced with "baseCrypt" which you got in case of a successful sending of the previous request and processing the 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 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 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 sending 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. 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 shown 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, where to body of the request will contain JSON data mentioned above and replace xxxx with a baseCrypt for the chosen 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. You can verify this 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 here.

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 request 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 bool 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)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
            "mailingListId": 8947,
            "name": "Mailing list name",
            "description": "Mailing list description ",
            "created": "2018-03-13T07:10:34.893",
            "updated": "2019-04-23T08:05:39.28",
            "availableForCampaign": true,
            "availableForContact": true,
            "contactAssigned": null,
            "guid": "196d9ef3-7f86-418d-8326-b1861561bbc3",
            "isTest": false
        }
    ]
}

Response object parameters
Parameter name Data type Description
mailingListID integer Mailing list ID
name string Mailing list name
description string Mailing list description
created datetime Date of creation
updated datetime Date of last update
availableForCampaign bool Contains info about availability of adding a contact to a mailing list to campaign specified in request parameters.
availableForContact bool Contains info about availability of adding a contact to a mailing list. Contact ID must be specified in request parameters.
contactAssigned datetime Date of assignment a contact to mailing list. Contact ID must be specified in a query string
guid string Mailing list GUID
isTest datetime Is mailing list for testing purposes?
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
}

Request object parameters
Parameter name Data type Parameter type Description
name string required Mailing list name
description string optional Mailing list description
isTest string required Is mailing list for testing purposes?
Response object example
{
    "mailingListId": 11691
}

Response object parameters
Parameter name Data type Description
mailingListID integer ID of created mailing list
PUT - updating an existing mailing list
PUT api/xxxxxx/mailingLists/{mailingListId}

Update of a mailing list where {mailingListId} 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
}

Request object parameters

Tip

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

Response object example

Response body is usually empty. Result of this operation is represented in response code.

DELETE - deleting a mailing list
DELETE api/xxxxxx/mailingLists

Deletes a mailing list from the system.

Available request parameters:
Parameter name Data type Parameter type Description
mailingListIds integer required IDs of mailing list you want to delete, IDs are separated by comma, semicolon or pipe
unassign bool required 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.
Response object example

Response body is usually empty. Result of this operation is represented in response code.

Recipients /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 request 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 email of a wanted recipient (just a bit of email 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)
Response object example
{
    "data": [
        {
            "customColumns": {
                "cc_last_order": "2020-01-09T09:46:17",
                "cc_wk_pane_pani": "Pane Nováku",
                "cc_wk_mily_mila": "Milý pane Nováku"
            },
            "contactId": 7457823,
            "name": "Jan",
            "surname": "Novák",
            "email": "jan@webkomplet.cz",
            "sex": true,
            "mobilePhone": "+420775123456",
            "company": "Webkomplet",
            "title": "Nováku",
            "created": "2018-11-26T06:54:00",
            "userAgent": "",
            "ipAddress": "",
            "lastOpen": null,
            "lastClick": null,
            "dateCreated": null,
            "lastUpdate": "2018-11-26T05:53:32",
            "confirmed": null
        }
    ],
    "totalRecordCount": 1,
    "pageCount": 1
}

Response object parameters
Parameter name Data type Description
customColumns object User columns - Custom recipient data (you can find more here)
contactId integer Contact ID
name string First name
surname string Last name
email string Recipients' email
sex bool Sex (true - male, false - female, null - unspecified)
mobilePhone string Phone number
company string Company name
title string Title
created datetime Date of creation
userAgent string User agent
ipAddress string IP address
lastOpen datetime Date of last opening of any email
lastClick datetime Date of last click on any link
dateCreated datetime Date of creation - deprecated (will by removed)
lastUpdate datetime Date of last update of this recipient
confirmed bool Is recipient confirmed? This attribute was used for GDPR purposes, but it could be used in many other ways.
POST - create a recipient
POST api/xxxxxx/contacts

Creates new recipient. If a recipient with given email already exists it will update an existing one.

Sample JSON object that has to be found in the body request:
{
    "email": "jan@webkomplet.cz",
    "name": "Jan",
    "surname": "Novák",
    "sex": true,
    "title": null,
    "mobilePhone": "775123456",
    "company": "Webkomplet",
    "mailingListIds": [ 1, 2, 3 ],
    "customColumns": {
        "last_order": "2020-01-09T09:46:17"
    }
}

Request object parameters
Parameter name Data type Parameter type Description
email string required email
name string optional First name
surname string optional Last name
sex bool optional Sex (true - male, false - female, null - unspecified)
mobilePhone string optional Phone number
company string optional Company name
mailingListIds array optional Mailing list IDs, where a contact should be assigned
customColumns object optional User columns - Custom recipient data (you can find more here)
Response object example
{
    "contactId": 8368817
}

Response object parameters
Parameter name Data type Description
contactId integer ID of created recipient
PUT - updating a recipient
PUT api/xxxxxx/contacts/{contactId}

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

{
    "email": "jan@webkomplet.cz",
    "name": "Jan",
    "surname": "Novák",
    "sex": true,
    "mobilePhone": "775123456",
    "company": "Webkomplet",
    "title": null,
    "mailingListIds": [ 11611 ],
    "customColumns": {
        "last_order": "2020-01-28T11:46:17"
    }
}

Request object parameters

Tip

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

Response object example

Response body is usually empty. Result of this operation is represented in response code.

DELETE - deleting a recipient
DELETE api/xxxxxx/contacts

Deletes a recipient from the system

Available request parameters:
Parameter name Data type Parameter type Description
contactIds integer required 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
Response object example

Response body is usually empty. Result of this operation is represented in response code.

Warning!

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

POST - import recipients in a bulk
POST api/xxxxxx/contacts/bulk

Executes a bulk import based on shown parameters.

Sample JSON object that has to be found in the body request:
{
    "preImportAction": 1,
    "contactOverwriteMode": 1,
    "mailingListIds": [ 1, 2, 3 ],
    "contacts": [
        {
            "name": "Jan",
            "surname": "Novák",
            "title": "Dear Mr.",
            "email": "jan@webkomplet.cz",
            "sex": true,
            "company": "Webkomplet",
            "customData": null,
            "customColumns": {
                "last_order": "2020-01-28T11:46:17"
            }
        },
        {
            "name": "Jana",
            "surname": "Nováková",
            "title": "Dear Mrs.",
            "email": "jana@webkomplet.cz",
            "sex": false,
            "company": "Webkomplet",
            "customData": null,
            "customColumns": {}
        },
        {
            "email": "martin@webkomplet.cz"
        }
    ]
}

Request object parameters
Parameter name Data type Parameter type Description
preImportAction int required
  • 1 - add new records, ignore existing items (existing records, that belongs to 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 from system during import. All imported records will be added to the mailing list).
contactOverwriteMode int required
  • 1 - merge existing record values with imported
  • 2 - overwrite existing record values with imported
  • 3 - skip existing records
mailingListIds array optional Mailing list IDs, where a contact should be assigned
contacts array required Recipients to be imported. Data structure of array item should match common object for insert / update a recipient.
Response object example
{
    "data": {
        "operationId": "fde11e2f-3d10-4fe5-9f3f-6b9390fbar18"
    }
}

Response object parameters
Parameter name Data type Description
operationId integer GUID of bulk import operation

Duration of bulk import

Bulk import of recipients could take some time depending on the number of inserted items. You can find a state of a bulk import process using /contacts/getBulkInfo endpoint.

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

Returns information about the state of the import.

Available request parameters:
Parameter name Data type Parameter type Description
operationId GUID required GUID of bulk import operation
Response object example
{
    "data": {
      "status": "SuccessfulyFinished",
      "errors": null,
      "errorMessage": null
    }
}

Response object parameters
Parameter name Data type Description
status string Status of import. It should be:
  • Composing
  • Queued
  • Processing
  • SuccessfulyFinished
  • Error
errors string Errors during an import
errorMessage string Outer error message
GET - getting recipients history
GET api/xxxxxx/contacts/getContactActivity

Return history of actions of recipient, like mass email sending, transactional email sending, link click etc.

Available request parameters:
Parameter name Data type Parameter type Description
email string required email of a recipient you want to get history
Response object example

{
    "data": [
      {
        "actionTypeId": 2,
        "created": "2021-01-22T11:06:00",
        "mailId": 351878868,
        "openId": 41737910,
        "clickId": null,
        "tranMailId": null,
        "tranOpenId": null,
        "tranClickId": null,
        "cfssId": null,
        "orderId": null,
        "cartItemId": null,
        "email": "martin@webkomplet.cz",
        "generatorExecutionId": 96052,
        "bounceTypeId": null,
        "campaignId": 31567
      }
    ]
}

Response object parameters
Parameter name Data type Description
actionTypeId int
  • 1 - mass email sent
  • 2 - mass email opened
  • 3 - mass email clicked
  • 4 - transactional email sent
  • 5 - transactional email opened
  • 6 - transactional email clicked
  • 7 - flow script started
  • 8 - email unsubscribe
  • 9 - email bounce
created datetime Date and time of action
mailId int Mass email ID
openId int Mass email open ID
clickId int Mass email click ID
tranMailId int Transactional email ID
tranOpenId int Transactional email open ID
tranClickId int Transactional email click ID
cfssId int Contact flow script state ID
orderId int Order ID
cartItemId int Cart item id
email string Recipients' email
generatorExecutionId int Generator execution ID
bounceTypeId int
  • 1 - hard bounce
  • 2 - soft bounce
campaignId int Campaign ID

Subscribe requests /subscribeContacts

POST - creates a new subscribe request for recipient
POST api/xxxxxx/subscribeContacts

Creates a new subscribe request for the recipient. JSON object in body could contain all properties mentioned in contacts POST method, but moreover, it's necessary to add property "dispatcherId", which contains information about dispatcher selected for processing this subscribe request.

Sample JSON object that has to be found in the body request:
{
    "email": "jan@webkomplet.cz",
    "name": "Jan",
    "surname": "Novák",
    "sex": true,
    "title": null,
    "mobilePhone": "775123456",
    "company": "Webkomplet",
    "mailingListIds": [ 1, 2, 3 ],
    "customColumns": {},
    "dispatcherId": 1234
}

Request object parameters
Parameter name Data type Parameter type Description
email string required email
name string optional First name
surname string optional Last name
sex bool optional Sex (true - male, false - female, null - unspecified)
mobilePhone string optional Phone number
company string optional Company name
mailingListIds array optional Mailing list IDs, where a contact should be assigned
customColumns object optional User columns - Custom recipient data (you can find more here)
dispatcherId integer required Domain redirect ID (for more information take a look here)
Response object example
{
    "subscribeRequestId": 81911
}

Response object parameters
Parameter name Data type Description
subscribeRequestId integer ID of created subscribe request

Templates /templates

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

Returns available templates in your account.

Available request 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)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
            "templateId": 82409,
            "created": "2019-05-14T14:24:00",
            "updated": "2019-05-20T12:41:29.42",
            "name": "Template name",
            "subject": "Subject",
            "isCampaignBound": false,
            "isHtml": true,
            "type": 2,
            "body": "",
            "bodyAlternative": null,
            "templateThumbnailUrl": "https://admin.mail-komplet.cz//api/xtjv3opyJDpfJbMkv2ThmRgsSCdVwPmr/thumbnail/?templateId=82409&t=37",
            "useWysiwyg": true
        }
    ]
}

Response object parameters
Parameter name Data type Description
templateId integer Template ID
created datetime Date of creation
updated datetime Date of last update
name string Name
subject string Subject
isCampaignBound bool Is template bound to any campaign?
isHtml bool Is template HTML?
type integer Type of template:
  • 1 - WYSIWYG editor template
  • 2 - Clever editor template
  • 3 - SMS template
body string Body
bodyAlternative string Alternative body, e.g. for clients, which do not support HTML
templateThumbnailUrl string URL of a thumbnail
useWysiwyg boolean

Campaigns /campaigns

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

Returns available campaigns in your account.

Available request parameters:
Parameter name Data type Parameter type Description
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)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
            "campaignId": 26719,
            "templateId": 91592,
            "name": "Campaign name",
            "description": "Campaign description",
            "insertTrackingImage": true,
            "ignoreExcludeList": false,
            "useWysiwyg": true,
            "autoLinkTracking": true,
            "status": 4,
            "schedulerId": null,
            "nextRunTime": null,
            "mailFromDisplayName": "Webkomplet",
            "mailFromAddress": "info@webkomplet.cz",
            "replyToDisplayName": null,
            "replyToAddress": null
        }
    ]
}

Response object parameters
Parameter name Data type Description
campaignId integer Campaign ID
templateId integer Template ID
name string Name
description string Description
insertTrackingImage bool Track openings of messages?
ignoreExcludeList bool Send messages to unsubscribed recipients?
useWysiwyg boolean
autoLinkTracking boolean Track link clicks?
status integer State of campaign:
  • 1 - Canceled - Campaign was canceled
  • 2 - Preparation - Campaign is being set
  • 3 - FinishedWithUnpaid - Campaign is finished but some emails were not sent, because there was not enough credit.
  • 4 - FinishedAll - Campaign is finished and all emails were sent.
  • 5 - Active - Campaign is being sent.
  • 6 - Scheduled - Campaign is scheduled to be sent.
  • 7 - Evaluation - Campaign has some distributions that are going to be evaluated.
schedulerId integer Scheduler ID
nextRunTime dateTime Date of scheduled distribution
mailFromDisplayName string From name to display
mailFromAddress string From email to display
replyToDisplayName string Reply to name
replyToAddress string Reply to email
GET - getting campaign detail by ID
GET api/xxxxxx/campaigns

Returns campaign detail for given campaign ID.

Available request parameters:
Parameter name Data type Parameter type Description
campaignId integer required ID of a campaign you want to get
Response object example
{
    "data": {
      "campaignId": 30264,
      "campaignGroupId": null,
      "name": "odhlaseni 2",
      "description": null,
      "webTrackParam": null,
      "senderDisplayName": "Sender name",
      "senderEmail": "sender@webkomplet.cz",
      "mailFromDisplayName": "Mail from name",
      "mailFromAddress": "mail.from@webkomplet.cz",
      "replyToDisplayName": null,
      "replyToAddress": null,
      "insertTrackingImage": true,
      "ignoreExcludeList": false,
      "autoLinkTracking": true,
      "unsubscribeTypeId": 2,
      "dispatcherId": 1858,
      "templateId": 103111,
      "useWysiwyg": true,
      "campaignType": 1
    }
}

Response object parameters
Parameter name Data type Description
campaignGroupId integer Campaign group ID
name string Name
description string Description
webTrackParam string Link tagging (like utm_source=newsletter&utm_medium=email)
senderEmail string Sender email
mailFromDisplayName string From name to display
mailFromAddress string From email to display
replyToDisplayName string Reply to name
replyToAddress string Reply to email
insertTrackingImage bool Track openings of messages?
ignoreExcludeList bool Send messages to unsubscribed recipients?
autoLinkTracking boolean Track link clicks?
unsubscribeTypeId integer Unsubscribe type ID:
  • 1 - unsubscribe from the campaign
  • 2 - unsubscribe from all mailing lists assigned to the campaign
  • 3 - mass unsubscribe (recipients will be unsubscribed globally)
dispatcherId integer Dispatcher ID
templateId integer Template ID
useWysiwyg boolean
status integer State of campaign:
  • 1 - Canceled - Campaign was canceled
  • 2 - Preparation - Campaign is being set
  • 3 - FinishedWithUnpaid - Campaign is finished but some emails were not sent, because there was not enough credit.
  • 4 - FinishedAll - Campaign is finished and all emails were sent.
  • 5 - Active - Campaign is being sent.
  • 6 - Scheduled - Campaign is scheduled to be sent.
  • 7 - Evaluation - Campaign has some distributions that are going to be evaluated.
schedulerId integer Scheduler ID
nextRunTime dateTime Date of scheduled distribution
campaignType integer Campaign type:
  • 1 - Mass email campaign
  • 2 - Mass SMS campaign
  • 3 - Transactional email campaign
  • 4 - A/B testing campaign
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:
{ 
    "templateId": 95821,
    "dispatcherId": 1811,
    "unsubscribeTypeId": 2, 
    "ignoreExcludeList": false,
    "autoLinkTracking": true,
    "name": "New campaign",
    "description": "Short description campaign",
    "webTrackParam": "null",
    "mailFromDisplayName": "Webkomplet",
    "mailFromAddress": "info@webkomplet.cz",
    "insertTrackingImage": true
}

Request object parameters
Parameter name Data type Parameter type Description
templateId integer optional Template ID
dispatcherId integer optional Domain redirect ID
unsubscribeTypeId integer required Unsubscribe type:
  • 1 - unsubscribe from the campaign
  • 2 - unsubscribe from all mailing lists assigned to the campaign
  • 3 - mass unsubscribe (recipients will be unsubscribed globally)
ignoreExcludeList boolean optional Send messages to unsubscribed recipients? Default set to false.
autoLinkTracking boolean optional Track link clicks automatically?
name string required Name
description string optional Description
webTrackParam string optional Link tagging (like utm_source=newsletter&utm_medium=email)
mailFromDisplayName string optional Name of sender to display
mailFromAddress string required email of sender to display
insertTrackingImage boolean optional Insert tracking image?
Response object example
{
    "campaignId": 28494
}

Response object parameters
Parameter name Data type Description
campaignId integer ID of created campaign
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:
{ 
    "templateId": 95821,
    "dispatcherId": 1811,
    "unsubscribeTypeId": 2, 
    "ignoreExcludeList": false,
    "autoLinkTracking": true,
    "name": "New campaign",
    "description": "Short description campaign",
    "webTrackParam": "null",
    "mailFromDisplayName": "Webkomplet",
    "mailFromAddress": "info@webkomplet.cz",
    "insertTrackingImage": true
}

Request object parameters

Tip

It is possible to use the same properties as in the POST method in JSON when updating an existing campaigns. Properties that are not found in the JSON object will not be updated.

Response object example

Response body is usually empty. Result of this operation is represented in response code.

DELETE - deleting a campaign
DELETE api/xxxxxx/campaigns

Deletes a campaign based on an ID

Available request parameters:
Parameter name Data type Parameter type Description
id integer required ID of a campaign you want to delete
Response object example

Response body is usually empty. Result of this operation is represented in response code.

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 request 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)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
            "dispatcherId": 1612,
            "status": 2,
            "genericDispatcherId": 1,
            "genericDispatcherDomain": "m1.mail-komplet.cz",
            "name": "",
            "title": "http://m1.mail-komplet.cz/m/",
            "url": "http://m1.mail-komplet.cz/m/",
            "useHttps": false,
            "subscribeReturnUrl": "",
            "unsubscribeReturnUrl": "",
            "useSubscribeAuthentication": false,
            "sendSubscribeAuthenticationFormReturnUrl": "",
            "subscribeCampaignId": 26185,
            "useSendWelcomeMail": false,
            "welcomeCampaignId": 26185,
            "useUnsubscribeAuthentication": false,
            "unsubscribeAuthenticationReturnUrl": "",
            "sendUnsubscribeAuthenticationFormReturnUrl": "",
            "useFeedback": false,
            "feedback": null,
            "feedbackUrl": null,
            "domainRewrite": "",
            "cnameRecord": null,
            "useIdentifier": false
        }
    ]
}

Response object parameters
Parameter name Data type Description
dispatcherId integer Dispatcher (domain redirect) ID
status integer Dispatcher state:
  • 0 - Not verified - dispatcher needs to be verified and activated
  • 1 - Dns verified - dispatcher was verified and needs to be activated
  • 2 - Active - dispatcher was verified and activated
genericDispatcherId integer Generic dispatcher ID
genericDispatcherDomain string Generic dispatcher domain
name string Name
title string Title
url string Url
useHttps boolean Use https?
subscribeReturnUrl string redirect URL after subscription
unsubscribeReturnUrl string redirect URL after unsubscription
useSubscribeAuthentication boolean Use subscribe verification?
sendSubscribeAuthenticationFormReturnUrl string return URL address after sending subscribe confirmation form
subscribeCampaignId integer ID of campaign used to send subscribe confirmation link
useSendWelcomeMail boolean Send welcome email?
welcomeCampaignId boolean ID of campaign used to send welcome email
useUnsubscribeAuthentication boolean Use unsubscribe verification?
unsubscribeAuthenticationReturnUrl string return URL address after sending unsubscribe request
sendUnsubscribeAuthenticationFormReturnUrl string return URL address after sending unsubscribe request form
useFeedback boolean Use unsubscribe feedback?
feedback string Feedback info
feedbackUrl string Feedback URL
domainRewrite string Own domain
cnameRecord string CNAME record
useIdentifier boolean Use identifier

Marketing emails /marketingEmails

GET - returns all marketing emails for distribution
GET api/xxxxxx/marketing

Returns a list of marketing emails which are available based on chosen parameters.

Available request parameters:
Parameter name Data type Parameter type Description
generatorExecutionId integer required ID of a generator execution
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
            "emailId": 1834,
            "campaignId": 171477,
            "generatorExecutionId": 171477,
            "created": "2017-05-11T18:11:39",
            "sent": "2017-05-11T18:11:47",
            "delivered": "2017-05-11T18:11:47",
            "fromAddress": "jan@webkomplet.cz",
            "toAddress": "jana@webkomplet.cz",
            "guid": "93d4037e-6436-e711-80b8-0015172840a0",
            "variant": 0,
            "metadata": null,
        }
    ],
    "totalRecordCount": 1
}

Response object parameters
Parameter name Data type Description
emailId integer Marketing email ID
campaignId integer Campaign ID
generatorExecutionId integer Generator execution ID - ID of distribution
created datetime Date of creation
sent datetime Date of sending
delivered datetime Date of delivery
fromAddress string Email address of sender
toAddress string Email of recipient
toDisplayName string Name of recipient
guid string Transactional email GUID
GET - returns all opens of marketing emails for distribution
GET api/xxxxxx/marketingEmails/opens

Returns all opens actions of marketing emails by distribution

Available request parameters:
Parameter name Data type Parameter type Description
generatorExecutionId integer required ID of a generator execution
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
        "openId": 12589,
        "emailId": 432642,
        "campaignId": 171477,
        "generatorExecutionId": 171477,
        "created": "2020-01-31T11:05:20",
        "toAddress": "jan@webkomplet.cz",
        "ipAddress": "80.95.120.66",
        "userAgent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)"
        "variant": "0"
        }
    ]
}

Response object parameters
Parameter name Data type Description
openId integer Open record ID
emailId integer Marketing email ID
campaignId integer Campaign ID
generatorExecutionId integer Generator execution ID - ID of distribution
created datetime Date of opening
toAddress string Email address of recipient
ipAddress string IP address of device, where the email was opened
userAgent string User agent of application, where the email was opened
GET - returns all clicks of marketing emails for distribution
GET api/xxxxxx/marketingEmails/clicks

Returns all clicks actions of marketing emails by distribution

Available request parameters:
Parameter name Data type Parameter type Description
generatorExecutionId integer required ID of a generator execution
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
Response object example
{
    "totalRecordCount": 2,
    "pageCount": 1,
    "data": [
        {
            "clickId": 48024,
            "emailId": 417994,
            "campaignId": 171477,
            "generatorExecutionId": 171477,
            "created": "2020-01-03T14:38:51",
            "toAddress": "jan@webkomplet.cz",
            "linkUrl": "https://www.nejaka-url.cz/",
            "linkIndex": 11,
            "ipAddress": "80.95.120.66",
            "userAgent": "PostmanRuntime/7.21.0"
        }
    ]
}

Response object parameters
Parameter name Data type Description
clickId integer Click record ID
emailId integer Marketing email ID
campaignId integer Campaign ID
generatorExecutionId integer Generator execution ID - ID of distribution
created datetime Date of clicking
toAddress string Email address of recipient
ipAddress string IP address of device, where the email was clicked
userAgent string User agent of application, where the email was clicked
linkUrl string Original URL address
linkIndex string Index position URL in email body

Transactional emails /transactionalEmails

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

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

Available request parameters:
Parameter name Data type Parameter type Description
emailId integer optional ID of a transactional email
createdFrom datetime optional Date of creation from
createdTo datetime optional Date of creation to
toAddress string optional email of a recipient (part of the email will also work)
state integer optional State of a transactional email:
  • 1 - Active
  • 2 - Finished successfully
  • 3 - Finished with error
  • 4 - Canceled
isOpened bool optional Select only opened emails?
isClicked bool optional Select only clicked emails?
guid GUID optional Transactional email GUID
tags Tags optional Tags
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
        {
            "emailId": 1834,
            "queuePriority": 3,
            "phase": 2,
            "state": 2,
            "created": "2017-05-11T18:11:39",
            "sendAt": "2017-05-11T18:11:39",
            "sent": "2017-05-11T18:11:47",
            "delivered": null,
            "fromAddress": "jan@webkomplet.cz",
            "fromDisplayName": "Webkomplet",
            "toAddress": "jana@webkomplet.cz",
            "toDisplayName": null,
            "subject": "Subject",
            "bodyFormat": false,
            "emlSize": 7790,
            "result": null,
            "opened": null,
            "clicked": null,
            "softBounced": null,
            "hardBounced": null,
            "isBulk": false,
            "unsubscribed": null,
            "reportedAsSpam": null,
            "guid": "93d4037e-6436-e711-80b8-0015172840a0",
            "tags": null,
            "isClicked": 0,
            "isOpened": 0
        }
    ],
    "totalRecordCount": 1
}

Response object parameters
Parameter name Data type Description
emailId integer Transactional email ID
queuePriority integer Queue priority:
  • 1 - Urgent
  • 2 - High
  • 3 - Normal
  • 4 - Below normal
  • 5 - Low
phase integer Phase of transmitting:
  • 0 - Message is being composed
  • 1 - Message is being transmitted to our relay server
  • 2 - Message is being transmitted to the target mail server
state integer State of a transactional email:
  • 1 - Active
  • 2 - Finished successfully
  • 3 - Finished with error
  • 4 - Canceled
created datetime Date of creation
sendAt datetime Scheduled date of sending
sent datetime Date of sending
delivered datetime Date of delivery
fromAddress string email address of sender
fromDisplayName string Name of sender
toAddress string email of recipient
toDisplayName string Name of recipient
subject string Subject of an email
bodyFormat boolean Format of an email
  • false - text
  • true - html
emlSize integer Size of an eml
result string In case of any error you can find here detail info
opened datetime When the email was opened
clicked datetime When some link in the email was clicked
softBounced boolean Was email marked as soft bounce?
hardBounced boolean Was email marked as hard bounce?
isBulk boolean Is bulk email?
unsubscribed datetime Date of unsubscribe request
reportedAsSpam datetime Is reported as spam?
guid string Transactional email GUID
tags string Tags
isClicked boolean Was some link in the email clicked?
isOpened boolean Was this email opened?
POST - sending a transactional email
POST api/xxxxxx/transactionalEmails

Sending a transactional email.

Sample JSON object that has to be found in the body request:
{
    "email": {
        "fromAddress": "jan@webkomplet.cz",
        "fromDisplayName": "Mail Komplet",
        "to": [{ 
                "address": "jana@webkomplet.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
    }
}

Request object parameters
Parameter name Data type Parameter type Description
fromAddress string required email address of sender
fromDisplayName string optional Name of sender
to array required List of recipients
to.address string required Email address of recipient
to.variables array optional List of variables, used in email body. It has higher priority than "variables" parameter in root element.
subject string required Subject
bodyHtml string optional emails' body in HTML format
bodyText string optional emails' body in text format
attachments array optional List of attachments
variables object optional Variables
trackOpens boolean optional Track opens of this email?
trackClicks boolean optional Track clicks on links in this email?

Tip

We recommend to create campaign (via API or in system) and use its ID insead of sending whole email content repeatedly. You can get campaign ID calling /campaigns endpoint. Attachements have to be enabled in system.

Response object example
{
     "data": [
        {
            "email": "jan@webkomplet.cz",
            "guid": "2a84821c-2344-ea11-aeff-00155d012d0b"
        }
    ]
}

Response object parameters
Parameter name Data type Description
email string Email address of recipient
guid string Transactional email GUID
GET - getting all records about the open rate of transactional emails in your account
GET api/xxxxxx/transactionalEmails/opens

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

Available request parameters:
Parameter name Data type Parameter type Description
openId integer optional ID of an transactional email's open rate
emailId integer optional ID of a transactional email
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)
Response object example
{
    "totalRecordCount": 1,
    "pageCount": 1,
    "data": [
      {
        "openId": 171477,
        "emailId": 432642,
        "created": "2020-01-31T11:05:20",
        "toAddress": "jan@webkomplet.cz",
        "ipAddress": "80.95.120.66",
        "userAgent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)"
      }
    ]
}

Response object parameters
Parameter name Data type Description
openId integer Open record ID
emailId integer Transactional email ID
created datetime Date of opening
toAddress string Email address of recipient
ipAddress string IP address of device, where the email was opened
userAgent string User agent of application, where the email was opened
GET - getting records about clicks in transactional emails in your account
GET api/xxxxxx/transactionalEmails/clicks

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

Available request parameters:
Parameter name Data type Parameter type Description
clickId integer optional ID of a record about a clicktrough in a transactional email
emailId integer optional ID of a transactional email
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)
Response object example
{
    "totalRecordCount": 2,
    "pageCount": 1,
    "data": [
        {
            "clickId": 48024,
            "emailId": 417994,
            "created": "2020-01-03T14:38:51",
            "toAddress": "jan@webkomplet.cz",
            "linkUrl": "https://www.nejaka-url.cz/",
            "linkIndex": 11,
            "ipAddress": "80.95.120.66",
            "userAgent": "PostmanRuntime/7.21.0"
        },
        {
            "clickId": 48023,
            "emailId": 417994,
            "created": "2020-01-03T14:37:07",
            "toAddress": "jana@webkomplet.cz",
            "linkUrl": "https://www.nejaka-url.cz/",
            "linkIndex": 11,
            "ipAddress": "80.95.120.66",
            "userAgent": "PostmanRuntime/7.21.0"
        }
    ]
}

Response object parameters
Parameter name Data type Description
clickId integer Click record ID
emailId integer Transactional email ID
created datetime Date of click
toAddress string Email address of recipient
linkUrl string URL of clicked link
linkIndex integer index of clicked link in transactional emails' body
ipAddress string IP address of device, where the email was clicked
userAgent string User agent of application, where the email was clicked
GET - getting bounce info for given transactional email
GET api/xxxxxx/transactionalEmails/bounceInfo

Returns an object with bounce info for transactional email, specified via emailId

Available request parameters:
Parameter name Data type Parameter type Description
emailId integer required ID of an transactional email
Response object example
{
    "data": [
        {
            "deliveryInfoId": 11112014,
            "guid": "816560bc-dfed-ea11-af13-00154d012d0b",
            "emailId": 622620,
            "email": "bounce@webkomplet.cz",
            "created": "2018-09-03T16:20:03",
            "dsnInfo": "smtp; 550-5.1.1 The email account that you tried to reach does not exist. Please try Remote-MTA: dns; Last-Attempt-Date: Thu, 03 Sep 2018 14:20:02 +0200",
            "dsnStatus": "5.0.0"
        }
    ]
}

Response object parameters
Parameter name Data type Description
deliveryInfoId integer Delivery info record ID
guid GUID Transactional email GUID
emailId integer Transactional email ID
email string Email address of recipient
created datetime Date of delivery info creation
dsnInfo string Delivery status notification description
dsnStatus string Delivery status notification status code

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 request 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 work)
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)
Response object example
{
    "data": [
        {
            "smsId": 59451,
            "state": 3,
            "queuePriority": 5,
            "to": "+420775123456",
            "created": "2020-01-31T14:06:25",
            "due": "2020-01-31T14:06:25",
            "sent": "2020-01-31T14:06:31",
            "received": "2020-01-31T14:06:34",
            "text": "Hello, I am transactional sms",
            "smsGroupId": null,
            "guid": "cff71b8a-2f7a-4b3e-949f-075e4349efa6",
            "price": 0.8
        }
    ],
    "totalRecordCount": 1
}

Response object parameters
Parameter name Data type Description
smsId integer SMS ID
state integer State of a transactional SMS:
  • 0 - Composing
  • 1 - Batch Transmission In Progress
  • 2 - Transaction Transmission In Progress
  • 3 - Finished Successfuly
  • 4 - Canceled
  • 5 - Finished With Error
  • 6 - Unpaid
queuePriority integer Queue priority:
  • 1 - Urgent
  • 2 - High
  • 3 - Normal
  • 4 - Below normal
  • 5 - Low
to string Recipients' phone number
created datetime Date of creation
due datetime Date of scheduled sending
sent datetime Date of sending
received datetime Date of receving
text string Message content
smsGroupId integer SMS group ID
guid integer Transactional SMS GUID
price decimal Price
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": "+4207752123456"
            }
        ],
        "text": "Your first SMS message.",
        "priority" : 5,
        "groupId": 1      
    }
}

Request object parameters
Parameter name Data type Parameter type Description
to array required List of recipients
to.number string required Phone number of recipient
text string required Transactional SMS content
priority integer optional
  • 1 - Urgent
  • 2 - High
  • 3 - Normal
  • 4 - Below normal
  • 5 - Low
groupId integer optional Transactional SMS group ID
Response object example
{
    "data": [
        {
            "number": "+420775123456",
            "guid": "34851b54-d56b-4199-aac2-4f71c5bcc6a7"
        }
    ]
}

Response object parameters
Parameter name Data type Description
number string Recipients' phone number
number string Recipients' phone number
guid string Transactional SMS GUID

Distributions /generatorExecutions

GET - getting all distributions
GET api/xxxxxx/generatorExecutions

Returns distributions which are available based on chosen parameters.

Available request 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)
Response object example
{
    "data": [
        {
            "campaignName": "Test",
            "campaignId": 20189,
            "campaignType": 1,
            "generatorExecutionId": 81326,
            "status": 1,
            "phase": 4,
            "spentCredits": 0,
            "totalCount": 0,
            "clickCount": 0,
            "clickCountTotal": 0,
            "openCount": 0,
            "openCountTotal": 0,
            "unsubscribeCount": 0,
            "openRatio": 0,
            "clickRatio": 0,
            "unsubscribeRatio": 0,
            "created": "2020-02-03T11:00:10.167",
            "executed": "2020-02-03T11:01:42.077",
            "isTesting": false,
            "softBounceCount": 0,
            "hardBounceCount": 0,
            "bounceCount": 0,
            "softBounceRatio": 0,
            "hardBounceRatio": 0,
            "bounceRatio": 0,
            "deliveryRatio": 0,
            "deliveryCount": 0,
            "smsPrice": 0,
            "groupName": "",
            "groupColor": "",
            "campaignGroupId": null
        }
    ],
    "totalRecordCount": 1,
    "pageCount": 1
}

Response object parameters
Parameter name Data type Description
campaignName string Campaign name
campaignId integer Campaign ID
campaignType integer Campaign type:
  • 1 - Mass email campaign
  • 2 - Mass SMS campaign
  • 3 - Transactional email campaign
  • 4 - A/B testing campaign
generatorExecutionId integer Generator execution ID
status integer State:
  • 1 - Generation is in progress
  • 2 - Generation was paused
  • 3 - Generation was cancelled
  • 4 - Error happened during generation
phase integer Phase:
  • 1 - Waiting to be executed
  • 2 - Generating
  • 3 - Sending
  • 4 - Finished all
  • 5 - Finished with unpaid
spentCredits integer Credits spent
totalCount integer Total count of messages
clickCount integer Clicked through emails (multiple clicks in one email are counted as one item)
clickCountTotal integer Total link clicks (multiple clicks in one email are counted separately)
openCount integer Opened emails (multiple opens of one email are counted as one email)
openCountTotal integer Opens of emails (multiple opens of one email are counted separately)
unsubscribeCount integer Count of unsubscribes
openRatio decimal Open ratio (openCount / deliveryCount)
clickRatio decimal Click ratio (clickCount / deliveryCount)
unsubscribeRatio decimal Unsubscribe ratio (unsubscribeCount / deliveryCount)
created datetime Date of creation
executed datetime Date of execution
isTesting boolean Is testing?
softBounceCount integer Soft bounces count
hardBounceCount integer Hard bounces count
bounceCount integer Bounces count
softBounceRatio decimal Soft bounce ratio (softBounceCount / totalCount)
hardBounceRatio decimal Soft bounce ratio (hardBounceCount / totalCount)
bounceRatio decimal Soft bounce ratio (bounceCount / totalCount)
deliveryCount integer Successfully delivered messages count
deliveryRatio decimal Delivery ration (deliveryCount / totalCount)
smsPrice decimal SMS price
groupName string Campaign group name
groupColor string Campaign group color
campaignGroupId integer Campaign group ID

User columns /customColumns

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

Returns user columns which are available based on chosen parameters.

Available request 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)
Response object example
{
    "data": [
        {
            "customColumnId": 4370,
            "customColumnTypeId": 1,
            "customColumnGroupId": null,
            "dataTypeId": 1,
            "name": "wholename",
            "caption": "caption",
            "description": "contains name, surname together",
            "defaultValue": "",
            "minValue": null,
            "maxValue": null,
            "required": false,
            "unique": false,
            "disabled": false,
            "precision": null,
            "system": false,
            "order": 11,
            "deleted": null,
            "size": null,
            "originalName": "cc_wholename"
        }
    ],
    "totalRecordCount": 1,
    "pageCount": 1
}

Response object parameters
Parameter name Data type Description
customColumnId integer Custom column ID
customColumnTypeId integer Custom column type ID:
  • 1 - Contact custom column
customColumnGroupId integer Custom column group ID
dataTypeId integer Data type ID:
  • 1 - Text (string)
  • 2 - Number
  • 3 - Yes/no (boolean)
  • 4 - Date and time (DateTime)
  • 5 - Date (Date)
  • 6 - Time (Time)
  • 7 - List of options (Select)
name string Name
caption string Caption
description string Description
defaultValue string Default value used when creating new row
minValue object Minimal allowed value
maxValue object Maximal allowed value
required boolean Defines if field/column is required
unique boolean Defines if field/column value is unique
disabled boolean Defines if field/column is temporarily disabled by user
precision byte Defines precision of field/column, when its datatype is numeric
system boolean Defines if field/column is used for system purposes and its manipulation from user-side is limited
order integer Defines order of field/column in user interface
deleted datetime Date when field/column was deleted
size integer Size
originalName string Original name
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": "myUserColumn",
    "caption": "caption",
    "description": "description",
    "defaultValue": 1,
    "minValue": 1,
    "maxValue": 1,
    "required": false,
    "unique": false,
    "disabled": false,
    "precision": null,
    "order": null
}

Request object parameters
Parameter name Data type Parameter type Description
dataTypeId integer required Data type ID:
  • 1 - Text (string)
  • 2 - Number
  • 3 - Yes/no (boolean)
  • 4 - Date and time (DateTime)
  • 5 - Date (Date)
  • 6 - Time (Time)
  • 7 - List of options (Select)
name string required Name
caption string optional Caption
description string optional Description
defaultValue string optional Default value used when creating new row
minValue object optional Minimal allowed value
maxValue object optional Maximal allowed value
required boolean optional Defines if field/column is required
unique boolean optional Defines if field/column value is unique
disabled boolean optional Defines if field/column is temporarily disabled by user
precision byte optional Defines precision of field/column, when its datatype is numeric
order integer optional Defines order of field/column in user interface
Response object example
{
    "customColumnId": 17267
}

Response object parameters
Parameter name Data type Description
customColumnId integer Custom column ID
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": "myUserColumn",
     "caption": "caption",
     "description": "description",
     "defaultValue": 1,
     "minValue": 1,
     "maxValue": 1,
     "required": false,
     "unique": false,
     "disabled": false,
     "precision": null,
     "order": null
 }

Tip

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

Response object example

Response body is usually empty. Result of this operation is represented in response code.

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

Deletes a user column from your account

Available request parameters:
Parameter name Data type Parameter type Description
id integer required ID of a user column you want to delete
Response object example

Response body is usually empty. Result of this operation is represented in response code.

Unsubscribed recipients /excludeLists

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

Returns unsubscribed recipients which are available based on chosen parameters.

Available request 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)
Response object example
{
    "data": [
        {
            "excludeListId": 161250,
            "mailingListId": null,
            "campaignId": null,
            "email": "jan@webkomplet.cz",
            "createdDate": "2018-04-05T19:53:00",
            "reason": null,
            "sourceGeneratorExecutionId": 4393,
            "origin": 1,
            "reasonId": 1,
            "bounceTypeId": null,
            "deliveryInfoErrorCode": null,
            "validFrom": null,
            "validTo": null,
            "variant": 0,
            "sourceCampaignId": null,
            "sourceTransactionalEmailId": null,
            "sourceMarketingEmailId": null,
            "mailingListName": null,
            "campaignName": null
        }
    ],
    "totalRecordCount": 1,
    "pageCount": 1
}

Response object parameters
Parameter name Data type Description
excludeListId integer Exclude list item ID
mailingListId integer Mailing list ID
campaignId integer Campaign ID
email string Email of unsubscribe recipient
createdDate datetime Date of creation
reason string Reason of unsubscription
sourceGeneratorExecutionId integer Source generator execution ID
origin integer Origin:
  • 1 - Exclude list record was inserted through submission of unsubscribe form
  • 2 - Exclude list record was inserted through administration
  • 3 - Exclude list record was inserted by bounce cleaning mechanism
  • 4 - Exclude list record was inserted by unsubcribe messages processing
reasonId integer Reason ID:
  • 1 - Exclude list record was inserted because user does not want emails
  • 2 - Exclude list record was inserted because recipient's mailbox is undeliverable
bounceTypeId integer Bounce type ID:
  • 1 - HardBounce
  • 2 - SoftBounce
deliveryInfoErrorCode string Delivery info error code
validFrom datetime Begin date of unsubscription
validTo datetime End date of unsubscription
variant integer Variant of email (when A/B campaign)
sourceCampaignId integer ID of source campaign, where unsubscription occured
sourceTransactionalEmailId integer ID of source transactional email, where unsubscription occured
sourceMarketingEmailId integer ID of source mass email, where unsubscription occured
mailingListName string Mailing list name
campaignName string Campaign name
POST - unsubscribing a recipient
POST api/xxxxxx/excludeLists

Unsubscribes a recipient based on an email 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"
}

Request object parameters
Parameter name Data type Parameter type Description
mailingListsId integer optional Mailing list ID
campaignId integer optional Campaign description
generatorExecutionId integer optional Generator execution ID
email string required email
reason string optional Reason
Response object example

Response body is usually empty. Result of this operation is represented in response code.

DELETE - deleting an unsubscribed recipient
DELETE api/xxxxxx/excludeLists

Deletes a record about unsubscribing.

Available request parameters:
Parameter name Data type Parameter type Description
id integer required ID of a unsubscribed recipient's record (exclude list item)
Response object example

Response body is usually empty. Result of this operation is represented in response code.

Sale coupons groups /saleCouponGroups

GET - getting all sale coupons groups
GET api/xxxxxx/saleCouponGroups

Returns sale coupon groups.

Response object example
{
  "data": [
    {
      "couponGroupId": 2,
      "name": "prvni",
      "color": "#3E50B4"
    }
  ],
  "totalRecordCount": 1
}

Response object parameters
Parameter name Data type Description
couponGroupId integer Sale coupon group ID
name string Sale coupon group name
color string Sale coupon groups flag color
POST - creating a new sale coupons group
POST api/xxxxxx/saleCouponGroups

Creates a new sale coupon group.

Sample JSON object that has to be found in the body request:
{
  "color": "#3E50B4",
  "name": "treti"
}

Request object parameters
Parameter name Data type Parameter type Description
color string required Sale coupon groups flag color
name string required Name
Response object example
{
  "couponGroupId": 4
}

Response object parameters
Parameter name Data type Description
couponGroupId integer Sale coupon group ID
POST - updating sale coupons group
POST api/xxxxxx/saleCouponGroups

Updates a sale coupons group.

Sample JSON object that has to be found in the body request:
{
  "couponGroupId": 4,
  "name": "treti edit",
  "color": "#3E50B4"
}

Response object example
{
  "couponGroupId": 4
}

Response object parameters
Parameter name Data type Description
couponGroupId integer Sale coupon group ID
DELETE - deleting a sale coupons group
DELETE api/xxxxxx/saleCouponGroups

Deletes a sale coupons group from your account

Available request parameters:
Parameter name Data type Parameter type Description
id integer required ID of a sale coupon group you want to delete
Response object example

Response body is usually empty. Result of this operation is represented in response code.

Sale coupons /saleCoupons

GET - getting all sale coupons
GET api/xxxxxx/saleCoupons

Returns sale coupons which are available based on chosen parameters.

Available request parameters:
Parameter name Data type Parameter type Description
couponGroupId integer optional ID of a sale coupon group
coupon string optional Name of sale coupon
sent bool optional Show only sent / not sent sale coupons
page integer optional page number (default value is 1)
pageSize integer optional number of records on a page (default value is 25)
Response object example
{
  "data": [
    {
      "couponId": 37,
      "couponGroupId": 2,
      "mailId": null,
      "generatorExecutionId": null,
      "transactionalEmailId": 1234,
      "transactionalEmailGuid": "2067fca8-446d-ea00-af03-00155d012d0b",
      "coupon": "aaaaa",
      "email": "jan@webkomplet.cz",
      "created": "2020-11-24T20:18:31.81",
      "validity": null,
      "sent": "2020-11-24T20:19:21.053"
    }
  ],
  "totalRecordCount": 1
}

Response object parameters
Parameter name Data type Description
coupongId integer Sale coupon ID
couponGroupId integer Sale coupon group ID
mailId integer Mass email ID, where the sale coupon was used.
generatorExecutionId integer Generator execution ID, where the sale coupon was used.
transactionalEmailId integer Transactional email ID, where the sale coupon was used.
transactionalEmailGuid string Transactional email GUID, where the sale coupon was used.
coupon string Sale coupon value
email string Recipients email address
created datetime When a sale coupon was created
validity datetime Until when a sale coupon is valid (ready to be used)
sent datetime When a sale coupon was sent
POST - creating new sale coupons
POST api/xxxxxx/saleCoupons

Creates new sale coupons.

Sample JSON object that has to be found in the body request:
{
    "coupons": [
        {
            "code": "coupon1",
            "validity": "2022-11-26T05:53:32"
        },
        {
            "code": "coupon2",
            "validity": null
        }
    ],
    "couponGroupId": 2
}

Request object parameters
Parameter name Data type Parameter type Description
coupons array required Coupons to be added
couponGroupId integer required Sale coupon groups ID
Response object example

Response body is usually empty. Result of this operation is represented in response code.

DELETE - deleting a sale coupon
DELETE api/xxxxxx/saleCoupons/{id:int}

Deletes a sale coupon based on an ID

Response object example

Response body is usually empty. Result of this operation is represented in response code.

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 email: 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 } }
Required 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.
Currency enum
CZK = 5, EUR = 7, USD = 32, GBP = 33
UpdateBasketContent - updating the whole cart
MkTracker.updateBasketContent(items[])

Updates the whole cart.

Available request parameters:
Parameter name Data type Parameter type Description
items object[] required 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 request parameters:
Parameter name Data type Parameter type Description
item object required 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 request parameters:
Parameter name Data type Parameter type Description
item object required 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 required to pass the ID of the order generated by your system + you can mention the parameter email.

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

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

Available request parameters:
Parameter name Data type Parameter type Description
email string required email address of the visitor
PushEvent - pushes custom event for automation triggering
MkTracker.pushEvent(eventName, customData)

Push custom event to start automation.

Available request parameters:
Parameter name Data type Parameter type Description
eventName string required name of event
customData object optional object with custom additional data

Webhooks

Webhooks enable realtime messaging from Mail Komplet to your application. It uses HTTP communication to notify about selected events. Mail Komplet can send specified objects to defined URLs and then your application can process them. Several events, when you can use webhooks, are described below.

Delivery of transactional e-mail

Fired when transactional e-mail is delivered.


{
    "webhookTypeId": 1,
    "transactionalEmailId": 989206,
    "created": "2021-08-03T06:15:02.44",
    "recipient": "***@***.**",
    "fromAddress": "***@***.**",
    "subject": "Test of transactional e-mails"
    "guid": "********-****-****-****-************"
    "sent": "2021-08-03T06:15:04",
    "delivered": "2021-08-03T06:15:24"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
created Datetime of e-mail creation
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
delivered Datetime, when an e-mail was delivered
Click in transactional e-mail

Fired when a link click in a transactional e-mail is realized.


{
    "webhookTypeId": 2,
    "transactionalEmailId": 989209,
    "clickId": 114651,
    "created": "2021-08-03T07:04:17.08",
    "recipient": "***@***.**,
    "fromAddress": "***@***.**",
    "subject": "Test of transactional e-mails",
    "guid": "********-****-****-****-************",
    "sent": "2021-08-03T06:50:15",
    "delivered": "2021-08-03T06:50:34",
    "linkUrl": "https://www.mail-komplet.cz",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.107 Safari/537.36"
  
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
clickId Link click ID
created Datetime of link click
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
delivered Datetime, when an e-mail was delivered
linkUrl URL of link
userAgent User agent of device, where this click was realized
Opening of transactional e-mail

Fired when a transactional e-mail is opened.


{
  "webhookTypeId": 3,
  "transactionalEmailId": 989209,
  "openId": 562610,
  "created": "2021-08-03T08:10:49.897",
  "recipient": "***@***.**",
  "fromAddress": "***@***.**",
  "subject": "Test of transactional e-mails",
  "guid": "********-****-****-****-************",
  "sent": "2021-08-03T06:50:15",
  "delivered": "2021-08-03T06:50:34",
  "userAgent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
openId Opening ID
created Datetime of opening
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
delivered Datetime, when an e-mail was delivered
userAgent User agent of device, where this e-mail was opened
Soft bounce of transactional e-mail

Fired when a transactional e-mail soft bounces.


{
    "webhookTypeId": 4,
    "transactionalEmailId": 989220,
    "deliveryInfoId": 11284385,
    "created": "2021-08-03T10:16:48",
    "recipient": "***@***.**",
    "fromAddress": "***@***.**",
    "subject": "Test of transactional e-mails",
    "guid": "********-****-****-****-************",
    "sent": "2021-08-03T08:16:36"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
deliveryInfoId Delivery info ID
created Datetime of soft bounce
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
Hard bounce of transactional e-mail

Fired when a transactional e-mail hard bounces.


{
    "webhookTypeId": 5,
    "transactionalEmailId": 989409,
    "deliveryInfoId": 11284466,
    "created": "2021-08-04T08:54:48",
    "recipient": "***@***.**",
    "fromAddress": "***@***.**",
    "fromDispalyName": "Mail Komplet",
    "subject": "Your first email message.",
    "guid": "********-****-****-****-************",
    "sent": "2021-08-04T06:54:44"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
deliveryInfoId Delivery info ID
created Datetime of hard bounce
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
fromDispalyName Sender's display name
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
Unsubscription from transactional e-mail

Fired when an unsubscription from transactional e-mail occures.


{
    "webhookTypeId": 6,
    "transactionalEmailId": 989418,
    "excludeListId": 1231739,
    "created": "2021-08-04T09:11:00",
    "recipient": "***@***.**",
    "fromAddress": "***@***.**",
    "subject": "Test of transactional e-mails",
    "guid": "********-****-****-****-************",
    "sent": "2021-08-04T07:10:23",
    "delivered": "2021-08-04T07:10:42"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
excludeListId Exclude list ID - ID of unsubscription
created Datetime of unsubscription
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
delivered Datetime, when an e-mail was delivered
Spam complaint from transactional e-mail

Fired when a spam complaint from transactional e-mail occures.


{
    "webhookTypeId": 7,
    "transactionalEmailId": 989424,
    "excludeListId": 1231744,
    "created": "2021-08-04T07:30:00",
    "recipient": "***@***.**",
    "fromAddress": "***@***.**",
    "subject": "Test of transactional e-mails",
    "guid": "********-****-****-****-************",
    "sent": "2021-08-04T07:27:33",
    "delivered": "2021-08-04T07:27:44"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
transactionalEmailId Transactional e-mail ID
excludeListId Exclude list ID - ID of unsubscription
created Datetime of unsubscription
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
subject E-mail's subject
guid E-mail's GUID
sent Datetime, when an e-mail was sent
delivered Datetime, when an e-mail was delivered
Unsubscription from mass e-mail

Fired when an unsubscription from mass e-mail occures.


{
    "webhookTypeId": 8,
    "mailId": 378651800,
    "excludeListId": 1231749,
    "created": "2021-08-04T10:01:00",
    "recipient": "***@***.**",
    "fromAddress": "***@***.**",
    "sent": "2021-05-28T11:46:57"
}
Object parameters:
Parameter name Description
webhookTypeId Webhook type ID
mailId Mass e-mail ID
excludeListId Exclude list ID - ID of unsubscription
created Datetime of unsubscription
recipient Recipient's e-mail address
fromAddress Sender's e-mail address
sent Datetime, when an e-mail was sent