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.
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.
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:
Response codes are part of server response to client's request. Most of responses usually contain these response codes:
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.
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:
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
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)"
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.
/mailingLists
GET api/xxxxxx/mailingLists
Mailing lists are returned, which are available in your account in our system.
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) |
{
"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
}
]
}
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 api/xxxxxx/mailingLists
Creates a new mailing list within the account.
{
"name": "Testing mailing list",
"description": "Mailing list description",
"isTest": true
}
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? |
{
"mailingListId": 11691
}
Parameter name | Data type | Description |
---|---|---|
mailingListID | integer | ID of created 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.
{
"name": "Testing mailing list",
"description": "Mailing list description",
"isTest": true
}
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 body is usually empty. Result of this operation is represented in response code.
DELETE api/xxxxxx/mailingLists
Deletes a mailing list from the system.
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 | 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. |
Response body is usually empty. Result of this operation is represented in response code.
/contacts
GET api/xxxxxx/contacts
Return recipients which can be found in the system under entered 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 |
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) |
{
"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": "",
"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
}
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 |
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 e-mail |
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 api/xxxxxx/contacts
Creates new recipient. If a recipient with given e-mail already exists it will update an existing one.
{
"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"
}
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
string | required | ||
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) |
{
"contactId": 8368817
}
Parameter name | Data type | Description |
---|---|---|
contactId | integer | ID of created 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"
}
}
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 body is usually empty. Result of this operation is represented in response code.
DELETE api/xxxxxx/contacts
Deletes a recipient from the system
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 body is usually empty. Result of this operation is represented in response code.
In case the mailing list ID has not occured the recipients will be deleted from the database! (this action is irreversible)
POST api/xxxxxx/contacts/bulk
Executes a bulk import based on showcased parameters.
{
"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"
}
]
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
preImportAction | int | required |
|
contactOverwriteMode | int | required |
|
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. |
{
"data": {
"operationId": "fde11e2f-3d10-4fe5-9f3f-6b9390fbar18"
}
}
Parameter name | Data type | Description |
---|---|---|
operationId | integer | GUID of bulk import operation |
Bulk import of recipients could take some time depending on count of inserted items. You can find a state of a bulk import process using /contacts/getBulkInfo endpoint.
GET api/xxxxxx/contacts/getBulkInfo
Returns information about the state of the import.
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
operationId | GUID | required | GUID of bulk import operation |
{
"data": {
"status": "SuccessfulyFinished",
"errors": null,
"errorMessage": null
}
}
Parameter name | Data type | Description |
---|---|---|
status | string | Status of import. It should be:
|
errors | string | Errors during an import |
errorMessage | string | Outer error message |
/subscribeContacts
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.
{
"email": "jan@webkomplet.cz",
"name": "Jan",
"surname": "Novák",
"sex": true,
"title": null,
"mobilePhone": "775123456",
"company": "Webkomplet",
"mailingListIds": [ 1, 2, 3 ],
"customColumns": {},
"dispatcherId": 1234
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
string | required | ||
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) |
{
"subscribeRequestId": 81911
}
Parameter name | Data type | Description |
---|---|---|
subscribeRequestId | integer | ID of created subscribe request |
/templates
GET api/xxxxxx/templates
Returns available templates in your account.
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) |
{
"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
}
]
}
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:
|
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
GET api/xxxxxx/campaigns
Returns available campaigns in your account.
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) |
{
"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,
"senderDisplayName": null,
"senderEmail": null,
"mailFromDisplayName": "Webkomplet",
"mailFromAddress": "info@webkomplet.cz",
"replyToDisplayName": null,
"replyToAddress": null
}
]
}
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:
|
schedulerId | integer | Scheduler ID |
nextRunTime | dateTime | Date of scheduled distribution |
senderDisplayName | string | From name to display - deprecated |
senderEmail | string | From e-mail to display - deprecated |
mailFromDisplayName | string | From name to display |
mailFromAddress | string | From e-mail to display |
replyToDisplayName | string | Reply to name |
replyToAddress | string | Reply to e-mail |
POST api/xxxxxx/campaigns
Creates new campaing in the system
{
"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,
"contactFilter": null
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
templateId | integer | optional | Template ID |
dispatcherId | integer | optional | Domain redirect ID |
unsubscribeTypeId | integer | required | Unsubscribe type:
|
ignoreExcludeList | boolean | optional | Send messages to unsubscribed recipients? Default set to false. |
autoLinkTracking | boolean | optional | Track link clicks? |
name | string | required | Name |
description | string | optional | Description |
webTrackParam | string | optional | Link tagging |
mailFromDisplayName | string | optional | Name of sender to display |
mailFromAddress | string | required | e-mail of sender to display |
insertTrackingImage | boolean | optional | Insert tracking image? |
contactFilter | string | optional | Filter on contacts |
{
"campaignId": 28494
}
Parameter name | Data type | Description |
---|---|---|
campaignId | integer | ID of created 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.
{
"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,
"contactFilter": null
}
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 body is usually empty. Result of this operation is represented in response code.
DELETE api/xxxxxx/campaigns
Deletes a campaign based on an ID
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
id | integer | required | ID of a campaign you want to delete |
Response body is usually empty. Result of this operation is represented in response code.
/dispatchers
GET api/xxxxxx/dispatchers
Returns domain redirects which are available in your account.
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) |
{
"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": "",
"unsubscribeCampaignId": 26185,
"useFeedback": false,
"feedback": null,
"feedbackUrl": null,
"domainRewrite": "",
"cnameRecord": null,
"useIdentifier": false
}
]
}
Parameter name | Data type | Description |
---|---|---|
dispatcherId | integer | Dispatcher (domain redirect) ID |
status | integer | Dispatcher state:
|
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 e-mail? |
welcomeCampaignId | boolean | ID of campaign used to send welcome e-mail |
useUnsubscribeAuthentication | boolean | Use unsubscribe verification? |
unsubscribeAuthenticationReturnUrl | string | return URL address after sending unsubscribe request |
sendUnsubscribeAuthenticationFormReturnUrl | string | return URL address after sending unsubscribe request form |
unsubscribeCampaignId | integer | ID of campaign used to send unsubscribe confirmation link |
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 |
/transactionalEmails
GET api/xxxxxx/transactionalEmails
Return a list of transactional e-mail which are available based on chosen 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 (part of the e-mail will also work) |
state | integer | optional | State of a transactional e-mail:
|
isOpened | bool | optional | Select only opened e-mails? |
isClicked | bool | optional | Select only clicked e-mails? |
guid | GUID | optional | Transactional e-mail 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) |
{
"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,
"rownum": 226
}
],
"totalRecordCount": 1
}
Parameter name | Data type | Description |
---|---|---|
emailId | integer | Transactional e-mail ID |
queuePriority | integer | Queue priority:
|
phase | integer | Phase of transmitting:
|
state | integer | State of a transactional e-mail:
|
created | datetime | Date of creation |
sendAt | datetime | Scheduled date of sending |
sent | datetime | Date of sending |
delivered | datetime | Date of delivery |
fromAddress | string | E-mail address of sender |
fromDisplayName | string | Name of sender |
toAddress | string | E-mail of recipient |
toDisplayName | string | Name of recipient |
subject | string | Subject of an e-mail |
bodyFormat | boolean | Format of an e-mail
|
emlSize | integer | Size of an eml |
result | string | In case of any error you can find here detail info |
opened | datetime | When the e-mail was opened |
clicked | datetime | When some link in the e-mail was clicked |
softBounced | boolean | Was e-mail marked as soft bounce? |
hardBounced | boolean | Was e-mail marked as hard bounce? |
isBulk | boolean | Is bulk e-mail? |
unsubscribed | datetime | Date of unsubscribe request |
reportedAsSpam | datetime | Is reported as spam? |
guid | string | Transactional e-mail GUID |
tags | string | Tags |
isClicked | boolean | Was some link in the e-mail clicked? |
isOpened | boolean | Was this e-mail opened? |
rownum | integer | Items row number in this result |
POST api/xxxxxx/transactionalEmails
Sending a transactional e-mail.
{
email: {
fromAddress: "jan@webkomplet.cz",
fromDisplayName: "Mail Komplet",
to: [{
address: "jana@webkomplet.cz",
variables: {
nothingVariable1: "variable text 1 for this e-mail",
nothingHtml: "Hi, dear recipient"
}
}
],
subject: "Your first e-mail message.",
bodyHtml: "Hello world.",
bodyText: "Hello world.",
attachments: [
{
"contentType": "text/plain",
"name": "file.txt",
"content": "VGhpcyBpcyB0ZXN0"
}
],
variables: {
nothingVariable: "variable text 1 fro all e-mails",
nothingText: "text 1 fro all e-mails",
},
trackOpens: true,
trackClicks: true,
campaignId: 2525
}
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
fromAddress | string | required | E-mail 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 | E-mails' body in HTML format |
bodyText | string | optional | E-mails' body in text format |
attachments | array | optional | List of attachments |
variables | object | optional | Variables |
trackOpens | boolean | optional | Track opens of this e-mail? |
trackClicks | boolean | optional | Track clicks on links in this e-mail? |
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.
{
"data": [
{
"email": "jan@webkomplet.cz",
"guid": "2a84821c-2344-ea11-aeff-00155d012d0b"
}
]
}
Parameter name | Data type | Description |
---|---|---|
string | Email address of recipient | |
guid | string | Transactional e-mail GUID |
GET api/xxxxxx/transactionalEmails/opens
Returns a list of transactional e-mails's open rate which is available based on specified 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) |
{
"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)"
}
]
}
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 api/xxxxxx/transactionalEmails/clicks
Returns a list of clicks of transactional e-mails which are available based on chosen 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) |
{
"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"
}
]
}
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 |
/transactionalSms
GET api/xxxxxx/transactionalSms
Returns a list of transactional SMS which are available based on chosen 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) |
{
"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
}
Parameter name | Data type | Description |
---|---|---|
smsId | integer | SMS ID |
state | integer | State of a transactional e-mail:
|
queuePriority | integer | Queue priority:
|
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 api/xxxxxx/transactionalSms
Sending a transactional SMS.
{
"sms": {
"to": [{
"number": "+4207752123456"
}
],
"text": "Your first SMS message.",
"groupId": 1
}
}
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 |
groupId | integer | optional | Transactional SMS group ID |
{
"data": [
{
"number": "+420775123456",
"guid": "34851b54-d56b-4199-aac2-4f71c5bcc6a7"
}
]
}
Parameter name | Data type | Description |
---|---|---|
number | string | Recipients' phone number |
number | string | Recipients' phone number |
guid | string | Transactional SMS GUID |
/generatorExecutions
GET api/xxxxxx/generatorExecutions
Returns distributions which are available based on chosen 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) |
{
"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
}
Parameter name | Data type | Description |
---|---|---|
campaignName | string | Campaign name |
campaignId | integer | Campaign ID |
campaignType | integer | Campaign type:
|
generatorExecutionId | integer | Generator execution ID |
status | integer | State:
|
phase | integer | Phase:
|
spentCredits | integer | Credits spent |
totalCount | integer | Total count of messages |
clickCount | integer | Clicked through e-mails (multiple clicks in one e-mail are counted as one item) |
clickCountTotal | integer | Total link clicks (multiple clicks in one e-mail are counted separately) |
openCount | integer | Opened e-mails (multiple opens of one e-mail are counted as one e-mail) |
openCountTotal | integer | Opens of e-mails (multiple opens of one e-mail 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 |
/customColumns
GET api/xxxxxx/customColumns
Returns user columns which are available based on chosen 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) |
{
"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
}
Parameter name | Data type | Description |
---|---|---|
customColumnId | integer | Custom column ID |
customColumnTypeId | integer | Custom column type ID:
|
customColumnGroupId | integer | Custom column group ID |
dataTypeId | integer | Data type ID:
|
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 api/xxxxxx/customColumns
Creates a new user column.
{
"dataTypeId": 1,
"name": "myUserColumn",
"caption": "caption",
"description": "description",
"defaultValue": 1,
"minValue": 1,
"maxValue": 1,
"required": false,
"unique": false,
"disabled": false,
"precision": null,
"order": null
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
dataTypeId | integer | required | Data type ID:
|
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 |
{
"customColumnId": 17267
}
Parameter name | Data type | Description |
---|---|---|
customColumnId | integer | Custom column ID |
PUT api/xxxxxx/customColumns
Updates a user column.
{
"dataTypeId": 1,
"name": "myUserColumn",
"caption": "caption",
"description": "description",
"defaultValue": 1,
"minValue": 1,
"maxValue": 1,
"required": false,
"unique": false,
"disabled": false,
"precision": null,
"order": null
}
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 body is usually empty. Result of this operation is represented in response code.
DELETE api/xxxxxx/contacts
Deletes a user column from your account
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
id | integer | required | ID of a user column you want to delete |
Response body is usually empty. Result of this operation is represented in response code.
/excludeLists
GET api/xxxxxx/excludeLists
Returns unsubscribed recipients which are available based on chosen 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) |
{
"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,
"rownum": 24
}
],
"totalRecordCount": 1,
"pageCount": 1
}
Parameter name | Data type | Description |
---|---|---|
excludeListId | integer | Exclude list item ID |
mailingListId | integer | Mailing list ID |
campaignId | integer | Campaign ID |
string | Email of unsubscribe recipient | |
createdDate | datetime | Date of creation |
reason | string | Reason of unsubscription |
sourceGeneratorExecutionId | integer | Source generator execution ID |
origin | integer | Origin:
|
reasonId | integer | Reason ID:
|
bounceTypeId | integer | Bounce type ID:
|
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 |
rownum | integen | Row number |
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".
{
"mailingListsId": 1,
"campaignId": 1,
"generatorExecutionId": 1,
"email": "info@webkomplet.cz",
"reason": "text"
}
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
mailingListsId | integer | optional | Mailing list ID |
campaignId | integer | optional | Campaign description |
generatorExecutionId | integer | optional | Generator execution ID |
string | required | ||
reason | string | optional | Reason |
Response body is usually empty. Result of this operation is represented in response code.
DELETE api/xxxxxx/excludeLists
Deletes a record about unsubscribing.
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
id | integer | required | ID of a unsubscribed recipient's record (exclude list item) |
Response body is usually empty. Result of this operation is represented in response code.
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.
{
"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
}
}
CZK = 5, EUR = 7, USD = 32, GBP = 33
MkTracker.updateBasketContent(items[])
Updates the whole cart.
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 |
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.
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 |
MkTracker.removeBasketItem(item)
Remove an item from the cart. In this case the parameter "amount" defines what amount of this item was removed.
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 |
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 e-mail.
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
orderId | string | required | ID of an order from your e-shop or web |
string | optional | E-mail address of the customer |
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.).
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
string | required | E-mail address of the visitor |
MkTracker.pushEvent(eventName, customData)
Push custom event to start automation.
Parameter name | Data type | Parameter type | Description |
---|---|---|---|
eventName | string | required | name of event |
customData | object | optional | object with custom additional data |