Overview

1. General

The base API URL is https://em.kmatrixonline.com/api

1.1. HTTP headers

All eM API endpoints require an authorizated token to access, you need to supply your API key with the Authorization header. For request that require a valid JSON object for the body, you need to set the Content-Type header too.

Authorization

Bearer YOUR_API_KEY

Content-Type

application/json; charset=UTF-8

1.2. HTTP methods

The eM API supports 5 HTTP methods for interacting with resources:

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource (complete replacement)

PATCH

Used to update an existing resource (partial)

DELETE

Used to delete an existing resource

1.3. HTTP response code

Code Description

200

Action completed successfully.

400

Bad request. Wrong parameters supplied or the resource requested to add or update already exist.

401

Unauthorized. Wrong credentials entered or API key expired.

403

Forbidden. Your account do not have the right to access a particular endpoint.

404

Not found. Some resource is not found in your request.

500

Internal server error. Please contact our support with the Error code.

1.4. Pagination

For endpoints that paginate the result, you can control and iterate the reuslt with the following request parameters

Table 1. Request parameters
Path Type Optional Description

page

Integer

false

Page you want to retrieve, the first page is indexed 0 and defaults to 0.

size

Integer

false

Size of the page you want to retrieve, defaults to 50, maximum is 1000.

sort

String

false

Properties that should be sorted by in the format property,property(,ASC|DESC). Default sort direction is ascending. Use multiple sort parameters if you want to switch directions, e.g. ?sort=name&sort=id,asc.

Please note that not all properties are supported for sorting

For example, to sort the result by descending ID, paginate the result to 100 items per page and retrieve the second page, we append the following query string to the request endpoint

?size=100&page=1&sort=id,desc

Pagination response has following structure:

Table 2. Response structure
Path Type Description

content

Array[Object]

Actual items.

page

Object

first

Boolean

If this page is the first one.

last

Boolean

If this page is the last one.

totalPages

Integer

Total pages with current page size.

totalElements

Integer

Total count.

totalPages

Integer

Total pages with current page size.

numberOfElements

Integer

Actual size of content array (number of items).

size

Integer

Requested size of the page.

number

Integer

Page number.

sort

Object

Contains a list of the following object, empty if no sort parameters are supplied.

property

String

the sorted property

direction

String

ASC or DESC

Resources

Resources are nouns such as customers or campaigns that you can take actions on with supported HTTP methods.

2. Email Identity

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-email-identity/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-email-identity/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-identity/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-identity-list/auto-section.adoc[]

3. Customer Tag

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-tag/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-tag/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-tag/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-tag-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/share-tag/auto-section.adoc[]

4. Customer

The add customers and list customers endpoints accept the following field names (case sensitive)

Table 3. Customer fields

Email

CountryCode

Mobile

HomeAddress

OfficeAddress

ContactAddress

Telephone

OfficeTelephone

Pager

Fax

Region

Title

DisplayName

ChineseName

FirstName

LastName

Sex

Birthday

Income

Company

MemberNo

MemberCategory

JoinDate

ExpiryDate

Custom1

Custom2

Custom3

Notes

Unresolved directive in index.adoc - include::../../../target/generated-snippets/add-customer/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-customer-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-optout-email-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/optout-email/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/unlist-optout-email/auto-section.adoc[]

5. Campaign Category

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-campaign-category/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-campaign-category/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-campaign-category/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-campaign-category-list/auto-section.adoc[]

6. Email Template Folder

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-email-template-folder/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-email-template-folder/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-template-folder/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-template-folder-list/auto-section.adoc[]

7. Email Template

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-email-template/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-email-template/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-template/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-template-list/auto-section.adoc[]

8. Email Campaign

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-email-campaign/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-email-campaign/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-campaign/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-email-campaign-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/send-test-mail/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/approve-campaign/auto-section.adoc[]

9. SMS Campaign

Unresolved directive in index.adoc - include::../../../target/generated-snippets/create-sms-campaign/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/update-sms-campaign/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-sms-campaign/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-sms-campaign-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/approve-sms-campaign/auto-section.adoc[]

10. Subuser

Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-subuser-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/share-tag/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/get-shared-tag-list/auto-section.adoc[] Unresolved directive in index.adoc - include::../../../target/generated-snippets/revoke-shared-tag/auto-section.adoc[]