NAV Navbar
Logo

Introduction

Mapp Engage is a software as a service (SaaS) for multi-channel marketing. This enables you to orchestrate fully automated, comprehensive multi-step customer campaigns that successfully combine email, social, mobile and web.

Mapp gives you the ability to interact with your contacts with relevant information at the right time. By taking advantage of our marketing software, you benefit from a comprehensive range of features as well as current best practice advice from our digital marketing experts.

What is the Mapp Engage API?

An API is used by two or more platforms to share information and manage processes without the need for human intervention. The Mapp Engage API makes it possible for you to connect any program or webpage to your marketing platform. This lets you pull data into our system and extract information for reuse in other applications.

We employ a consistent scheme for our SOAP and REST API solutions. Feel free to decide which solution best fits your needs. For an overview of the SOAP solution, see SOAP API. For an overview of the REST solution, see REST API.

Other API solutions and the previous REST and SOAP solutions are still available, however these will no longer be extended or updated. If you wish to continue using an old application that is based on these interfaces, please contact your customer support representative.

API Tools

SoapUI is an open-source web service testing application

To setup REST project in soapui

To setup SOAP project in soapui

Another API tool is called Postman

Domains

API calls are grouped within functional test domains.

REST SOAP Description
async async Contains methods for processing data asynchronously and for requesting the result of the process.
automation automation Contains methods that let you interact with automations in Mapp Engage.
blacklist blacklist Contains methods that you use to manage system and group blacklists.
cms cms Contains methods that you use to manage messages stored in the Content Management System (CMS).
contact contact Contains methods for working with contact profiles.
content content Contains methods that are used to manage elements in the Content Store.
draftmessage draftmessage Contains methods for working with an email or SMS message that has been saved as a draft.
group group Contains all group-related methods.
landingpage landingpage Contains methods that can be used to manage landing pages.
membership membership Contains methods that are used to manage group memberships.
message message Contains methods that can be used to manage email and SMS messages.
meta meta Contains methods that define your system.
preparedmessage preparedmessage A prepared message is a saved message that you have assigned to a group.
process process Contains methods that let you interact with a process in Mapp Engage.
relatedData relatedData Contains methods to manage records stored in Related Data.
system system Contains methods that return information about the current version of the system in use.
systemuser systemuser Contains system user related methods such as editing, deleting, and creating a system user.
user user Contains methods for contact management.

Access and Authentication

Authentication and Users

Both SOAP and REST API use HTTP basic authentication method that does not require cookies or session tokens.

For this reason, there are no explicit login and logout methods. Instead authorization header must be included in each API request.

The example header for 'test@test.com' user and 'test' password is following

Authorization: Basic dGVzdEB0ZXN0LmNvbTp0ZXN0

You should use "API user" or "Hybrid User" user type for authentication.

In case "UI User" user is trying to connect, the following message is displayed

Secure Connection

All API requests allow HTTP and HTTPS access. For your own security, we strongly recommend using HTTPS. Your email address and password are transferred with every request that is sent to our system. Authentication using HTTP uses only Base64 encoding and does not provide any protection for the transmitted data.

IP Restriction

Establishing IP restriction is an additional way to protect your Mapp Engage system against unauthorized access. IP restriction offers a significant increase in security for the protection of your contact and message data.

To more tightly control access to Mapp Engage, system login is restricted to pre-defined IP addresses or IP ranges. Access is granted only to computers that belong to this address pool (i.e., that are located within your company network or that are part of a pre-defined service provider or system).

API Version

When you start programming, always use the latest version of the API. Older versions might not support all of the new functionality that is provided within Mapp Engage.

REST API

ROOT ENDPOINT
https://cook.shortest-route.com/central_support/api/rest/v10 Use your system URL accordingly
WADL
https://cook.shortest-route.com/central_support/api/rest/v10?wadl Use your system URL accordingly

If authorization header is missing, HTTP 401 response is returned.

Some concepts that you should keep in mind:

/async

The async domain contains methods for queue handling. Topic name is required for that.

Available from
v1

/submit

Description

Adds new element to the topic

Request path

POST [REST API ROOT]/async/submit

Query Parameters

Parameter Type Description
topic String -

Request Body Type

list of Attribute arguments

/poll

Description

Retrieves a certain amount of results for a topic from the result queue. The result items that were retrieved are deleted from the server once they have been transmitted.

Request path

GET [REST API ROOT]/async/poll

Query Parameters

Parameter Type Description
topic String -
limit Integer -

/pollByIndex

Description

Retrieves a specific number of results for a topic from the result queue, starting from the given offset.

Available from
v9

Request path

GET [REST API ROOT]/async/pollByIndex

Query Parameters

Parameter Type Description
topic String Name of the topic.
index Long Number of the offset to start from.
limit Integer Number of result items to retrieve.

/getSubmitCount

Description

Returns the number of job results that were submitted for a certain topic.

Request path

GET [REST API ROOT]/async/getSubmitCount

Query Parameters

Parameter Type Description
topic String -

/getPollCount

Description

Returns the number of result items that were retrieved/polled for a certain topic.

Request path

GET [REST API ROOT]/async/getPollCount

Query Parameters

Parameter Type Description
topic String -

/getRemainingCapacity

Description

Returns the remaining capacity for a certain topic. Each result item is saved and assigned to a topic. Each topic has a limited amount of storage capacity. Submitting new results is blocked once the limit for the topic has been reached. Whenever the asyncPoll() call is executed, the transmitted data is deleted and new space is made available.

Request path

GET [REST API ROOT]/async/getRemainingCapacity

Query Parameters

Parameter Type Description
topic String -

/getNextIndex

Description

Returns the next index for the given topic relative to the last call to "async/poll". This call is useful when switching from calling "async/poll" (with a managed index) to calling "async/pollByIndex" where the index is managed by the user. The result value can be used as value for parameter "index" in a follow up call to "async/pollByIndex".

Available from
v9

Request path

GET [REST API ROOT]/async/getNextIndex

Query Parameters

Parameter Type Description
topic String -

/automation

/find

Description

Returns information about one or more automations. Use this method to obtain information about time-based or event-based automations.

Available from
v7

Request path

POST [REST API ROOT]/automation/find

Query Parameters

Parameter Type Description
None - -

Request Body Type

AutomationFilter

/getDetails

Description

Returns detailed information for an automation. Use this method to obtain information about time-based or event-based automations.

Available from
v7

Request path

GET [REST API ROOT]/automation/getDetails

Query Parameters

Parameter Type Description
automationId Long ID of the automation
automationType automationType ID of the automation

/runOnce

Description

Performs one execution of the specified time-based automation. Execution takes place immediately. Run once does not change the status or schedule of the automation. You can only use this method to run an existing time-based automation. To execute the automation successfully, the API user account must also have the permissions required to run the job.

Available from
v7

Request path

GET [REST API ROOT]/automation/runOnce

Query Parameters

Parameter Type Description
automationId Long ID of the automation

/blacklist

The blacklist domain contains methods that are used to manage system and group blacklists.

Available from
v4

/createGroupEntries

Example body

[{
"type": "EMAIL",
 "pattern": "test@test.com"
}]

Example response

[{
    "success": true,
    "id": "test@test.com",
    "errorActor": null,
    "errorCode": null,
    "errorMessage": null
}]

Description

Adds new entries (email, emailDomain, mobileNumber, or faxNumber) to the group blacklist.

Request path

POST [REST API ROOT]/blacklist/createGroupEntries

Query Parameters

Parameter Type Description
groupId Long ID of the group

Request Body Type

list of BlacklistEntries

/createGroupEntriesHashed

Example body

 [
    {
        "type": "EMAIL",
        "pattern":"6a4b6cb2045fd55f706eaebd6ab5d4f7"
    },
    {
        "type": "EMAIL",
        "pattern":"0dbfb46341bc3d195db23e4015b20847"
    }
]

Description

Adds new hashed email entries to the group blacklist. Entries can be hashed using md5hashgenerator

Available from
v9

Request path

POST [REST API ROOT]/blacklist/createGroupEntriesHashed

Query Parameters

Parameter Type Description
groupId Long The group ID.
hashed String hashing algorithm used to hash given entries. Either 'clear-text' or 'md5'

/deleteGroupEntries

Example body

[{
"type": "EMAIL",
 "pattern": "test@test.com"
}]


Example response

[{
    "success": true,
    "id": "test@test.com",
    "errorActor": null,
    "errorCode": null,
    "errorMessage": null
}]

Description

Deletes entries (email, email domain, mobile number, or fax number) from the group blacklist.

Request path

POST [REST API ROOT]/blacklist/deleteGroupEntries

Query Parameters

Parameter Type Description
groupId Long ID of the group

Request Body Type

list of BlacklistEntries

/createSystemEntries

Example body

[{
"type": "EMAIL",
 "pattern": "test@test.com"
}]

Example response

[{
    "success": true,
    "id": "test@test.com",
    "errorActor": null,
    "errorCode": null,
    "errorMessage": null
}]

Description

Adds new entries (email, email domain, mobile number, or fax number) to the system blacklist.

Request path

POST [REST API ROOT]/blacklist/createSystemEntries

Query Parameters

Parameter Type Description
groupId Long ID of the group

Request Body Type

list of BlacklistEntries

/createSystemEntriesHashed

Example body

 [
    {
        "type": "EMAIL",
        "pattern":"6a4b6cb2045fd55f706eaebd6ab5d4f7"
    },
    {
        "type": "EMAIL",
        "pattern":"0dbfb46341bc3d195db23e4015b20847"
    }
]

Description

Adds new entries (email, email domain, mobile number or mobile app alias) to the system blacklist. Entries can be hashed using md5hashgenerator

Available from
v9

Request path

POST [REST API ROOT]/blacklist/createSystemEntriesHashed

Query Parameters

Parameter Type Description
hashed String hashing algorithm used to hash given entries. Either 'clear-text' or 'md5'

/deleteSystemEntries

Example body

[{
"type": "EMAIL",
 "pattern": "test@test.com"
}]

Example response

[{
    "success": true,
    "id": "test@test.com",
    "errorActor": null,
    "errorCode": null,
    "errorMessage": null
}]

Description

Deletes entries (email, email domain, mobile number, or fax number) from the system blacklist.

Request path

POST [REST API ROOT]/blacklist/deleteSystemEntries

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of BlacklistEntries

/cms

The cms domain contains methods you use to manage messages stored in the Content Management System (CMS)

Available from
v3

/getMessageDefinitions

Description

Returns a list of all CMS messages that are saved in the system. Every CMS message contains detailed information that identifies the message and the template that was used for creation.

Request path

GET [REST API ROOT]/cms/getMessageDefinitions

Query Parameters

Parameter Type Description

/getMimeMessage

Description

Returns the specified CMS message in MIME message format.

Request path

GET [REST API ROOT]/cms/getMimeMessage

Query Parameters

Parameter Type Description
cmsMessageId Long The ID of the CMS message to be returned.

/contact

The contact domain contains methods for working with contact profiles.

Available from
v7

/create

Example bodies

{
    "emailAddress" : "testuser@test.com"
}
{
    "mobileNumber" : "48505606708"
}
{
    "applicationAlias" : "testuser@test.com"
}

Description

Creates a new contact using the information provided in the contact object.

Request path

POST [REST API ROOT]/contact/create

Query Parameters

Parameter Type Description
contact Contact An object that contains a definition of the contact to be created.

/get

Example bodies

{
    "type":"EMAIL",
    "value":"test@test.com"
}
{
    "type":"MOBILE",
    "value":"48505606707"
}

Description

Returns a contact object that matches the specified identifier.

Request path

POST [REST API ROOT]/contact/get

Query Parameters

Parameter Type Description
identifier ContactIdentifier The contact identifier.

/update

Example body

{
"emailAddress" : "testuser@test.com",
"applicationAlias" : "testuseralias@test.com"
}

Description

Updates the profile data of an existing contact.

Request path

POST [REST API ROOT]/contact/update

Query Parameters

Parameter Type Description
identifier ContactIdentifiertype The type of identifier to be used for the contact update.

/delete

Description

Deletes the contact identified by the specified identifier.

Request path

POST [REST API ROOT]/contact/delete

Query Parameters

Parameter Type Description
identifier ContactIdentifiertype The identifier that references the contact.

/anonymize

Description

Anonymizes contact PII data based on GDPR regulations.

Available from
v9

Request path

GET [REST API ROOT]/contact/anonymize

Query Parameters

Parameter Type Description
contactId Long The user ID of the contact to perform anonymization for.
notificationRecipient String Active system user witch is going to be used for permission checks, and will get system message .

/export

Description

Pushes asynchronyous GDPR contact export, which will send system message with the link in the end

Available from
v9

Request path

GET [REST API ROOT]/contact/export

Query Parameters

Parameter Type Description
contactId Long The user ID of the contact to perform export for.
notificationRecipient String Active system user witch is going to be used for permission checks, and will get system message.

/content

The content domain contains methods that are used to manage elements in the Content Store

Available from
v1

/store

Example body

{
"name" : "twitter_logo.png",
"contentType" : "image/png",
"content" : "iVBORw0KGgoAAAANSUhEUgAAABUAAAARCAYAAAAyhueAAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAASFJREFUeNqslM0NgkAQhRdiAdiAgQ6468EO1INntQOpwFABdqBe9aAdiIl3twS1AbECfJPMkhVZftSXjJPsDh87z2WsNE1Fb3d3z+POVVQIdQ5ShJhqywdEgEgQQ1qwutsbFT4QM4DXFcALwi3YJqDD2bPx4/PGCg/OSw46NwAFA0nU7d7ObUYAHxF+wYMDUU8jiz19aG9TihEbyuS3oSavNmoT5Sm1thA/CkCLsvJ0In5XdnsIKkv+gCaSGZQ8QF7+AXrST0peBH8Ar9+grKfuS1Mgd/wBjb/0lmChvmBr14GgMy5qoiA/N+zcPSNfPN2fCoVF86KlDQxqvc93tl8DaBxALcAi/qLqKuaWpalAffsOz8iB4ZRSzYIymNJLgAEAYsJkJOLW//gAAAAASUVORK5CYII="
}

Example response

{
    "contentId": "contentstore:/16598/CONTENTSTORE/660624976?contentStoreId=660624976",
    "reference": "660624976"
}

Description

Stores a content element in the Content Store.

Request path

POST [REST API ROOT]/content/store

Query Parameters

Parameter Type Description
None - -

Request Body Type

Attachment content

/delete

Example response

NULL

Description

Deletes a content element in the Content Store.

Request path

DELETE [REST API ROOT]/content/delete

Query Parameters

Parameter Type Description
contentId String -

/draftmessage

Available from
v6

/create

Example body

{
    "id": 18060600,
    "name": "Test Draft Message",
    "externalId": null,
    "messageCategoryId": null,
    "message":
    {
        "subject": "This is draft test",
        "emailBodyText": null,
        "emailBodyHtml": "Test",
        "smsText": null,
        "faxText": null,
        "emailHeaders":
        [
        ],
        "attachments":
        [
        ],
        "attachmentReferences": null,
        "encoding": "ISO-8859-1",
        "encodingSMS": "ISO-8859-1",
        "imageHandlingMode": "none"
    }
}

Example response

{
    "id": 18060677,
    "name": "Test Draft Message 002",
    "externalId": null,
    "messageCategoryId": null,
    "message": {
        "subject": "This is draft test 002",
        "emailBodyText": null,
        "emailBodyHtml": "Test 002",
        "smsText": null,
        "faxText": null,
        "emailHeaders": [],
        "attachments": [],
        "attachmentReferences": null,
        "encoding": "ISO-8859-1",
        "encodingSMS": "ISO-8859-1",
        "imageHandlingMode": "none"
    }
}

Description

Creates a new message as a draft.

Request path

POST [REST API ROOT]/draftmessage/create

Query Parameters

Parameter Type Description
None - -

Request Body Type

DraftMessage

/get

Example response


Response
{
    "id": 18060600,
    "name": "Test",
    "externalId": null,
    "messageCategoryId": null,
    "message": {
        "subject": "Test",
        "emailBodyText": null,
        "emailBodyHtml": "<html><body>Test</body></html>",
        "smsText": null,
        "faxText": null,
        "emailHeaders": [],
        "attachments": [],
        "attachmentReferences": null,
        "encoding": "ISO-8859-1",
        "encodingSMS": "ISO-8859-1",
        "imageHandlingMode": "none"
    }
}

Description

Returns a draft message identified by the specified draft message ID.

Request path

GET [REST API ROOT]draftmessage/get

Query Parameters

Parameter Type Description
draftMessageId Long -

/update

Example body

{
    "id": 18060600,
    "name": "Test Draft Message",
    "externalId": null,
    "messageCategoryId": null,
    "message":
    {
        "subject": "This is draft test",
        "emailBodyText": null,
        "emailBodyHtml": "Test",
        "smsText": null,
        "faxText": null,
        "emailHeaders":
        [
        ],
        "attachments":
        [
        ],
        "attachmentReferences": null,
        "encoding": "ISO-8859-1",
        "encodingSMS": "ISO-8859-1",
        "imageHandlingMode": "none"
    }
}

Example response

NULL

Description

Updates a message draft.

Request path

POST [REST API ROOT]/draftmessage/update

Query Parameters

Parameter Type Description
None - -

Request Body Type

DraftMessage

/delete

Example response

NULL

Description

Deletes a draft message identified by the specified draft message ID.

Request path

DELETE [REST API ROOT]draftmessage/delete

Query Parameters

Parameter Type Description
draftMessageId Long ID of the draft message

/find

Description

Finds draft messages specified by a draft message filter.

Available from
v7

Request path

POST [REST API ROOT]draftmessage/find

Query Parameters

Parameter Type Description
None - -

Request Body Type

draftMessageFilter

/saveAsPreparedMessage

Description

Saves draft message as prepared message. The channel ID is available at "Information" panel for each channel, at "Administration > Channels".

Available from
v9

Request path

GET [REST API ROOT]draftmessage/saveAsPreparedMessage

Query Parameters

Parameter Type Description
draftMessageId Long The draft message to be used in creating the prepared message
groupId Long The id of the group to perform sendout on
channelId Long The channel id associated with the message

/group

The group domain contains all group-related methods.

/clone

Example body

{
"name" : "Group Name",
"description" : "Description of the group",
"email" : "group@test.com",
"includePreparedMessages" : "true",
"includeTestUsers" : "false"
}

Example response

{
  "id": 1800150437,
  "name": "Group Name",
  "description": "Description of the group",
  "email": "group@test.com"
}

Description

Creates a clone of a specific group that already exists in the system. Most of the sendout options and delivery settings are identical for the original and the clone. However, group members are not copied - members of the group are not members of the clone. With CloneOptions you have to specify how and with what mandatory parameters the group will be cloned.

Request path

POST [REST API ROOT]/group/clone

Query Parameters

Parameter Type Description
groupId Long ID of the group to be cloned

Request Body Type

GroupCloneOptions options

/get

Example response

{
    "id": 1800150437,
    "name": "Group Name",
    "description": "Description of the group",
    "email": "group@test.com"
}

Description

Returns the group object of the specified group. The group is identified by group ID.

Request path

GET [REST API ROOT]/group/get

Query Parameters

Parameter Type Description
groupId Long ID of the group to be requested

/findIdsByAttributes

Example body

[{
"name" : " GroupAttributeName ",
"value" : "12345"
}]

Example response

[1800123829]

Description

Returns a list of group IDs for all groups in the system that use the specified group attributes. Group attributes are only available in the group context and consist of a unique name and a value. Please note that attributes like Group Name or Email cannot be used here.

Request path

POST [REST API ROOT]/group/findIdsByAttributes

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of Attributes

/setAttributes

Example body

[{
"name" : "GroupAttributeName",
"value" : "12345"
}]

Example response

[{
    "name": "Test",
    "value": "12345" }, {
    "name": "TestRest",
    "value": "12345"
}]

Description

Creates and updates the group attributes. Existing attributes are overwritten.

Request path

POST [REST API ROOT]/group/setAttributes

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of Attributes

/getAttributes

Example response

[{
    "name": "Test",
    "value": "12345" }, {
    "name": "TestRest",
    "value": "12345"
}]

Description

Provides a list of all group attributes.

Request path

GET [REST API ROOT]/group/getAttributes

Query Parameters

Parameter Type Description
groupId Long ID of the group for which we request the parameters

/overrideGroupSettings

Example response

NULL

Description

Overwrites the existing group settings with the settings template, identified by the settings ID. GroupSettingTemplates predefine several settings in a template. The list of templates available for a system can be requested with the API call. The mechanism for using GroupSettingTemplates is only available in a special configuration.

Request path

POST [REST API ROOT]/group/overrideGroupSettings

Query Parameters

Parameter Type Description
groupId Long ID of the group for which we change the settings
settingsId Long ID of the configuration template

/getPreparedMessages

Example response

[1800197358]

Description

Returns all of the prepared messages for a specific group.

Request path

GET [REST API ROOT]/group/getPreparedMessages

Query Parameters

Parameter Type Description
groupId Long ID of the group for which we request the messages

/getAllGroupSettingsTemplates

Example response

[
  {
    "id": [1002],
    "name": ["Group Template 1"]
  },
  {
    "id": [1003],
    "name": ["Group Template 2"]
  }
]

Description

Gets all GroupSettingsTemplates that are defined in the system. GroupSettingTemplates predefine several settings in a template and can be applied to override the settings of a group with a special API call. The mechanism for using GroupSettingTemplates is only available in a special configuration.

Request path

GET [REST API ROOT]/group/getAllGroupSettingsTemplates

Query Parameters

Parameter Type Description
None - -

/archive

Example body

["1800123820", "1800146953"]

Example response

[{
    "entityKey": "1800123820",
    "code": null,
    "message": null }, {
    "entityKey": "1800146953",
    "code": null,
    "message": null
}]

Description

Archive a list of groups and any dependent subgroups. Other dependent objects, such as triggers and scheduled tasks, are not archived.

Request path

POST [REST API ROOT]/group/archive

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of Long groupIds

/activate

Example body

["1800123820", "1800146953"]

Example response

[{
    "entityKey": "1800123820",
    "code": null,
    "message": null }, {
    "entityKey": "1800146953",
    "code": null,
    "message": null
}]

Description

Activates archived groups.

Request path

POST [REST API ROOT]/group/activate

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of Long groupIds

/landingpage

Available from
v2

The landingpage domain contains methods that can be used to manage landing pages

/find

Example body

Example response

NULL

Description

Request path

POST [REST API ROOT]/landingpage/find

Query Parameters

Parameter Type Description
None - -

Request Body Type

LandingpageFilter

/getStatus

Example response

PUBLISHED

Description

Returns the publishing status of a landing page. Because these pages are usually associated with the lifetime of a particular email campaign, they may have a differing publishing status. Previously published pages that have become inactive because they are no longer valid are sometimes redirected to another default page. Possible states are:

Request path

GET [REST API ROOT]/landingpage/getStatus

Query Parameters

Parameter Type Description
landingpageId Long landingpageId ID of the landing page

/delete

Example response

NULL

Description

Deletes the landing page with the specified landing page ID. It works only if the landing page is inactive.

Request path

DELETE [REST API ROOT]/landingpage/delete

Query Parameters

Parameter Type Description
landingpageId Long landingpageId ID of the landing page

/deleteMany

Example body

["626","627"]

Example response

NULL

Description

Deletes the landing pages with the specified landing page IDs. It works only if landing pages are inactive.

Request path

POST [REST API ROOT]/landingpage/deleteMany

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of Long landingpageIds

/membership

The membership domain contains methods that are used to manage group memberships.

/subscribe

Example response

NULL

Description

Subscribes a user to a group. With this call, the subscription is handled as a self subscription. Depending on the subscription mode used, the user may have to confirm the subscription (opt in) and may be notified of the successful subscription.

SubscriptionMode Description
CONFIRMED_OPT_IN New contacts receive a welcome message via email when they are added to the group. Despite the label used for this value, the contact does not need to confirm the subscription. A single opt-in subscription.
DOUBLE_OPT_IN New contacts receive an invitation to join the group via email. The contact must accept the invitation before they are added to the group. A double opt-in subscription.
OPT_IN New contacts are added to the group without notification.
Available from
v2

Request path

POST [REST API ROOT]/membership/subscribe

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group
subscriptionMode SubscriptionMode See above

/subscribeByEmail

Example response

NULL

Description

Subscribes a user to a group. Works like the subscribe call but uses an email address instead of a user ID.

SubscriptionMode Description
CONFIRMED_OPT_IN New contacts receive a welcome message via email when they are added to the group. Despite the label used for this value, the contact does not need to confirm the subscription. A single opt-in subscription.
DOUBLE_OPT_IN New contacts receive an invitation to join the group via email. The contact must accept the invitation before they are added to the group. A double opt-in subscription.
OPT_IN New contacts are added to the group without notification.
Available from
v2

Request path

POST [REST API ROOT]/membership/subscribeByEmail

Query Parameters

Parameter Type Description
email String Email of the user
groupId Long ID of the group
subscriptionMode SubscriptionMode See above

/unsubscribe

Example response

NULL

Description

Unsubscribes a user from a group. A notification is sent to the manager.

Available from
v2

Request path

POST [REST API ROOT]/membership/unsubscribe

Query Parameters

Parameter Type Description
userId String ID of the user
groupId Long ID of the group

/unsubscribeFromMessage

Example response

NULL

Description

Unsubscribes a user from a group. The unsubscription is associated with a specific message. Notification is sent to the group manager. Returns success only when the user is unsubscribed from the group and the unsubscription is associated with the specified message.

Available from
v5

Request path

POST [REST API ROOT]/membership/unsubscribeFromMessage

Query Parameters

Parameter Type Description
userId String ID of the user
groupId Long ID of the group
messageId Long ID of the message

/unsubscribeByEmail

Example response

NULL

Description

Unsubscribes a user from a group based on the email address. An unsubscribe confirmation email is sent to the user.

Available from
v5

Request path

POST [REST API ROOT]/membership/unsubscribeByEmail

Query Parameters

Parameter Type Description
email String Email of the user
groupId Long ID of the group

/unsubscribeFromMessageByEmail

Example response

NULL

Description

Unsubscribes a user from a group based on an email address. The unsubscription is associated with a specific message. An unsubscribe confirmation email is sent to the user. Returns success only when the user is unsubscribed from the group and the unsubscription is associated with the specified message.

Available from
v5

Request path

POST [REST API ROOT]/membership/unsubscribeFromMessageByEmail

Query Parameters

Parameter Type Description
email String Email of the user
groupId Long ID of the group
messageId Long ID of the message

/create

Example response

{
    "userId": 18076325029,
    "groupId": 1800116178,
    "attributes": []
}

Description

Creates a new membership (meaning the user is subscribed to a group). This call differs from subscribe, in that notification is not sent.

Available from
v2

Request path

GET [REST API ROOT]/membership/create

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group

/get

Example response

{
    "userId": 18223800009,
    "groupId": 1800190005,
    "attributes": [{
        "name": "member.bounceCounter",
        "value": "0"
    }, {
        "name": "member.type",
        "value": "normal"
    }, {
        "name": "member.readMode",
        "value": "mail"
    }, {
        "name": "member.creationDate",
        "value": "2015-07-21 16:10:30.0"
    }, {
        "name": "member.bounced",
        "value": "false"
    }, {
        "name": "member.role",
        "value": "member"
    }, {
        "name": "member.messageCounter",
        "value": "0"
    }, {
        "name": "member.systemWideDeactivated",
        "value": "false"
    }]
}

Description

Retrieves membership context of a user identified by the userId in a group identified by groupId.

Available from
v7

Request path

GET [REST API ROOT]/membership/get

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group

/getByEmail

Example response

{
    "userId": 18223800009,
    "groupId": 1800190005,
    "attributes": [{
        "name": "member.bounceCounter",
        "value": "0"
    }, {
        "name": "member.type",
        "value": "normal"
    }, {
        "name": "member.readMode",
        "value": "mail"
    }, {
        "name": "member.creationDate",
        "value": "2015-07-21 16:10:30.0"
    }, {
        "name": "member.bounced",
        "value": "false"
    }, {
        "name": "member.role",
        "value": "member"
    }, {
        "name": "member.messageCounter",
        "value": "0"
    }, {
        "name": "member.systemWideDeactivated",
        "value": "false"
    }]
}

Description

Retrieves membership context of a user identified by email in a group identified by groupId.

Available from
v7

Request path

GET [REST API ROOT]/membership/getByEmail

Query Parameters

Parameter Type Description
email String Email of the user
groupId Long ID of the group

/delete

Example response

{
    "userId": 18076325029,
    "groupId": 1800116178,
    "attributes": []
}

Description

Creates a new membership (meaning the user is subscribed to a group). This call differs from subscribe in that a notification is not sent.

Available from
v2

Request path

DELETE [REST API ROOT]/membership/delete

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group

/findAll

Example response

[{
    "userId": 18061450504,
    "groupId": 1800116178,
    "attributes": [] }, {
    "userId": 18061450504,
    "groupId": 1800138927,
    "attributes": []
}]

Description

Returns a list of membership objects, one membership object for each group in which the user is a member.

Available from
v2

Request path

GET [REST API ROOT]/membership/findAll

Query Parameters

Parameter Type Description
userId Long ID of the user

/findAllByEmail

Example response

[{
    "userId": 18061450504,
    "groupId": 1800116178,
    "attributes": [] }, {
    "userId": 18061450504,
    "groupId": 1800138927,
    "attributes": []
}]

Description

Returns a list of membership objects for the user. One membership object for each group in which the user is a member. The user is identified by the email.

Available from
v2

Request path

GET [REST API ROOT]/membership/findAllByEmail

Query Parameters

Parameter Type Description
email String Email of the user

/getAttributes

Example response

[{
    "name": "attribute1",
    "value": "0001" }, {
    "name": "attribute2",
    "value": "0002"
}]

Description

Returns a collection of member attributes for a user within the specified group. Member attributes are used to save information for an individual user, but in the context of a specific group. A member attribute contains a specific value for each recipient.

Available from
v2

Request path

GET [REST API ROOT]/membership/getAttributes

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group

/getAttributesByEmail

Example response

[{
    "name": "attribute1",
    "value": "0001" }, {
    "name": "attribute2",
    "value": "0002"
}]

Description

Returns a collection of member attributes for a user within the specified group. Member attributes are used to save information for an individual user, but in the context of a specific group. A member attribute contains a specific value for each recipient. The user is identified by the email.

Available from
v2

Request path

GET [REST API ROOT]/membership/getAttributesByEmail

Query Parameters

Parameter Type Description
email String Email of the user
groupId Long ID of the group

/updateAttributes

Example body

[{
"name" : "attribute1",
"value" : "0001"
}]

Example response

NULL

Description

Updates the member attributes for a user within a certain group if the user is a member of the group. If an attribute already exists, the value will be updated; if not, a new attribute will be created. If an existing member attribute is not in the attribute list being sent in the call, it will be deleted.

Available from
v2

Request path

POST [REST API ROOT]/membership/updateAttributes

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group

Request Body Type

list of Attributes

/replaceAttributes

Example body

[{
"name" : "attribute1",
"value" : "0001"
},
{
"name" : "attribute2",
"value" : "0002"
}]

Example response

NULL

Description

Replaces the member attributes for a contact within a specific group where the contact is a member

Available from
v2

Request path

POST [REST API ROOT]/membership/replaceAttributes

Query Parameters

Parameter Type Description
userId Long ID of the user
groupId Long ID of the group

Request Body Type

list of Attributes

/message

The message domain contains methods that can be used to manage email and SMS messages

/getHistorical

Description

Operator wants to fetch a specific (group) message as it was sent to a defined contact, including resolved personalizations.

Available from
v8

Request path

GET [REST API ROOT]/message/getHistorical

Query Parameters

Parameter Type Description
messageId Long ID of the (sent) message to fetch.
contactId Long ID of the contact for whom the message shall be personalized.

/sendSingle

Example body

{
"parameters":
    [{"name" : "Parameter Name 1","value" : "Parameter Value 1"
    }, {"name" : "Parameter Name 2","value": "Parameter Value 2"
    }], "attachments": [{"name" : "image.png","contentType" : "application/png","content" : "BASE64ENCODING"}]
}


Example response

NULL

Description

Sends a prepared message as a single message to a specific user. Prepared messages are saved copies of a message to which a group has been assigned. They are used to automatically send messages to single users (e.g. for birthday messages). Because sendouts are always managed via a group, this method automatically adds the user who receives the email to the group of the prepared message. Be aware that there are legal issues associated with contacting users. The system usually provides automated opt-in settings to satisfy these requirements. However, this particular method does not include an opt-in process. The method changes memberships without any additional processes. You may avoid legal complications if the user is already part of the group that is sending the single message (and has successfully completed an opt-in process) or if the group is only used for sending single messages.

Available from
v1

Request path

POST [REST API ROOT]/message/sendSingle

Query Parameters

Parameter Type Description
recipientId Long ID of the user
messageId Long ID of the message

Request Body Type

MessageContent additionalContent

/sendTransactional

Example body

{
"parameters":
    [{"name" : "Parameter Name 1","value" : "Parameter Value 1"
    }, {"name" : "Parameter Name 2","value": "Parameter Value 2"
    }], "attachments": [{"name" : "image.png","contentType" : "application/png","content" : "BASE64ENCODING"}]
}


Example response

NULL

Description

Sends a previously prepared message template as transactional message.

Available from
v1

Request path

POST [REST API ROOT]/message/sendTransactional

Query Parameters

Parameter Type Description
recipientId Long ID of the user
messageId Long ID of the message
externalTransactionFormula String External transactional identifier

Request Body Type

MessageContent additionalContent

/getUsedPersonalizations

Example response

["user.FirstName"]

Description

Returns the names of all user and group attributes that are referenced within the header and content area of a prepared message. The reference to the attributes is a personalization placeholder in the body of the message. All of these placeholders are replaced with individual user or message information during sendout. Be aware that this method does not return member attributes.

Available from
v1

Request path

GET [REST API ROOT]/message/getUsedPersonalizations

Query Parameters

Parameter Type Description
messageId Long ID of the message

/getManyUsedPersonalizations

Example body

["1800249553","1800202306"]

Example response

[{
    "entityKey": "1800249553",
    "code": null,
    "message": "user.FirstName"
}, {
    "entityKey": "1800202306",
    "code": null,
    "message": ""
}]

Description

Returns the names of all user and group attributes that are referenced within the header and content area of a prepared message. The reference to the attributes is a personalization placeholder in the body of the message. All of these placeholders are replaced with individual user or message information during sendout. Be aware that this method does not return member attributes.

Available from
v1

Request path

GET [REST API ROOT]/message/getUsedPersonalizations

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of String messageIds

/validate

Example response

{
    "entityKey": "1800249570",
    "code": "ARCHIVED_ATTRIBUTE",
    "message": "Message contains archived attribute(s) user.CustomAttribute.Attribute1."
}

Description

Validates a prepared message for following functionality: check that message is valid (InvalidObjectError -> objecttype message), check that message does not contain invalid content store items, check that message does not use archived Attributes (InvalidObjectError -> objecttype attribute).

Available from
v1

Request path

GET [REST API ROOT]/message/validate

Query Parameters

Parameter Type Description
messageId Long ID of the message

/validateMany

Example body

["1800249570","1800202306"]

Example response

[{
    "entityId": 1800249570,
    "errorCode": "ARCHIVED_ATTRIBUTE",
    "errorMessage": "Message contains archived attribute(s) user.CustomAttribute.Attribute1"
}, {
    "entityId": 1800202306,
    "errorCode": null,
    "errorMessage": null
}]


Description

Validates a list of messages for following functionality: checks that the message is valid (InvalidObjectError -> objecttype message), checks that the message does not contain any invalid content store items, checks that the message does not use archived Attributes (InvalidObjectError -> objecttype attribute).

Available from
v1

Request path

POST [REST API ROOT]/message/validateMany

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of Long messageIds

/getStatistics

Example response

{
    "messageId": 1800228386,
    "messageName": "[Test_Export] Campaign Winter Bottom March 2014",
    "messageSubject": "Winter Bottom",
    "externalMessageId": "ExternalWinter",
    "groupId": 1800138893,
    "groupName": "Test_Export",
    "groupSize": 20,
    "sendoutStartDate": 1404721300908,
    "sendoutEndDate": 1404721301837,
    "selectionName": null,
    "statisticValues": [{
        "name": "sentsPerFormat",
        "value": "email-html-multipart=16" }, {
        "name": "uniqueClicker",
        "value": "5" }, {
        "name": "uniqueConfirmedOpener",
        "value": "16" }, {
        "name": "openingRate",
        "value": "100.0" }, {
        "name": "hardBounces",
        "value": "0" }, {
        "name": "category",
        "value": "Winter Bottom" }, {
        "name": "durationMs",
        "value": "929" }, {
        "name": "majorSent",
        "value": "16" }, {
        "name": "skipped",
        "value": "4"     }, {
        "name": "accepted",
        "value": "16" }, {
        "name": "converter",
        "value": "0" }, {
        "name": "fromAddress",
        "value": "test@test.com"  }, {
        "name": "groupSize",
        "value": "20" }, {
        "name": "attachments",
        "value": "" }, {
        "name": "messageSize",
        "value": "7789" }, {
        "name": "clickRate",
        "value": "31.25" }]
}

Description

Retrieves statistical data for a sent message.

Available from
v5

Request path

GET [REST API ROOT]/message/getStatistics

Query Parameters

Parameter Type Description
messageId Long ID of the message

/getStatisticsByExternalMessageId

Example response

{
    "messageId": 1800228386,
    "messageName": "[Test_Export] Campaign Winter Bottom March 2014",
    "messageSubject": "Winter Bottom",
    "externalMessageId": "ExternalWinter",
    "groupId": 1800138893,
    "groupName": "Test_Export",
    "groupSize": 20,
    "sendoutStartDate": 1404721300908,
    "sendoutEndDate": 1404721301837,
    "selectionName": null,
    "statisticValues": [{
        "name": "sentsPerFormat",
        "value": "email-html-multipart=16" }, {
        "name": "uniqueClicker",
        "value": "5" }, {
        "name": "uniqueConfirmedOpener",
        "value": "16" }, {
        "name": "openingRate",
        "value": "100.0" }, {
        "name": "hardBounces",
        "value": "0" }, {
        "name": "category",
        "value": "Winter Bottom" }, {
        "name": "durationMs",
        "value": "929" }, {
        "name": "majorSent",
        "value": "16" }, {
        "name": "skipped",
        "value": "4"     }, {
        "name": "accepted",
        "value": "16" }, {
        "name": "converter",
        "value": "0" }, {
        "name": "fromAddress",
        "value": "test@test.com"  }, {
        "name": "groupSize",
        "value": "20" }, {
        "name": "attachments",
        "value": "" }, {
        "name": "messageSize",
        "value": "7789" }, {
        "name": "clickRate",
        "value": "31.25" }]
}

Description

Retrieves statistical data for a sent message that is identified by the external message ID.

Available from
v5

Request path

GET [REST API ROOT]/message/getStatisticsByExternalMessageId

Query Parameters

Parameter Type Description
externalMessageId String extenralMessageId External ID of the message

/find

Example body

{
  "authorId":null,
  "authorName":null,
  "externalMessageId":null,
  "groupCategoryId":null,
  "groupCategoryName":null,
  "groupId":6,"groupName":null,
  "messageCategoryId":null,
  "messageName":null,
  "sendoutDateFrom":"2017-12-01T00:00:00",
  "sendoutDateTo":"2017-12-31T00:00:00",
  "status":null,
  "subjectLine":null,
  "type":null
}

Example response

<messageSummary>
    <authorId>12386215766</authorId>
    <authorName>Mustermann,Daniel</authorName>
    <groupId>1200550565</groupId>
    <id>1202033667</id>
    <isArchived>false</isArchived>
    <isSystemMessage>false</isSystemMessage>
    <messageName>Copy of support test</messageName>
    <originalMessageId>1202011446</originalMessageId>
    <status>SCHEDULED</status>
    <subjectLine>test</subjectLine>
    <type>NORMAL</type>
    <sendoutDate>2017-12-18T15:52:22Z</sendoutDate>
    <sendoutStartDate>null</sendoutStartDate>
    <sendoutEndDate>null</sendoutEndDate>
    <transferDate>null<transferDate>
    <transferStartDate>null</transferStartDate>
    <transferEndDate>null</transferEndDate>
</messageSummary>

Description

Returns a list of message summary objects that contain information about the messages that match the filter criteria. You can use this method to retrieve information about a message that has been sent or saved as a prepared message.

Available from
v7

Request path

GET [REST API ROOT]/message/find

Query Parameters

Parameter Type Description
filter MessageFilter A filter object that determines which messages are included in the list of returned message summary objects.

/getTimeDistribution

Description

Retrieves statistical time distribution information for a specific sent message.

Available from
v7

Request path

GET [REST API ROOT]/message/getTimeDistribution

Query Parameters

Parameter Type Description
messageId Long ID of the message
interval

/getTimeDistributionByExternalId

Description

Retrieves statistical time distribution information for a specific sent message.

Available from
v7

Request path

GET [REST API ROOT]/message/getTimeDistributionByExternalId

Query Parameters

Parameter Type Description
externalMessageId String extenralMessageId External ID of the message

/meta

The meta domain contains methods that define your system.

/createAttributeDefinitions

Example body

[{
"name": "attributename",
"type": "STRING",
"enumerationValues":
[
"value1",
"value2",
"value3"
],
"active": "true"
}]

Example response

NULL

Description

Creates a new data field (custom user attribute) where information about users can be stored. With the standard setup, you are permitted to create a limited number of custom attributes with different data types. Each custom user attribute has a unique name. If an attribute is no longer needed, it may be archived. Please contact your customer support representative if you need to delete an attribute.

Available from
v1

Request path

POST [REST API ROOT]/meta/createAttributeDefinitions

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of AttributeDefinition

/getAttributeDefinitions

Example response

[{
    "name": "NumberName",
    "type": "NUMBER",
    "enumerationValues": null,
    "active": null },{
    "name": "StringName",
    "type": "STRING",
    "enumerationValues": ["1"],
    "active": null
}]

Description

Returns a list of all active custom attributes that are defined for the users. Attributes with the status 'archived' or 'system' are not included in the list.

Available from
v1

Request path

GET [REST API ROOT]/meta/getAttributeDefinitions

Query Parameters

Parameter Type Description
None - -

/archiveAttributeDefinitions

Example body

["attributename"]

Example response

NULL

Description

Archives custom attributes. An archived attribute is still stored in the system. The attributes can still be in use for existing messages and sendouts, but they are not available in the GUI message creation process (i.e. personalization builder).

Available from
v1

Request path

POST [REST API ROOT]/meta/archiveAttributeDefinitions

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of String attributeNames

/activateAttributeDefinitions

Example body

["attributename"]

Example response

NULL

Description

Reactivates archived custom attributes that are named in the parameter list. After activation, they can be used in personalization during message composition process.

Available from
v1

Request path

POST [REST API ROOT]/meta/activateAttributeDefinitions

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of String attributeNames

/mergeAttributeDefinitions

Example body

[{
"name": "attributename",
"type": "STRING",
"enumerationValues":
[
"value1",
"value2",
"value3"
],
"active": "true"
}]

Example response

NULL

Description

Updates the list of custom attributes that are available on the interface. It is used to archive, activate, and create custom attributes. This call affects every custom attribute that is available in your system. It updates all of the attributes that are available for saving user data and reusing it in a different context. If an attribute is not mentioned, it is automatically deactivated. Errors and changes are delivered at the end of the process when all attributes are processed. The update cannot be used in an interactional way. Errors do not stop the update process. The attribute with the error is skipped and the process continues with the next attribute. It is not possible to change the attribute name, type, or enumeration with this method. The results of the merge method are as follows: * New attributes are created if the attribute is listed and did not exist before. * Custom attributes that are not listed are archived. * Custom attributes that are listed and are identical to the ones that already exist have no state change. * Custom attributes that are archived and not listed remain archived. * Custom attributes that have a state other than archived/active generate an error and remain unchanged.

Available from
v1

Request path

POST [REST API ROOT]/meta/mergeAttributeDefinitions

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of AttributeDefinition

/createLinkCategories

Example body

[{
"id": "",
"name": "TestApi",
"description" : "Rest Api Call",
"pattern": "TestAp[i]"
}]

Example response

NULL

Description

Creates new link categories. Link categories are automatically assigned to a link via a regex pattern. The link categories group together different links for statistical purposes and can be used to trigger automated processes when a link of a certain category is clicked. The name and pattern are mandatory inputs for the category. The ID is automatically assigned by the system.

Available from
v1

Request path

POST [REST API ROOT]/meta/createLinkCategories

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of LinkCategory categories

/getLinkCategories

Example body

[{
    "id": 1800000093,
    "name": "Winter Bottom Game",
    "description": null,
    "pattern": "winterbottomgame"
}]

Example response

NULL

Description

Returns a list of all currently defined active link categories.

Available from
v1

Request path

POST [REST API ROOT]/meta/getLinkCategories

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of LinkCategory categories

/updateLinkCategories

Example body

{
"id": "1800000190",
"name": "TestApiUpdate",
"description" : "A test update from Rest Api Call",
"pattern": "TestUpdateAp[i]"
}

Example response

NULL

Description

Updates an existing link category identified by the parameter category.

Available from
v1

Request path

POST [REST API ROOT]/meta/updateLinkCategory

Query Parameters

Parameter Type Description
None - -

Request Body Type

LinkCategory category

/deleteLinkCategories

Example body

["CategoryName"]

Example response

NULL

Description

Updates an existing link category identified by the parameter category.

Available from
v1

Request path

POST [REST API ROOT]/meta/deleteLinkCategories

Query Parameters

Parameter Type Description
None - -

Request Body Type

list of String categoryNames

/attachTags

Example body


Example response


Description

Adds tags to the entity specified by the entity type and entity ID.

Available from
v6

Request path

POST [REST API ROOT]/meta/attachTags

Query Parameters

Parameter Type Description
entityId Long The entity ID.
entityType String The entity type. A list of available entity types is found in the description of the TaggedEntity type object.
tags String A list of tags to add to the entity.

/detachTags

Example body


Example response


Description

Removes tags from the entity specified by the entity type and entity ID.

Available from
v6

Request path

POST [REST API ROOT]/meta/detachTags

Query Parameters

Parameter Type Description
entityId Long The entity ID.
entityType String The entity type. A list of available entity types is found in the description of the TaggedEntity type object.
tags String A list of tags to add to the entity.

/findByTags

Example body


Example response


Description

Locates entities that are tagged with a specific label or combination of labels.

Available from
v6

Request path

POST [REST API ROOT]/meta/findByTags

Query Parameters

Parameter Type Description
tags String A list of search terms for locating entities with matching tags. When more than one search term is entered in the parameter, only entities with labels that match all search terms are returned.
entityType String Reference to an entity type. When used, only entities of the given type are considered for the search.

/getTags

Example body


Example response


Description

Returns a list of tags assigned to an entity.

Available from
v6

Request path

POST [REST API ROOT]/meta/getTags

Query Parameters

Parameter Type Description
entityId Long The entity ID.
entityType String The entity type. A list of available entity types is found in the description of the TaggedEntity type object.

/preparedmessage

/find

Description

Returns list of message summary objects that contain information about prepared messages that match the filter criteria.

Available from
v7

Request path

POST [REST API ROOT]/preparedmessage/find

Query Parameters

Parameter Type Description
filter PreparedMessageFilter A filter object that determines which messages are included in the list of returned prepared message summary objects.

/send

Description

Send prepared messages based on a given send datetime

Available from
v9

Request path

GET [REST API ROOT]/preparedmessage/send

Query Parameters

Parameter Type Description
preparedMessageId Long The id of the prepared message you want to send.
sendDateTime Datetime Sendout time as timestamp.
processingDateTime String The preprocessing date time (optional)
selectionId Long A selection id to associate with the sendout (optional).

/process

The process domain contains methods that let you interact with a process in Mapp Engage.

/getDetails

Example response


Description

Returns information for the process identified by the specified process ID.

Available from
v7

Request path

GET [REST API ROOT]/process/getDetails

Query Parameters

Parameter Type Description
None - -

/applyAction

Example response


Description

Changes the status of an existing process.

Available from
v7

Request path

GET [REST API ROOT]/process/applyAction

Query Parameters

Parameter Type Description
None - -

/relatedData

The relatedData domain contains methods that are used to manage records stored in Related Data.

Available from
v4

/createRecord

Example body

{
  "datasetName": "workflow",
  "key": "11107",
  "data": [
    {
      "name": "ID",
      "value": "90900"
    },
    {
      "name": "Category",
      "value": "Email Marketing"
    }
  ]
}

Example response

HTTP/1.1 204 No Content

Example response

{
   "errorActor": "CLIENT",
   "errorCode": "NO_SUCH_OBJECT",
   "message": "RelatedDataList with dataSetName=myproducts does not exist.",
   "objectType": "RelatedDataList",
   "propertyName": "dataSetName",
   "propertyValue": "myproducts"
}

Example response

{
   "errorActor": "CLIENT",
   "errorCode": "UNEXPECTED_ERROR",
   "message": "com.ecircle.das.DASSystemException: 
   No columns to insert in dataset myproducts",
   "errorId": null
}

Description

Adds a record to a data set. The data set is defined in the type RelatedDataRecord. Dataset has to be created in "Attributes > Related Data". Please make sure dataset has at least one column.

Request path

POST [REST API ROOT]/relatedData/createRecord

Query Parameters

Parameter Type Description
None - -

Request Body Type

RelatedDataRecord record

/updateRecord

Example body

{"datasetName": "workflow",
 "key": "11107",
 "data":
    [{
        "name": "ID",
        "value": "90900"
    },
            {   "name": "Category",
        "value": "Email Marketing"
    }]
}

Example response

NULL

Description

Updates all or specific records for a key in a related data set. Dataset has to be created in "Attributes > Related Data". Please make sure dataset has at least one column.

Request path

POST [REST API ROOT]/relatedData/updateRecord

Query Parameters

Parameter Type Description
None - -

Request Body Type

RelatedDataRecordAndFilter

/deleteRecord

Example body

{"datasetName": "workflow",
 "key": "11107",
 "filter":
    [{
        "name": "ID",
        "value": "90900"
    }]
}

Example response

NULL

Description

Delete a records in a related data set.

Request path

POST [REST API ROOT]/relatedData/deleteRecords

Query Parameters

Parameter Type Description
None - -

Request Body Type

RelatedDataFilter

/system

The system domain contains methods that return information about the current version of the system in use.

/getApiVersion

Example response

0.95

Description

Returns information about the API version currently in use.

Available from
v1

Request path

GET [REST API ROOT]/system/getApiVersion

Query Parameters

Parameter Type Description
None - -

/getEcmVersion

Example response

Build 6.90.554.7

Description

Returns information about the API version currently in use.

Available from
v1

Request path

GET [REST API ROOT]/system/getEcmVersion

Query Parameters

Parameter Type Description
None - -

/systemuser

SystemUser contains all of the system user-related methods such as editing, deleting, and creating a system user.

/create

Description

Creates the new system user in system.

Available from
v8

Request path

POST [REST API ROOT]/systemuser/create

Query Parameters

Parameter Type Description
createContact Boolean create contact for the user
suppressSystemMessage Boolean send/not send the system message to the user

Request Body Type

SystemUser

/get

Description

Retrieves the system user identified by the specified system user ID, external ID, or email address.

Available from
v8

Request path

GET [REST API ROOT]/systemuser/get

Query Parameters

Parameter Type Description
systemuserId Long ID of the user
email String Email of the user
externalId String External ID of the user

/update

Description

Updates the existing system user in the system.

Available from
v8

Request path

POST [REST API ROOT]/systemuser/update

Query Parameters

Parameter Type Description
None - -

Request Body Type

SystemUser

/delete

Description

Deletes the system user identified by the specified system user ID, external ID, or email address.

Available from
v8

Request path

DELETE [REST API ROOT]/systemuser/delete

Query Parameters

Parameter Type Description
systemuserId Long ID of the user
email String Email of the user
externalId String External ID of the user

/updatePassword

Example body

{
    "systemUserId":1234,
    "password":"abcd1234"
}


Description

Updates the system user password identified by the specified system user ID

Available from
v9

Request path

POST [REST API ROOT]/systemuser/updatePassword

Query Parameters

Parameter Type Description

/user

The user domain contains methods for contact management.

/create

Example body

[{
"name" : "user.lastname",
"value" : "Smith"
},
{
"name" : "DateOfBirth",
"value" : "1950-05-05"
}]

Example response

{
   "id": 17,
   "email": "test@test.com",
   "mobileNumber": null,
   "identifier": null
}

Description

Creates a new user. Requires either an email or a mobile number since these fields are used as the unique user identifier in the system.

Available from
v1

Request path

POST [REST API ROOT]/user/create

Query Parameters

Parameter Type Description
email String Email for the user
mobileNumber String MobileNumber Mobile number of the user

Request Body Type

list of Attributes

/get

Example response

{
    "id": 18067305231,
    "email": "test@test.com",
    "mobileNumber": null,
    "identifier": null
}

Description

Returns the user identified by the specified user ID.

Available from
v1

Request path

GET [REST API ROOT]/user/get

Query Parameters

Parameter Type Description
userId Long ID of the user

/getByEmail

Example response

{
    "id": 18067305231,
    "email": "test@test.com",
    "mobileNumber": null,
    "identifier": null
}

Description

Returns the user identified by the specified email address.

Available from
v1

Request path

GET [REST API ROOT]/user/getByEmail

Query Parameters

Parameter Type Description
email String Email of the user

/getByIdentifier

Example response

{
    "id": 18067305231,
    "email": "test@test.com",
    "mobileNumber": null,
    "identifier": null
}

Description

Returns the user identified by the specified identifier. If there are more users with the same identifier, the response refers to the last user where this identifier has been assigned.

Available from
v4

Request path

GET [REST API ROOT]/user/getByIdentifier

Query Parameters

Parameter Type Description
identifier String Identifier identifier of the user

/getByMobileNumber

Example response

{
    "id": 18067305231,
    "email": "test@test.com",
    "mobileNumber": null,
    "identifier": null
}

Description

Returns the user identified by the specified identifier. If there are more users with the same identifier, the response refers to the last user where this identifier has been assigned.

Available from
v7

Request path

GET [REST API ROOT]/user/getByMobileNumber

Query Parameters

Parameter Type Description
mobileNumber String mobileNumber mobileNumber of the user

/getProfile

Example response

[{
    "name": "user.ISOLanguageCode",
    "value": "it" }, {
    "name": "user.Email",
    "value": "test@test.com" }, {
    "name": "user.EmailDomain",
    "value": "test.de" }, {
    "name": "user.LastName",
    "value": "Cloned" }, {
    "name": "user.FirstName",
    "value": "Test" }, {
    "name": "user.ISOCountryCode",
    "value": "IT" }
}]


Description

Returns the user's profile (only attributes with a value are shown). The profile consists of attributes that contain user data. All attributes can be accessed system-wide.

Available from
v1

Request path

GET [REST API ROOT]/user/getProfile

Query Parameters

Parameter Type Description
userId String userId ID of the user

/getProfileByEmail

Example response

[{
    "name": "user.ISOLanguageCode",
    "value": "it" }, {
    "name": "user.Email",
    "value": "test@test.com" }, {
    "name": "user.EmailDomain",
    "value": "test.de" }, {
    "name": "user.LastName",
    "value": "Cloned" }, {
    "name": "user.FirstName",
    "value": "Test" }, {
    "name": "user.ISOCountryCode",
    "value": "IT" }
}]


Description

Returns the user's profile, this is identified by the email address.

Available from
v2

Request path

GET [REST API ROOT]/user/getProfileByEmail

Query Parameters

Parameter Type Description
email String Email of the user

/getProfileByMobileNumber

Example response

[{
    "name": "user.ISOLanguageCode",
    "value": "it" }, {
    "name": "user.Email",
    "value": "test@test.com" }, {
    "name": "user.EmailDomain",
    "value": "test.de" }, {
    "name": "user.LastName",
    "value": "Cloned" }, {
    "name": "user.FirstName",
    "value": "Test" }, {
    "name": "user.ISOCountryCode",
    "value": "IT" }
}]


Description

Returns the user's profile, identified by the mobile number

Available from
v2

Request path

GET [REST API ROOT]/user/getProfileByMobileNumber

Query Parameters

Parameter Type Description
mobileNumber String mobileNumber mobile number of the user

/updateProfile

Example body

[{
"name" : "user.firstname",
"value" : "FirstName"
},
{
"name" : "user.lastname",
"value" : "LastName"
}]

Example response

NULL

Description

Updates the user's profile (data stored in the attributes) with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).

Available from
v1

Request path

POST [REST API ROOT]/user/updateProfile

Query Parameters

Parameter Type Description
userId Long ID of the user

Request Body Type

list of Attributes

/updateProfileByEmail

Example body

[{
"name" : "user.firstname",
"value" : "FirstName"
},
{
"name" : "user.lastname",
"value" : "LastName"
}]

Example response

NULL

Description

Updates a user identified via email. Updates all data stored in the attributes with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).

Available from
v2

Request path

POST [REST API ROOT]/user/updateProfileByEmail

Query Parameters

Parameter Type Description
email String Email of the user

Request Body Type

list of Attributes

/updateProfileByMobileNumber

Example body

[{
"name" : "user.firstname",
"value" : "FirstName"
},
{
"name" : "user.lastname",
"value" : "LastName"
}]

Example response

NULL

Description

Updates a user identified via mobile number. Updates all data stored in the attributes with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).

Available from
v7

Request path

POST [REST API ROOT]/user/updateProfileByMobileNumber

Query Parameters

Parameter Type Description
mobileNumber String mobile number of the user

Request Body Type

list of Attributes

/replaceProfile

Example body

[{
"name" : "user.firstname",
"value" : "FirstName"
},
{
"name" : "user.lastname",
"value" : "LastName"
}]

Example response

NULL

Description

Replaces all attribute values for a specific user. All attribute values that are transmitted with the method are added and replace any existing values. Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).

Available from
v2

Request path

POST [REST API ROOT]/user/replaceProfile

Query Parameters

Parameter Type Description
userId Long ID of the user

Request Body Type

list of Attributes

/replaceProfileByEmail

Example body

[{
"name" : "user.firstname",
"value" : "FirstName"
},
{
"name" : "user.lastname",
"value" : "LastName"
}]

Example response

NULL

Description

Replaces all attribute values for a user identified via email. All attribute values that are transmitted with the method are added and replace any existing values. Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).

Available from
v2

Request path

POST [REST API ROOT]/user/replaceProfileByEmail

Query Parameters

Parameter Type Description
email String Email of the user

Request Body Type

list of Attributes

/replaceProfileByMobileNumber

Example body

[{
"name" : "user.firstname",
"value" : "FirstName"
},
{
"name" : "user.lastname",
"value" : "LastName"
}]

Example response

NULL

Description

Replaces all attribute values for a user identified via mobile number. All attribute values that are transmitted with the method are added and replace any existing values. Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).

Available from
v2

Request path

POST [REST API ROOT]/user/replaceProfileByMobileNumber

Query Parameters

Parameter Type Description
mobileNumber String mobile number of the user

Request Body Type

list of Attributes

/delete

Example response

NULL

Description

Deletes the user identified by the specified ID.

Available from
v1

Request path

DELETE [REST API ROOT]/user/delete

Query Parameters

Parameter Type Description
userId Long userId ID of the user

/deleteByEmail

Example response

NULL

Description

Deletes the user identified by the email address.

Available from
v1

Request path

DELETE [REST API ROOT]/user/deleteByEmail

Query Parameters

Parameter Type Description
email String Email of the user

/deleteByMobileNumber

Example response

NULL

Description

Deletes the user identified by the mobile number.

Available from
v7

Request path

DELETE [REST API ROOT]/user/deleteByMobileNumber

Query Parameters

Parameter Type Description
mobileNumber String mobile number of the user

/getMessageHistory

Example response

[
  {
    "messageID": [354476555],
    "externalTransactionId": {},
    "externalMessageID": {},
    "messageName": ["Test"],
    "messageSubject": ["Test"],
    "groupId": [353599854],
    "groupName": ["Test"],
    "groupEmail": ["test@test.com"],
    "sendDate": [1491216661590],
    "messageType": ["single"],
    "status": ["Sent"],
    "clicked": [true],
    "opened": [false]
  }
]

Description

Retrieves the message history for a recipient for a set time frame. The maximum time frame is 31 days. The maximum number of messages returned is 5000. sendDate is presented as Datetime

Available from
v6

Request path

GET [REST API ROOT]/user/getMessageHistory

Query Parameters

Parameter Type Description
userId Long Start date of time frame in ISO 8601 date time format.
fromDate String Start date of time frame in ISO 8601 date time format.
toDate String End date of time frame in ISO 8601 date time format.

SOAP API

ROOT ENDPOINT
https://cook.shortest-route.com/central_support/api/soap/v10/ Use your system URL accordingly
WSDL
https://cook.shortest-route.com/central_support/api/soap/v10/?wsdl Use your system URL accordingly

If authorization header is missing, HTTP 401 response is returned.

'async

The async domain contains methods for queue handling. Topic name is required for that.

Available from
v1

asyncPoll

Description

Retrieves a certain amount of results for a topic from the result queue. The result items that were retrieved are deleted from the server once they have been transmitted.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:asyncPoll>
         <topic>queue</topic>
         <limit>10</limit>
      </ecm:asyncPoll>
   </soapenv:Body>
</soapenv:Envelope>

asyncGetNextIndex

Description

Returns the next index for the given topic relative to the last call to "async/poll". This call is useful when switching from calling "async/poll" (with a managed index) to calling "async/pollByIndex" where the index is managed by the user. The result value can be used as value for parameter "index" in a follow up call to "async/pollByIndex".

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:asyncGetNextIndex>
         <topic>queue</topic>
      </ecm:asyncGetNextIndex>
   </soapenv:Body>
</soapenv:Envelope>

asyncGetPollCount

Description

Returns the number of result items that were retrieved/polled for a certain topic.

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:asyncGetPollCount>
         <topic>queue</topic>
      </ecm:asyncGetPollCount>
   </soapenv:Body>
</soapenv:Envelope>

asyncGetSubmitCount

Description

Returns the number of job results that were submitted for a certain topic.

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:asyncGetSubmitCount>
         <topic>queue</topic>
      </ecm:asyncGetSubmitCount>
   </soapenv:Body>
</soapenv:Envelope>

asyncPollByIndex

Description

Retrieves a specific number of results for a topic from the result queue, starting from the given offset.

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:asyncPollByIndex>
         <topic>queue</topic>
         <index>1</index>
         <limit>10</limit>
      </ecm:asyncPollByIndex>
   </soapenv:Body>
</soapenv:Envelope>

asyncSubmit

Description

Adds new element to the topic

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:asyncSubmit>
         <topic>queue</topic>
         <!--Zero or more repetitions:-->
         <arguments>
            <name>element</name>
            <value>2</value>
         </arguments>
      </ecm:asyncSubmit>
   </soapenv:Body>
</soapenv:Envelope>

'automation

automationFind

Description

Returns information about one or more automations. Use this method to obtain information about time-based or event-based automations.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:automationFind>
<automationFilter>
<automationType>TIME_BASED</automationType>
</automationFilter>
</ecm:automationFind>
</soapenv:Body>
</soapenv:Envelope>

automationGetDetails

Description

Returns detailed information for an automation. Use this method to obtain information about time-based or event-based automations.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:automationGetDetails>
<automationType>TIME_BASED</automationType>
<automationId>91</automationId>
</ecm:automationGetDetails>
</soapenv:Body>
</soapenv:Envelope>

automationRunOnce

Description

Performs one execution of the specified time-based automation. Execution takes place immediately. Run once does not change the status or schedule of the automation. You can only use this method to run an existing time-based automation. To execute the automation successfully, the API user account must also have the permissions required to run the job.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:automationRunOnce>
         <automationId>91</automationId>
      </ecm:automationRunOnce>
   </soapenv:Body>
</soapenv:Envelope>

'blacklist

The blacklist domain contains methods that are used to manage system and group blacklists.

Available from
v4

blacklistCreateGroupEntries

Description

Adds new entries (email, emailDomain, mobileNumber, or faxNumber) to the group blacklist.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:blacklistCreateGroupEntries>
         <entries>
         <!--Zero or more repetitions:-->
            <type>EMAIL_DOMAIN</type>
            <pattern>al.com</pattern>
         </entries>
         <groupId>30</groupId>
      </ecm:blacklistCreateGroupEntries>
   </soapenv:Body>
</soapenv:Envelope>

blacklistDeleteGroupEntries

Description

Deletes entries (email, email domain, mobile number, or fax number) from the group blacklist.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:blacklistDeleteGroupEntries>
         <!--Zero or more repetitions:-->
         <entries>
            <type>EMAIL</type>
            <pattern>test@bl.com</pattern>
         </entries>  
         <groupId>30</groupId>
      </ecm:blacklistDeleteGroupEntries>
   </soapenv:Body>
</soapenv:Envelope>

blacklistCreateSystemEntries

Description

Adds new entries (email, email domain, mobile number, or fax number) to the system blacklist.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:blacklistCreateSystemEntries>
         <!--Zero or more repetitions:-->
         <entries>
            <type>EMAIL</type>
            <pattern>blacklistuser4@test.com</pattern>
         </entries>
      </ecm:blacklistCreateSystemEntries>
   </soapenv:Body>
</soapenv:Envelope>

blacklistDeleteSystemEntries

Description

Deletes entries (email, email domain, mobile number, or fax number) from the system blacklist.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:blacklistDeleteSystemEntries>
         <!--Zero or more repetitions:-->
         <entries>
            <type>EMAIL</type>
            <pattern>mypartner1@test.com</pattern>
         </entries>
      </ecm:blacklistDeleteSystemEntries>
   </soapenv:Body>
</soapenv:Envelope>

blacklistCreateGroupEntriesHashed

Description

Adds new hashed email entries to the group blacklist. Entries can be hashed using md5hashgenerator

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:blacklistCreateGroupEntriesHashed>
         <!--Zero or more repetitions:-->
         <entries>
            <type>EMAIL_DOMAIN</type>
            <pattern>al.com</pattern>
         </entries>
         <groupId>30</groupId>
         <hashed>true</hashed>
      </ecm:blacklistCreateGroupEntriesHashed>
   </soapenv:Body>
</soapenv:Envelope>

blacklistCreateSystemEntriesHashed

Description

Adds new entries (email, email domain, mobile number or mobile app alias) to the system blacklist. Entries can be hashed using md5hashgenerator

Available from
v9

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:blacklistCreateSystemEntriesHashed>
         <!--Zero or more repetitions:-->
         <entries>
            <type>EMAIL</type>
            <pattern>blacklistuser4@test.com</pattern>
         </entries>
         <hashed>?</hashed>
      </ecm:blacklistCreateSystemEntriesHashed>
   </soapenv:Body>
</soapenv:Envelope>

'cms

Available from
v3

cmsGetMessageDefinitions

Description

Returns a list of all CMS messages that are saved in the system. Every CMS message contains detailed information that identifies the message and the template that was used for creation.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:automationFind>
<automationFilter>
<automationType>TIME_BASED</automationType>
</automationFilter>
</ecm:automationFind>
</soapenv:Body>
</soapenv:Envelope>

cmsGetMimeMessage

Description

Returns the specified CMS message in MIME message format.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:cmsGetMimeMessage>
<cmsMessageId>32</cmsMessageId>
</ecm:cmsGetMimeMessage>
</soapenv:Body>
</soapenv:Envelope>

'contact

The contact domain contains methods for working with contact profiles.

Available from
v7

contactCreate

Description

Creates a new contact using the information provided in the contact object.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contactCreate>
         <contact>
            <contactId>1</contactId>
            <emailAddress>test@test.com</emailAddress>
            <mobileNumber>48505606707</mobileNumber>
            <applicationAlias>?</applicationAlias>
            <identifier>?</identifier>
            <!--Zero or more repetitions:-->
            <attributes>
               <name>test</name>
               <value>test</value>
            </attributes>
         </contact>
      </ecm:contactCreate>
   </soapenv:Body>
</soapenv:Envelope>

contactGet

Description

Returns a contact object that matches the specified identifier.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contactGet>
         <identifier>
            <type>EMAIL</type>
            <value>test1@test.com</value>
         </identifier>
      </ecm:contactGet>
   </soapenv:Body>
</soapenv:Envelope>

contactUpdate

Description

Updates the profile data of an existing contact.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contactUpdate>
         <identifierType>EMAIL</identifierType>
         <contact>
            <contactId></contactId>
            <emailAddress>test@test.com</emailAddress>
            <mobileNumber>48606707808</mobileNumber>
            <applicationAlias>?</applicationAlias>
            <identifier>?</identifier>
            <!--Zero or more repetitions:-->
            <attributes>
               <name>?</name>
               <value>?</value>
            </attributes>
         </contact>
      </ecm:contactUpdate>
   </soapenv:Body>
</soapenv:Envelope>

contactDelete

Description

Deletes the contact identified by the specified identifier.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contactDelete>
         <identifier>
            <type>EMAIL</type>
            <value>test@test.com</value>
         </identifier>
      </ecm:contactDelete>
   </soapenv:Body>
</soapenv:Envelope>

contactAnonymize

Description

Anonymizes contact PII data based on GDPR regulations.

Available from
v9

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contactAnonymize>
         <contactId>3769711</contactId>
         <notificationRecipient>john.smith@mapp.com</notificationRecipient>
      </ecm:contactAnonymize>
   </soapenv:Body>
</soapenv:Envelope>

contactExport

Description

Pushes asynchronyous GDPR contact export, which will send system message with the link in the end

Available from
v9

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contactExport>
         <contactId>3769711</contactId>
         <notificationRecipient>john.smith@mapp.com</notificationRecipient>
      </ecm:contactExport>
   </soapenv:Body>
</soapenv:Envelope>

'content

Available from
v1

contentStore

Description

Stores a content element in the Content Store.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contentStore>
         <content>
                  <name>twitter_logo.png</name>
                  <contentType>image/png</contentType>
                  <content>iVBORw0KGgoAAAANSUhEUgAAABUAAAARCAYAAAAyhueAAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAASFJREFUeNqslM0NgkAQhRdiAdiAgQ6468EO1INntQOpwFABdqBe9aAdiIl3twS1AbECfJPMkhVZftSXjJPsDh87z2WsNE1Fb3d3z+POVVQIdQ5ShJhqywdEgEgQQ1qwutsbFT4QM4DXFcALwi3YJqDD2bPx4/PGCg/OSw46NwAFA0nU7d7ObUYAHxF+wYMDUU8jiz19aG9TihEbyuS3oSavNmoT5Sm1thA/CkCLsvJ0In5XdnsIKkv+gCaSGZQ8QF7+AXrST0peBH8Ar9+grKfuS1Mgd/wBjb/0lmChvmBr14GgMy5qoiA/N+zcPSNfPN2fCoVF86KlDQxqvc93tl8DaBxALcAi/qLqKuaWpalAffsOz8iB4ZRSzYIymNJLgAEAYsJkJOLW//gAAAAASUVORK5CYII=</content>
         </content>
      </ecm:contentStore>
   </soapenv:Body>
</soapenv:Envelope>

contentDelete

Description

Deletes a content element in the Content Store.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:contentDelete>
         <contentId>1</contentId>
      </ecm:contentDelete>
   </soapenv:Body>
</soapenv:Envelope>

'draftmessage

Available from
v6

draftmessageCreate

Description

Creates a new message as a draft.

Example request

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="http://ecircle.com/developer/ecmapi">
    <soapenv:Header/>
    <soapenv:Body>
        <ecm:draftmessageCreate>
            <draftMessage>
                <id></id>
                <name>Test Draft Message</name>
                <externalId>111</externalId>
                <message>
                    <subject>This is subject</subject>
                    <emailBodyText>This is message body.</emailBodyText>
                    <attachments>
                        <name>twitter_logo.png</name>
                        <contentType>image/png</contentType>
                        <content>iVBORw0KGgoAAAANSUhEUgAAABUAAAARCAYAAAAyhueAAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAASFJREFUeNqslM0NgkAQhRdiAdiAgQ6468EO1INntQOpwFABdqBe9aAdiIl3twS1AbECfJPMkhVZftSXjJPsDh87z2WsNE1Fb3d3z+POVVQIdQ5ShJhqywdEgEgQQ1qwutsbFT4QM4DXFcALwi3YJqDD2bPx4/PGCg/OSw46NwAFA0nU7d7ObUYAHxF+wYMDUU8jiz19aG9TihEbyuS3oSavNmoT5Sm1thA/CkCLsvJ0In5XdnsIKkv+gCaSGZQ8QF7+AXrST0peBH8Ar9+grKfuS1Mgd/wBjb/0lmChvmBr14GgMy5qoiA/N+zcPSNfPN2fCoVF86KlDQxqvc93tl8DaBxALcAi/qLqKuaWpalAffsOz8iB4ZRSzYIymNJLgAEAYsJkJOLW//gAAAAASUVORK5CYII=</content>
                    </attachments>
                    <encoding></encoding>
                    <imageHandlingMode>inline</imageHandlingMode>
                </message>
            </draftMessage>
        </ecm:draftmessageCreate>
    </soapenv:Body>
</soapenv:Envelope>

draftmessageDelete

Description

Deletes a draft message identified by the specified draft message ID.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:draftmessageDelete>
         <draftMessageId>16</draftMessageId>
      </ecm:draftmessageDelete>
   </soapenv:Body>
</soapenv:Envelope>

draftmessageGet

Description

Returns a draft message identified by the specified draft message ID.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:draftmessageGet>
         <draftMessageId>16</draftMessageId>
      </ecm:draftmessageGet>
   </soapenv:Body>
</soapenv:Envelope>

draftmessageUpdate

Description

Updates a message draft.

Example request

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="http://ecircle.com/developer/ecmapi">
    <soapenv:Header/>
    <soapenv:Body>
        <ecm:draftmessageUpdate>
            <draftMessage>
                <id>16</id>
                <name>draft message update</name>
                <externalId>111</externalId>
                <message>
                    <subject>subject update</subject>
                    <emailBodyText>some text</emailBodyText>
                    <encoding></encoding>
                    <attachments>
                        <name>twitter_logo.png</name>
                        <contentType>image/png</contentType>
                        <content>iVBORw0KGgoAAAANSUhEUgAAABUAAAARCAYAAAAyhueAAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAASFJREFUeNqslM0NgkAQhRdiAdiAgQ6468EO1INntQOpwFABdqBe9aAdiIl3twS1AbECfJPMkhVZftSXjJPsDh87z2WsNE1Fb3d3z+POVVQIdQ5ShJhqywdEgEgQQ1qwutsbFT4QM4DXFcALwi3YJqDD2bPx4/PGCg/OSw46NwAFA0nU7d7ObUYAHxF+wYMDUU8jiz19aG9TihEbyuS3oSavNmoT5Sm1thA/CkCLsvJ0In5XdnsIKkv+gCaSGZQ8QF7+AXrST0peBH8Ar9+grKfuS1Mgd/wBjb/0lmChvmBr14GgMy5qoiA/N+zcPSNfPN2fCoVF86KlDQxqvc93tl8DaBxALcAi/qLqKuaWpalAffsOz8iB4ZRSzYIymNJLgAEAYsJkJOLW//gAAAAASUVORK5CYII=</content>
                    </attachments>
                    <imageHandlingMode>inline</imageHandlingMode>
                </message>
            </draftMessage>
        </ecm:draftmessageUpdate>
    </soapenv:Body>
</soapenv:Envelope>

draftmessageFind

Description

Finds draft messages specified by a draft message filter.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:draftmessageFind>
         <filter>
            <externalMessageId>?</externalMessageId>
            <messageName>Test Draft Message</messageName>
            <subjectLine>?</subjectLine>
            <authorName>?</authorName>
            <authorId>?</authorId>
            <messageCategoryId>?</messageCategoryId>
            <creationDateFrom>2018-07-10</creationDateFrom>
            <creationDateTo>2018-08-10</creationDateTo>
            <lastUpdateDateFrom>2018-07-10</lastUpdateDateFrom>
            <lastUpdateDateTo>2018-08-10</lastUpdateDateTo>
         </filter>
      </ecm:draftmessageFind>
   </soapenv:Body>
</soapenv:Envelope>

draftmessageSaveAsPreparedMessage

Description

Saves draft message as prepared message. The channel ID is available at "Information" panel for each channel, at "Administration > Channels".

Available from
v9

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:draftmessageSaveAsPreparedMessage>
         <draftMessageId>19</draftMessageId>
         <groupId>385</groupId>
         <channelId>1</channelId>
      </ecm:draftmessageSaveAsPreparedMessage>
   </soapenv:Body>
</soapenv:Envelope>

'group

Available from
v1

groupGet

Description

Returns the group object of the specified group. The group is identified by group ID.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupGet>
<groupId>52</groupId>
</ecm:groupGet>
</soapenv:Body>
</soapenv:Envelope>

groupSetAttributes

Description

Creates and updates the group attributes. Existing attributes are overwritten.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupSetAttributes>
<groupId>64</groupId>
<attributes>
<name>country</name>
<value>FR</value>
</attributes>
</ecm:groupSetAttributes>
</soapenv:Body>
</soapenv:Envelope>

groupClone

Description

Creates a clone of a specific group that already exists in the system. Most of the sendout options and delivery settings are identical for the original and the clone. However, group members are not copied - members of the group are not members of the clone. With CloneOptions you have to specify how and with what mandatory parameters the group will be cloned.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupClone>
<groupId>6</groupId>
<options>
<name>API GROUP2</name>
<email>clone@ecircle.com</email>
<includePreparedMessages>true</includePreparedMessages>
<includeTestUsers>true</includeTestUsers>
<keepOwner>true</keepOwner>
<withOwnerAsMember>true</withOwnerAsMember>
</options>
</ecm:groupClone>
</soapenv:Body>
</soapenv:Envelope>

groupFindIdsByAttributes

Description

Returns a list of group IDs for all groups in the system that use the specified group attributes. Group attributes are only available in the group context and consist of a unique name and a value. Please note that attributes like Group Name or Email cannot be used here.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupFindIdsByAttributes>
<attributes>
<name>country</name>
<value>croatia</value>
</attributes>
</ecm:groupFindIdsByAttributes>
</soapenv:Body>
</soapenv:Envelope>

groupArchive

Description

Archive a list of groups and any dependent subgroups. Other dependent objects, such as triggers and scheduled tasks, are not archived.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupArchive>
<groupIds>52</groupIds>
</ecm:groupArchive>
</soapenv:Body>
</soapenv:Envelope>

groupGetPreparedMessages

Description

Returns all of the prepared messages for a specific group.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupGetPreparedMessages>
<groupId>503</groupId>
</ecm:groupGetPreparedMessages>
</soapenv:Body>
</soapenv:Envelope>

groupActivate

Description

Activates archived groups.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:groupActivate>
<groupIds>52</groupIds>
</ecm:groupActivate>
</soapenv:Body>
</soapenv:Envelope>

'landingpage

Available from
v2

landingpageFind

Description

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:landingpageFind>
         <landingpageFilter>
            <status>PUBLISHED</status>
            <ownerId>279975</ownerId>
            <publishedFrom>2016-07-15</publishedFrom>
            <publishedTo>2018-07-15</publishedTo>
            <name>?</name>
            <pageName>?</pageName>
            <URL>?</URL>
         </landingpageFilter>
      </ecm:landingpageFind>
   </soapenv:Body>
</soapenv:Envelope>

landingpageGetStatus

Description

Returns the publishing status of a landing page. Because these pages are usually associated with the lifetime of a particular email campaign, they may have a differing publishing status. Previously published pages that have become inactive because they are no longer valid are sometimes redirected to another default page. Possible states are:

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:landingpageGetStatus>
         <landingpageId>271000010</landingpageId>
      </ecm:landingpageGetStatus>
   </soapenv:Body>
</soapenv:Envelope>

landingpageDelete

Description

Deletes the landing page with the specified landing page ID. It works only if the landing page is inactive.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:landingpageDelete>
         <landingpageId>271000014</landingpageId>
      </ecm:landingpageDelete>
   </soapenv:Body>
</soapenv:Envelope>

landingpageDeleteMany

Description

Deletes the landing pages with the specified landing page IDs. It works only if landing pages are inactive.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:landingpageDeleteMany>
      <landingpageIds>271000009</landingpageIds>
      <landingpageIds>271000010</landingpageIds>      
      </ecm:landingpageDeleteMany>
   </soapenv:Body>
</soapenv:Envelope>

'membership

The membership domain contains methods that are used to manage group memberships.

membershipSubscribe

Description

Subscribes a user to a group. With this call, the subscription is handled as a self subscription. Depending on the subscription mode used, the user may have to confirm the subscription (opt in) and may be notified of the successful subscription.

SubscriptionMode Description
CONFIRMED_OPT_IN New contacts receive a welcome message via email when they are added to the group. Despite the label used for this value, the contact does not need to confirm the subscription. A single opt-in subscription.
DOUBLE_OPT_IN New contacts receive an invitation to join the group via email. The contact must accept the invitation before they are added to the group. A double opt-in subscription.
OPT_IN New contacts are added to the group without notification.
Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipSubscribe>
         <userId>3769713</userId>
         <groupId>385</groupId>
         <subscriptionMode>OPT_IN</subscriptionMode>
      </ecm:membershipSubscribe>
   </soapenv:Body>
</soapenv:Envelope>

membershipSubscribeByEmail

Description

Description

Subscribes a user to a group. Works like the subscribe call but uses an email address instead of a user ID.

SubscriptionMode Description
CONFIRMED_OPT_IN New contacts receive a welcome message via email when they are added to the group. Despite the label used for this value, the contact does not need to confirm the subscription. A single opt-in subscription.
DOUBLE_OPT_IN New contacts receive an invitation to join the group via email. The contact must accept the invitation before they are added to the group. A double opt-in subscription.
OPT_IN New contacts are added to the group without notification.
Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipSubscribeByEmail>
         <email>one@test.com</email>
         <groupId>385</groupId>
         <subscriptionMode>CONFIRMED_OPT_IN</subscriptionMode>
      </ecm:membershipSubscribeByEmail>
   </soapenv:Body>
</soapenv:Envelope>

membershipUnsubscribe

Description

Unsubscribes a user from a group. A notification is sent to the manager.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipUnsubscribe>
         <userId>3769713</userId>
         <groupId>21</groupId>
      </ecm:membershipUnsubscribe>
   </soapenv:Body>
</soapenv:Envelope>

membershipUnsubscribeFromMessage

Description

Unsubscribes a user from a group. The unsubscription is associated with a specific message. Notification is sent to the group manager. Returns success only when the user is unsubscribed from the group and the unsubscription is associated with the specified message.

Available from
v5

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipUnsubscribeFromMessage>
         <userId>3769713</userId>
         <groupId>385</groupId>
         <messageId>12</messageId>
      </ecm:membershipUnsubscribeFromMessage>
   </soapenv:Body>
</soapenv:Envelope>

membershipUnsubscribeByEmail

Description

Unsubscribes a user from a group based on the email address. An unsubscribe confirmation email is sent to the user.

Available from
v5

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipUnsubscribeByEmail>
         <email>one@test.com</email>
         <groupId>385</groupId>
      </ecm:membershipUnsubscribeByEmail>
   </soapenv:Body>
</soapenv:Envelope>

membershipCreate

Description

Creates a new membership (meaning the user is subscribed to a group). This call differs from subscribe, in that notification is not sent.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipCreate>
         <userId>3769713</userId>
         <groupId>385</groupId>
      </ecm:membershipCreate>
   </soapenv:Body>
</soapenv:Envelope>

membershipGet

Description

Retrieves membership context of a user identified by the userId in a group identified by groupId.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipGet>
         <userId>3769713</userId>
         <groupId>385</groupId>
      </ecm:membershipGet>
   </soapenv:Body>
</soapenv:Envelope>

membershipGetByEmail

Description

Retrieves membership context of a user identified by email in a group identified by groupId.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipGetByEmail>
         <email>one@test.com</email>
         <groupId>385</groupId>
      </ecm:membershipGetByEmail>
   </soapenv:Body>
</soapenv:Envelope>

membershipDelete

Description

Creates a new membership (meaning the user is subscribed to a group). This call differs from subscribe in that a notification is not sent.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipDelete>
         <userId>3769713</userId>
         <groupId>385</groupId>
      </ecm:membershipDelete>
   </soapenv:Body>
</soapenv:Envelope>

membershipFindAll

Description

Returns a list of membership objects, one membership object for each group in which the user is a member.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipFindAll>
         <userId>3769713</userId>
      </ecm:membershipFindAll>
   </soapenv:Body>
</soapenv:Envelope>

membershipFindAllByEmail

Description

Returns a list of membership objects for the user. One membership object for each group in which the user is a member. The user is identified by the email.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipFindAllByEmail>
         <email>test@test.com</email>
      </ecm:membershipFindAllByEmail>
   </soapenv:Body>
</soapenv:Envelope>

membershipGetAttributes

Description

Returns a collection of member attributes for a user within the specified group. Member attributes are used to save information for an individual user, but in the context of a specific group. A member attribute contains a specific value for each recipient. | Available from| | -------| | v2 |

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
  <soapenv:Header/>
  <soapenv:Body>
     <ecm:membershipGetAttributes>
        <userId>5</userId>
        <groupId>1</groupId>
     </ecm:membershipGetAttributes>
  </soapenv:Body>
</soapenv:Envelope>

membershipGetAttributesByEmail

Description

Returns a collection of member attributes for a user within the specified group. Member attributes are used to save information for an individual user, but in the context of a specific group. A member attribute contains a specific value for each recipient.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipGetAttributesByEmail>
         <email>one@test.com</email>
         <groupId>385</groupId>
      </ecm:membershipGetAttributesByEmail>
   </soapenv:Body>
</soapenv:Envelope>

membershipUpdateAttributes

Description

Updates the member attributes for a user within a certain group if the user is a member of the group. If an attribute already exists, the value will be updated; if not, a new attribute will be created. If an existing member attribute is not in the attribute list being sent in the call, it will be deleted.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:membershipUpdateAttributes>
         <userId>3769713</userId>
         <groupId>385</groupId>
         <attributes>
            <name>hobby</name>
            <value>sport</value>
         </attributes>     
      </ecm:membershipUpdateAttributes>
   </soapenv:Body>
</soapenv:Envelope>

membershipReplaceAttributes

Description

Replaces the member attributes for a contact within a specific group where the contact is a member

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
  <soapenv:Header/>
  <soapenv:Body>
     <ecm:membershipReplaceAttributes>
        <userId>5</userId>
        <groupId>1</groupId>
        <!--Zero or more repetitions:-->
        <attributes>
           <name>likesfootball</name>
           <value>yes</value>
        </attributes>
     </ecm:membershipReplaceAttributes>
  </soapenv:Body>
</soapenv:Envelope>

'message

The message domain contains methods that can be used to manage email and SMS messages

messageGetHistorical

Description

Operator wants to fetch a specific (group) message as it was sent to a defined contact, including resolved personalizations.

Available from
v8

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageGetHistorical>
         <messageId>669</messageId>
         <contactId>3769713</contactId>
      </ecm:messageGetHistorical>
   </soapenv:Body>
</soapenv:Envelope>

messageSendSingle

Description

Sends a prepared message as a single message to a specific user.

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageSendSingle>
         <messageId>2</messageId>
         <recipientId>7</recipientId>
        <additionalContent>
            <!--Zero or more repetitions:-->
            <parameters>
               <name>subject</name>
               <value>This is a subject</value>
            </parameters> 
         </additionalContent> 
      </ecm:messageSendSingle>
   </soapenv:Body>
</soapenv:Envelope>

messageSendTransactional

Description

Sends a previously prepared message template as transactional message

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageSendTransactional>
         <messageId>2</messageId>
         <externalTransactionFormula>transactionalID</externalTransactionFormula>
         <recipientId>7</recipientId>
         <additionalContent><!--Zero or more repetitions:-->
           <parameters>
               <name>subject</name>
               <value>This is subject</value>
             </parameters>
         </additionalContent>
      </ecm:messageSendTransactional>
   </soapenv:Body>
</soapenv:Envelope>

messageGetUsedPersonalizations

Description

Returns the names of all user and group attributes that are referenced within the header and content area of a prepared message. The reference to the attributes is a personalization placeholder in the body of the message. All of these placeholders are replaced with individual user or message information during sendout. Be aware that this method does not return member attributes.

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageGetUsedPersonalizations>
         <messageId>669</messageId>
      </ecm:messageGetUsedPersonalizations>
   </soapenv:Body>
</soapenv:Envelope>

messageValidate

Description

Validates a prepared message for following functionality: check that message is valid (InvalidObjectError -> objecttype message), check that message does not contain invalid content store items, check that message does not use archived Attributes (InvalidObjectError -> objecttype attribute).

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageValidate>
         <messageId>669</messageId>
      </ecm:messageValidate>
   </soapenv:Body>
</soapenv:Envelope>

messageValidateMany

Description

Validates a list of messages for following functionality: checks that the message is valid (InvalidObjectError -> objecttype message), checks that the message does not contain any invalid content store items, checks that the message does not use archived Attributes (InvalidObjectError -> objecttype attribute).

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageValidateMany>
         <messageIds>668</messageIds>
         <messageIds>669</messageIds>
      </ecm:messageValidateMany>
   </soapenv:Body>
</soapenv:Envelope>

messageGetStatistics

Description

Retrieves statistical data for a sent message.

Available from
v5

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageGetStatistics>
         <messageId>669</messageId>
      </ecm:messageGetStatistics>
   </soapenv:Body>
</soapenv:Envelope>

messageGetStatisticsByExternalMessageId

Description

Retrieves statistical data for a sent message.

Available from
v5

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageGetStatisticsByExternalMessageId>
         <externalMessageId>888</externalMessageId>
      </ecm:messageGetStatisticsByExternalMessageId>
   </soapenv:Body>
</soapenv:Envelope>

messageFind

Description

Returns a list of message summary objects that contain information about the messages that match the filter criteria. You can use this method to retrieve information about a message that has been sent or saved as a prepared message.

Available from
v7

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageFind>
         <filter>
            <externalMessageId>test1</externalMessageId>
            <groupName>GroupA</groupName>
            <sendoutDateFrom>2018-06-20</sendoutDateFrom>
            <sendoutDateTo>2018-06-20</sendoutDateTo>
            <messageName></messageName>
            <subjectLine></subjectLine>
            <authorName></authorName>
            <authorId></authorId>
            <messageCategoryId></messageCategoryId>
            <groupId></groupId>
            <groupCategoryName></groupCategoryName>
            <groupCategoryId></groupCategoryId>
            <type></type>
            <status></status>
         </filter>
      </ecm:messageFind>
   </soapenv:Body>
</soapenv:Envelope>

messageGetTimeDistribution

Description

Retrieves statistical time distribution information for a specific sent message.

Available from
v7

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageGetTimeDistribution>
         <messageId>669</messageId>
         <interval>HOURLY</interval>
      </ecm:messageGetTimeDistribution>
   </soapenv:Body>
</soapenv:Envelope>

messageGetTimeDistributionByExternalMessageId

Description

Retrieves statistical time distribution information for a specific sent message.

Available from
v7

Example body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:messageGetTimeDistributionByExternalMessageId>
         <externalMessageId>123</externalMessageId>
         <interval>HOURLY</interval>
      </ecm:messageGetTimeDistributionByExternalMessageId>
   </soapenv:Body>
</soapenv:Envelope>

'preparedmessage

preparedmessageFind

Available from
v7

Description

Returns list of message summary objects that contain information about prepared messages that match the filter criteria.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:preparedmessageFind>
         <filter>
            <externalMessageId>?</externalMessageId>
            <messageName>?</messageName>
            <subjectLine>?</subjectLine>
            <authorName>?</authorName>
            <authorId>?</authorId>
            <messageCategoryId>?</messageCategoryId>
            <groupName>?</groupName>
            <groupId>?</groupId>
            <groupCategoryName>?</groupCategoryName>
            <groupCategoryId>?</groupCategoryId>
            <creationDateFrom>2018-07-01</creationDateFrom>
            <creationDateTo>2018-07-31</creationDateTo>
            <lastUpdateDateFrom>2018-07-01</lastUpdateDateFrom>
            <lastUpdateDateTo>2018-07-31</lastUpdateDateTo>
         </filter>
      </ecm:preparedmessageFind>
   </soapenv:Body>
</soapenv:Envelope>

preparedmessageSend

Available from
v9

Description

Send prepared messages based on a given send datetime as Datetime

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:preparedmessageSend>
         <preparedMessageId>667</preparedMessageId>
         <sendDateTime>1564146875000</sendDateTime>
         <!--Optional:-->
         <processingDateTime>1564146875000</processingDateTime>
         <!--Optional:-->
         <selectionId>231</selectionId>
      </ecm:preparedmessageSend>
   </soapenv:Body>
</soapenv:Envelope>

'meta

The meta domain contains methods that define your system.

metaGetAttributeDefinitions

Description

Returns a list of all active custom attributes that are defined for the users. Attributes with the status 'archived' or 'system' are not included in the list.

Available from
v1

Example Body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:metaGetAttributeDefinitions/>
   </soapenv:Body>
</soapenv:Envelope>

metaCreateAttributeDefinitions

Description

Creates a new data field (custom user attribute) where information about users can be stored. With the standard setup, you are permitted to create a limited number of custom attributes with different data types. Each custom user attribute has a unique name. If an attribute is no longer needed, it may be archived. Please contact your customer support representative if you need to delete an attribute.

Available from
v1

Example Body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:metaCreateAttributeDefinitions>
         <attributeDefinitions>
            <name>VehicleNames1</name>
            <type>STRING</type>
            <enumerationValues>Ford</enumerationValues>
            <enumerationValues>Mercedes</enumerationValues>
         </attributeDefinitions>                         
      </ecm:metaCreateAttributeDefinitions> 
   </soapenv:Body>
</soapenv:Envelope>

metaArchiveAttributeDefinitions

Description

Archives custom attributes. An archived attribute is still stored in the system. The attributes can still be in use for existing messages and sendouts, but they are not available in the GUI message creation process (i.e. personalization builder).

Available from
v1

Example Body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:metaArchiveAttributeDefinitions>
            <attributeNames>VehicleNames</attributeNames>                 
      </ecm:metaArchiveAttributeDefinitions>
   </soapenv:Body>
</soapenv:Envelope>

'process

processGetDetails

Description

Returns information for the process identified by the specified process ID.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:processGetDetails>
<processId>1534</processId>
</ecm:processGetDetails>
</soapenv:Body>
</soapenv:Envelope>

processApplyAction

Description

Changes the status of an existing process.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
<soapenv:Header/>
<soapenv:Body>
<ecm:processApplyAction>
<processId>1534</processId>
<action>PAUSE</action>
</ecm:processApplyAction>
</soapenv:Body>
</soapenv:Envelope>

'relateddata

The relatedData domain contains methods that are used to manage records stored in Related Data.

Available from
v4

relatedDataCreateRecord

Description

Adds a record to a data set. Dataset has to be created in "Attributes > Related Data". Please make sure dataset has at least one column.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:relatedDataCreateRecord>
         <record>
            <datasetName>myproducts</datasetName>
            <key>1</key>
            <data>
               <name>id</name>
               <value>1</value>
            </data>
            <data>
               <name>product</name>
               <value>bicycle</value>
            </data>            
         </record>
         <record>
            <datasetName>myproducts</datasetName>
            <key>2</key>
            <data>
               <name>id</name>
               <value>2</value>
            </data>
            <data>
               <name>product</name>
               <value>jacket</value>
            </data>            
         </record>         
      </ecm:relatedDataCreateRecord>
   </soapenv:Body>
</soapenv:Envelope>

relatedDataUpdateRecords

Description

Updates all or specific records for a key in a related data set. Dataset has to be created in "Attributes > Related Data". Please make sure dataset has at least one column.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:relatedDataUpdateRecords>
         <recordAndFilter>
            <datasetName>myproducts</datasetName>
            <key>1</key>
            <!--Zero or more repetitions:-->
            <data>
               <name>id</name>
               <value>1</value>
            </data>
            <data>
               <name>product</name>
               <value>suitcase</value>
            </data>        
            <!--Zero or more repetitions:-->
            <filter>
               <name>id</name>
               <value>1</value>
            </filter>
         </recordAndFilter>
      </ecm:relatedDataUpdateRecords>
   </soapenv:Body>
</soapenv:Envelope>

relatedDataDeleteRecords

Description

Delete a records in a related data set.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:relatedDataDeleteRecords>
         <filter>
            <datasetName>myproducts</datasetName>
            <key>3</key>
            <filter>
                <name></name>
                <value></value>
            </filter>
         </filter>
      </ecm:relatedDataDeleteRecords>
   </soapenv:Body>
</soapenv:Envelope>

'system

systemGetApiVersion

Description

Returns information about the API version currently in use.

Available from
v1

Example Body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemGetApiVersion/>
   </soapenv:Body>
</soapenv:Envelope>

systemGetEcmVersion

Description

Returns information about the API version currently in use.

Available from
v1

Example Body

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemGetEcmVersion/>
   </soapenv:Body>
</soapenv:Envelope>

'systemuser

SystemUser contains all of the system user-related methods such as editing, deleting, and creating a system user. Administrator priviledge may be required for some operations.

Available from
v8

systemuserCreate

Description

Creates the new system user in system.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemuserCreate>
         <systemUser>
            <type>API</type>
            <email>test@test.com</email>
            <firstName>?</firstName>
            <lastName>?</lastName>
            <language>en_US</language>
            <timeZone>Europe/Berlin</timeZone>
            <messagingRole>project_manager</messagingRole>
            <expiryDate>2018-09-01</expiryDate>
            <lastLoginDate>?</lastLoginDate>
         </systemUser>
         <createContact>?</createContact>
         <suppressSystemMessage>?</suppressSystemMessage>
      </ecm:systemuserCreate>
   </soapenv:Body>
</soapenv:Envelope>

systemuserGet

Description

Retrieves the system user identified by the specified system user ID, external ID, or email address.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemuserGet>
         <systemUserId>3769698</systemUserId>
         <email></email>
         <externalId>?</externalId>
      </ecm:systemuserGet>
   </soapenv:Body>
</soapenv:Envelope>

systemuserUpdate

Description

Updates the existing system user in the system.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemuserUpdate>
         <systemUser>
            <id>3769700</id>
            <type>UI</type>
            <firstName>?</firstName>
            <lastName>?</lastName>
            <language>en_US</language>
            <timeZone>Europe/London</timeZone>
            <messagingRole>client_admin</messagingRole>
            <expiryDate>2018-09-01</expiryDate>
         </systemUser>
      </ecm:systemuserUpdate>
   </soapenv:Body>
</soapenv:Envelope>

systemuserDelete

Description

Deletes the system user identified by the specified system user ID, external ID, or email address.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemuserDelete>
         <systemUserId>3769698</systemUserId>
         <email>test@test.com</email>
      </ecm:systemuserDelete>
   </soapenv:Body>
</soapenv:Envelope>

systemuserUpdatePassword

Description

Updates the system user password identified by the specified system user ID

Available from
v9

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:systemuserUpdatePassword>
         <credentials>
            <systemUserId>3769698</systemUserId>
            <password>password</password>
         </credentials>
      </ecm:systemuserUpdatePassword>
   </soapenv:Body>
</soapenv:Envelope>

'user

The user domain contains methods for contact management.

userCreate

Description

Creates a new user. Requires either an email or a mobile number since these fields are used as the unique user identifier in the system

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userCreate>
         <email>testuser1@test.com</email>
         <!--Optional:-->
         <mobileNumber>47505606707</mobileNumber>
         <!--Zero or more repetitions:-->
         <attributes>
            <name>isocountrycode</name>
            <value>DK</value>
         </attributes>
      </ecm:userCreate>
   </soapenv:Body>
</soapenv:Envelope>

userGet

Description

Returns the user identified by the specified user ID.

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGet>
         <userId>498332</userId>
      </ecm:userGet>
   </soapenv:Body>
</soapenv:Envelope>

userGetByEmail

Description

Returns the user identified by the specified email address.

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetByEmail>
         <email>test1@test.com</email>
      </ecm:userGetByEmail>
   </soapenv:Body>
</soapenv:Envelope>

userGetByIdentifier

Description

Returns the user identified by the specified identifier. If there are more users with the same identifier, the response refers to the last user where this identifier has been assigned.

Available from
v4

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetByIdentifier>
         <identifier>8888</identifier>
      </ecm:userGetByIdentifier>
   </soapenv:Body>
</soapenv:Envelope>

userGetProfile

Description

Returns the user's profile (only attributes with a value are shown). The profile consists of attributes that contain user data. All attributes can be accessed system-wide

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetProfile>
         <userId>498332</userId>
      </ecm:userGetProfile>
   </soapenv:Body>
</soapenv:Envelope>

userGetProfileByEmail

Description

Returns the user's profile, this is identified by the email address.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetProfileByEmail>
         <email>newuser@test.com</email>
      </ecm:userGetProfileByEmail>
   </soapenv:Body>
</soapenv:Envelope>

userGetProfileByMobileNumber

Description

Returns the user's profile, identified by the mobile number

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetProfileByMobileNumber>
         <mobileNumber>48505606707</mobileNumber>
      </ecm:userGetProfileByMobileNumber>
   </soapenv:Body>
</soapenv:Envelope>

userGetByMobileNumber

Description

Returns the user identified by the specified identifier. If there are more users with the same identifier, the response refers to the last user where this identifier has been assigned.

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetByMobileNumber>
         <mobileNumber>48505606707</mobileNumber>
      </ecm:userGetByMobileNumber>
   </soapenv:Body>
</soapenv:Envelope>

userUpdateProfile

Description

Updates the user's profile (data stored in the attributes) with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userUpdateProfile>
         <userId>498332</userId>
        <attributes>
                    <name>user.firstname</name>
                    <value>Ambrozy</value>
                 </attributes>
                 <attributes>
                    <name>user.lastname</name>
                    <value>Krzakiewicz</value>
                 </attributes>
                 <attributes>
                    <name>user.nickname</name>
                    <value></value>
                 </attributes>
                 <attributes>
                    <name>user.identifier</name>
                    <value>7777</value>
                 </attributes>
             <attributes>
                    <name>user.title</name>
                    <value>1</value>
                 </attributes>
              <attributes>
                    <name>user.dateofbirth</name>
                    <value>1985-09-22</value>
                 </attributes>
                 <attributes>
                    <name>user.zipcode</name>
                    <value>31422</value>
                 </attributes>
              <attributes>
                    <name>user.isolanguagecode</name>
                    <value>pl</value>
                 </attributes>
                 <attributes>
                    <name>user.isocountrycode</name>
                 <value>PL</value> 
                 </attributes>
      </ecm:userUpdateProfile>
   </soapenv:Body>
</soapenv:Envelope>

userUpdateProfileByEmail

Description

Updates a user identified via email. Updates all data stored in the attributes with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userUpdateProfileByEmail>
         <email>testprofile2@test.com</email>
         <attributes>
            <name>user.firstname</name>
            <value>John Adam</value>
         </attributes>
      </ecm:userUpdateProfileByEmail>
   </soapenv:Body>
</soapenv:Envelope>

userUpdateProfileByMobileNumber

Description

Updates a user identified via mobile number. Updates all data stored in the attributes with the information saved in the attribute list. This method only changes the information that is explicitly mentioned. Attributes that are not mentioned are not changed (there is also a replace method to change the entire profile of a user and to delete attribute values if the attribute is not mentioned for the user).

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userUpdateProfileByMobileNumber>
         <mobileNumber>48505606707</mobileNumber>
         <!--Zero or more repetitions:-->
         <attributes>
               <name>user.lastname</name>
               <value>Krzakiewicz</value>
         </attributes>
      </ecm:userUpdateProfileByMobileNumber>
   </soapenv:Body>
</soapenv:Envelope>

userReplaceProfile

Description

Replaces all attribute values for a specific user. All attribute values that are transmitted with the method are added and replace any existing values. Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userReplaceProfile>
         <userId>8888</userId>
         <!--Zero or more repetitions:-->
         <attributes>
                 <name>user.dateofbirth</name>
                 <value>1985-09-22</value>
         </attributes>
      </ecm:userReplaceProfile>
   </soapenv:Body>
</soapenv:Envelope>

userReplaceProfileByEmail

Description

Replaces all attribute values for a user identified via email. All attribute values that are transmitted with the method are added and replace any existing values. Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userReplaceProfileByEmail>
         <email>test@test.com</email>
         <!--Zero or more repetitions:-->
         <attributes>
                <name>user.dateofbirth</name>
                <value>1985-09-22</value>
         </attributes>
      </ecm:userReplaceProfileByEmail>
   </soapenv:Body>
</soapenv:Envelope>

userReplaceProfileByMobileNumber

Description

Replaces all attribute values for a user identified via mobile number. All attribute values that are transmitted with the method are added and replace any existing values. Any currently existing attribute values that are not found in the API call are deleted (except for Member attributes).

Available from
v2

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userReplaceProfileByMobileNumber>
         <mobileNumber>48505606808</mobileNumber>
         <!--Zero or more repetitions:-->
         <attributes>
                <name>user.dateofbirth</name>
                <value>1985-09-22</value>
         </attributes>
      </ecm:userReplaceProfileByMobileNumber>
   </soapenv:Body>
</soapenv:Envelope>

userDelete

Description

Deletes the user identified by the specified ID.

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userDelete>
         <userId>498332</userId>
      </ecm:userDelete>
   </soapenv:Body>
</soapenv:Envelope>

userDeleteByEmail

Description

Deletes the user identified by the email address.

Available from
v1

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userDeleteByEmail>
         <email>test@test.com</email>
      </ecm:userDeleteByEmail>
   </soapenv:Body>
</soapenv:Envelope>

userDeleteByMobileNumber

Description

Deletes the user identified by the mobile number.

Available from
v7

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userDeleteByMobileNumber>
         <mobileNumber>4505606707</mobileNumber>
      </ecm:userDeleteByMobileNumber>
   </soapenv:Body>
</soapenv:Envelope>

userGetMessageHistory

Description

Retrieves the message history for a recipient for a set time frame. The maximum time frame is 31 days. The maximum number of messages returned is 5000. sendDate is presented as Datetime

Available from
v6

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecm="http://ecircle.com/developer/ecmapi">
   <soapenv:Header/>
   <soapenv:Body>
      <ecm:userGetMessageHistory>
         <userId>12508646772</userId>
         <fromDate>2018-07-01T14:00:00</fromDate>
         <toDate>2018-07-01T23:59:59</toDate>
      </ecm:userGetMessageHistory>
   </soapenv:Body>
</soapenv:Envelope>

CONTROL XML

Access
https://cook.shortest-route.com/central_support/eCMessageService Use your system URL accordingly
"Mapp Engage > Automations > Time Based" Use "Process Control XML" automation
WSDL
http://webservices.ecircle-ag.com/soap/ecm.wsdl Generic
http://webservices.ecircle-ag.com/soap/ecm-ssl.wsdl for SSL Access

Mapp Engage is able to receive and process instructions contained in an XML job package. This is offered as an alternative to the SOAP and REST interfaces for transferring larger quantities of data. This interface uses comprehensive XML data sets that are transferred to Mapp Engage in various ways. Together with the XML, other mass data like recipient lists, attachments or images are transferred.

The XML is structured in blocks that provide instructions for tasks to be executed in sequence inside the system. You can, for example:

In addition to the XML, you can include large quantities of binary data like recipient address lists.

Your messages may contain images or attachments which must be received before a message is constructed. To accommodate this, the XML and binary data are compiled together into a package prior to transmission. This package can be formatted as a zip file or MIME package.

Test Control XML

Navigation Path

This window can be used to test the syntax of a Control XML job package.

This test determines whether the tags are set correctly and if they are known by the system.

Available Actions

Notification

When an XML job package is processed, a controlResultMessage is generated and sent to the specified email address according to the result reported. The message contains an attribute processing-result which reports one of the following states:

Complete

All processing steps finished without any error indication. The result is sent to the address defined in the success-report-address node.

Partial

Initial processing was successful (package transmission), but one or more of the subsequent processing steps encountered errors. The result is sent to the address defined in the failure-report-address node. More information can be obtained from the resultType nodes contained in the controlResultMessage.

Failure

Processing failed in an early stage and did not continue. The result is sent to the address defined in the failure-report-address node.

When processing is complete, the top-level node of the control-result message sent to the success-report-address contains the attribute processing-result="COMPLETE".

The same addresses can be used for both the success-report-address and failure-report-address. Up to 10 addresses may be scheduled for each node.

Basic examples

Here are few basic examples of control xml

send message 1

Description

send one message copied from prepared message with id=1

Example request

<control xmlns="http://webservices.ecircle-ag.com/ecm" 
request-id="Unique-String" group-id="1"> 
<message message-id="new" clone-from-id="1">
<send-date> <immediately/> </send-date> 
</message>
</control>

send message 2

Description

send two prepared messages copied from prepared message with id=1 the number of messages is limited to 100

Example request

<control xmlns="http://webservices.ecircle-ag.com/ecm" 
request-id="Unique-String" group-id="1">
<message message-id="new" clone-from-id="1">
<send-date> <immediately/> </send-date>
</message>
<message message-id="new" clone-from-id="1">
<send-date> <immediately/> </send-date>
</message>
</control>

clone a group 1

Description

Clone a group from a group with id=1

Example request

<control xmlns="http://webservices.ecircle-ag.com/ecm" 
request-id="Unique-String" group-id="new" clone-from-id="1">
</control>

clone a group 2

Description

Clone a group from a group with id=1, then delete it at future date

Example request

<control xmlns="http://webservices.ecircle-ag.com/ecm" 
request-id="Unique-String" group-id="new" clone-from-id="8">
<delete-date>
<date>2019-07-03T05:00:00.084Z</date>
</delete-date>
</control>

import recipients to a group

Description

import recipients to a group with id=1

<control xmlns="http://webservices.ecircle-ag.com/ecm" request-id="1" group-id="1">
    <member-list sync-mode="update_mode" add-mode="add_no_message" use-identifier="true">
        <user>
            <email>test11@test.com</email>
            <identifier>4444</identifier>
        </user>
        <user>
            <mobilenumber>48505606709</mobilenumber>
            <identifier>5555</identifier>
        </user>
    </member-list>
</control>  

Advanced examples

Here are advanced examples

create a group and import contacts from zip file

Description

create a new group with members as 200000members.xml.gz file

<control request-id="TestGroup1" group-id="new" 
xmlns="http://webservices.ecircle-ag.com/ecm">
<group-definition preferred-channel="email">
<name>TestGroup2</name>
<email-channel>
<email>TestGroup1@centralsupport.cust-mta.com</email>
</email-channel>
</group-definition>
<member-list add-mode="add_no_message" sync-mode="add_update_mode" sync-qualifiers="overwrite_profile_completely">
<uri-reference>200000members.xml.gz</uri-reference>
</member-list>
</control>

send email or sms using channelid

Description

send email or sms using channelid, please check channelid in "Administration > Channels"

<control xmlns="http://webservices.ecircle-ag.com/ecm"  request-id="Unique-String" group-id="1">
    <message message-id="new" delete="false" channel-id="1">
        <send-date>
            <immediately/>
        </send-date>
        <content target-content-encoding="ISO-8859-1">
            <subject target-encoding="ISO-8859-1">String</subject>
            <text target-content-encoding="ISO-8859-1">String</text>
        </content>
    </message>
</control>
<control xmlns="http://webservices.ecircle-ag.com/ecm"  request-id="Unique-String" group-id="1">
    <message message-id="new" delete="false" channel-id="2">
        <send-date>
            <immediately/>
        </send-date>
<content target-content-encoding="UTF-8">
<subject>sms</subject>
<sms>sms message</sms>
</content>
</message>
</control>

send push message

Description

send push message, works provide push message is correctly setup. the example provides additional headers

<?xml version="1.0" encoding="UTF-8"?>
<control
    xmlns="http://webservices.ecircle-ag.com/ecm"  request-id="Unique-String" group-id="1200533401">
    <message message-id="new" delete="false">
        <send-date>
            <immediately/>
        </send-date>
        <name>Message Name</name>
        <content target-content-encoding="UTF-8">
            <subject target-encoding="UTF-8">Another control XML test</subject>
            <additional-msg-headers>
                <header>
                    <name>X-eC-messenger-appid</name>
                    <value>36</value>
                </header>
                <header>
                    <name>X-eC-messenger-schedule_type</name>
                    <value>DEFAULT</value>
                </header>
                <header>
                    <name>X-eC-messenger-overdue</name>
                    <value>NEXT_DAY</value>
                </header>
            </additional-msg-headers>
            <fax target-content-encoding="UTF-8">hello</fax>
        </content>
    </message>
</control>

Description

preserve-link-category and message-tag tags examples

<control
    xmlns="http://webservices.ecircle-ag.com/ecm" request-id="Unique-String" group-id="1200735989">
    <message message-id="new" clone-from-id="1202515907">
        <send-date>
            <immediately/>
        </send-date>
        <preserve-link-category>true</preserve-link-category>
    </message>
</control>
<control
    xmlns="http://webservices.ecircle-ag.com/ecm" request-id="Unique-String" group-id="1200735989">
    <message message-id="new" clone-from-id="1202515907">
        <send-date>
            <immediately/>
        </send-date>
        <message-tag>2017_campaign</message-tag>
    </message>
</control>

split sendout

Description

split sendout

<control
    xmlns="http://webservices.ecircle-ag.com/ecm" request-id="a669e5c5-bd43-42b1-aab0-0094370ceadc" group-id="new" clone-from-id="1">
    <group-definition
        xmlns="http://webservices.ecircle-ag.com/ecm">
        <name>Group Name</name>
        <description>ClonedGroup</description>
        <email-channel>
            <from-handling>
                <special>
                    <email>remitente_GrupoA@example.com</email>
                    <name>Remitente_GrupoA</name>
                </special>
            </from-handling>
            <reply-to-handling>
                <autoresponder>
                    <email>reply@example.com</email>
                    <name>reply</name>
                </autoresponder>
            </reply-to-handling>
        </email-channel>
        <io-control>
            <sendout-speed>12000</sendout-speed>
        </io-control>
    </group-definition>
    <member-list sync-mode="replace_keep_bounces"
        xmlns="http://webservices.ecircle-ag.com/ecm">
        <uri-reference>200000members.xml.gz</uri-reference>
    </member-list>
    <split-message criterion="opening-rate"
        xmlns="http://webservices.ecircle-ag.com/ecm">
        <test-message message-id="750398653">
            <percentage>50</percentage>
        </test-message>
        <test-message message-id="750451323">
            <percentage>50</percentage>
        </test-message>
        <split-schedule-date>
            <date>2013-05-22T10:45:00Z</date>
        </split-schedule-date>
        <schedule-date>
            <date>2013-05-25T09:15:00Z</date>
        </schedule-date>
    </split-message>
    <success-report-address
        xmlns="http://webservices.ecircle-ag.com/ecm">
        <email>report@example.com</email>
    </success-report-address>
    <failure-report-address
        xmlns="http://webservices.ecircle-ag.com/ecm">
        <email>report@example.com</email>
    </failure-report-address>
    <delete-date
        xmlns="http://webservices.ecircle-ag.com/ecm">
        <date>2013-07-25T09:15:00Z</date>
    </delete-date>
</control>

example with explanations

Description

Example with explanations

Errors and Exceptions

These are all the possible exceptions raised by the server whenever your request fails.

AsyncException

An exception that occurs when a asynchronous call fails.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.

BatchException

An exception occurred during processing of a list of objects. When this exception occurs, all processing ends.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.
index Integer Index of batchElement objects that were processed before the error was encountered.
reason String Explanation of why an error occurred.

InvalidParameterException

An exception returned if an input parameter has an invalid value.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.
parameterName String The name of the parameter that is invalid. This is the parameter name used in the API documentation. For list parameters, the offset of the invalid element within the list is specified as a suffix. The suffix is the list offset (starting with zero for the first element) in square brackets.
propertyName String The name of the property containing the invalid value. This only applies to complex types.
value String The erroneous value.

LandingpageException

A problem occurred with a landing page.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.

NoSuchObjectException

An exception is returned if an object is not be found with the given property name (ID). This can be for different reasons, for example, the object has ben deleted or the propertyName is wrong.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.
objectType String The object type.
propertyName String The name of the property used to look up the object.
propertyValue String The value of the property used to look up the object.

ObjectAlreadyExistsException

An exception is returned if the object to be created already exists.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.
objectType String The object type.
propertyName String The name of the property that violates the unique constraint.
propertyValue String The value of the property that violates the unique constraint.

SystemUserErrorException

A problem occurs when related system user logic has been violated.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.

UnexpectedErrorException

The base type for all exceptions representing unexpected error conditions.

Properties

Name Type Description
errorActor ErrorActor The party that is responsible for the error.
errorCode ErrorCode The error code.
message String A detailed error description. Note: The error description is not intended for automatic processing but provides human-readable error information.
errorId String The ID of the error.

Types

Boolean

Example

false

Boolean data type: true (1) or false (0).

Integer

Example

1

A numeric value between -100000000000000000 and 1000000000000000000.

Long

Example

353576673

Typically an ID of an entity.

A numeric value between -100000000000000000 and 1000000000000000000.

String

Example

'Test'

Text strings. A string with a maximum of 2000 characters can be used.

AsyncResult

The result of a topic.

Properties

Name Type Description Constraints
queueId String ID of the result queue. required
output Attribute[] A list of attributes containing the result information. required

Attachment

A message attachment.

Properties

Name Type Description Constraints
name String The name of the attachment. required
contentType String The attachment content type. required
content String The attachment content in Base64 encoding. required

AttachmentReference

Reference content to be attached to the message.

Properties

Name Type Description Constraints
contentId String The internal ID of the content store element. This value is used to get, update, or delete the content store element with an API call. required
reference String The nine-digit reference ID of a content store element as visible in the user interface. This is the value used by placeholders to insert the element into the message or add it as an attachment. This value is also used as the MIME ID of the attachment. required

Attribute

A name and value pair that can be assigned as an attribute to various objects in the system.

Properties

Name Type Description Constraints
name String The name of the attribute. required
value String The value of the attribute. Note that although provided here as a string, you may need to convert it into a specific type to work with a specific request. If the value is not sent with the expected data type, an error can occur. required

AttributeDefinition

An object that contains the definition of a custom attribute.

Properties

Name Type Description Constraints
name String The attribute name. required maxLength:80
type AttributeType The data type assigned to the attribute value. required
enumerationValues String[] A list of set values that define an enumeration. The values are assigned the data type specified in the AttributeType property. optionalmaxLength:1,000
active Boolean This property determines whether the attribute is active (true) or archived (false). required

AttributeType

The data type assigned to the attribute value.

Enumeration Values

Value Description
BOOLEAN Attribute values are stored in Boolean data type: true (1) or false (0).
DATE Attribute values are stored as dates. Enter dates in the ISO 8601 date time format. For example, the format for a date is 2014-09-20, a date with time is 2014-09-20T13:45:55.
NUMBER Attribute values are stored as numbers. A numeric value between -100000000000000000 and 1000000000000000000.
STRING Attribute values are stored as text strings. A string with a maximum of 2000 characters can be used.

AutomationDetails

Available in version v7+

An object that contains detailed information about an automation.

Properties

Name Type Description Constraints
id Long The ID of the automation for which the information is returned. required
name String The name of the automation. The name is defined by the system user when the automation is created. The name identifies the automation in the system. The name does not have to be unique in the system. required
description String The description entered for the automation. The description makes it easier to identify the automation in the system. required
automationType AutomationType An enumerated type that indicates whether the automation is time-based or eventbased. A list of possible values is available in the description for the AutomationType type. required
jobType String A value that indicates which job is executed by the automation. required
eventType String A value that indicates which event initiates execution of the job. A list of possible values is available in the description for the EventType type. Use only for automations with the EVENT_BASED automationType property. required
ownerName String The name of the system user who created the automation. Provided in the format <LastName>, <FirstName>. required
nextExecutionDate String The date when the automation is next scheduled for execution. optional
endDate String The date when the automation is scheduled to finish. optional
dateOfLastError String The date and time of the most recent error. An error does not mean that the execution failed. optional
causeOfLastError String Error text for the most recent error. required
executionsCount Long The total number of executions to date. required
status AutomationStatus An enumerated type that indicates the current status of the automation. A list of possible values is available in the description for the AutomationStatus type. required
archived Boolean True if the automation is currently archived, otherwise false. required

AutomationFilter

Available in version v7+

A filter type that determines which automation is returned by a query. Filters applied against properties with string data types are not case-sensitive.

Properties

Name Type Description Constraints
name String The name of the automation. The name is defined by the system user when the automation is created. The name identifies the automation in the system. The name does not have to be unique in the system. optional
automationType AutomationType An enumerated type that indicates whether the automation is time-based or event based. A list of possible values is available in the description for the AutomationType type. required
jobType String An enumerated type that indicates which job is executed by the automation. A list of possible values is available in the description for the AutomationJobType type. optional
eventType String An enumerated type that indicates which event initiates execution of the job. A list of possible values is available in the description for the EventType type. Use only for automations with the EVENT_BASED automationType property. optional
ownerName String The name of the system user who created the automation. Provided in the format LastName, FirstName. optional
nextExecutionDateFrom String The start date for a time frame in which queries for automations that are scheduled for next execution after the specified time. Specify using ISO 8601 date format. optional
nextExecutionDateTo String The end date for a time frame in which queries for automations that are scheduled for next execution before the specified time. Specify using ISO 8601 date format. Must be later than nextExecutionDateFrom when both dates are specified. optional
endDateFrom String The start date for a time frame in which queries for the automations that are scheduled to finish after the specified time. Specify using ISO 8601 date format. optional
endDateTo String The end date for a time frame in which queries for automations that are scheduled to finish before the specified time. Specify using ISO 8601 date format. Must be later than endDateFrom when both dates are specified. optional
hasErrors Boolean True if the number of errors encountered during execution is greater than zero, otherwise false. An error does not mean that the execution failed. required
status AutomationStatus An enumerated type that indicates the current status of the automation. A list of possible values is available in the description for the AutomationStatus type. optional
archived Boolean True if the automation is currently archived, otherwise false. required

AutomationStatus

Available in version v7+

An enumerated type that represents the current status of an automation.

Enumeration Values

Value Description
ACTIVE_RUNNING The automation is active and has been executed at least once by the system. Only an automation with a scheduled repetition can have this status.
ACTIVE_SCHEDULED The automation is active and the start date is in the future. The automation will run according to the schedule defined in the system.
INACTIVE The automation is inactive. The automation is not executed by the system.
INACTIVE_DEACTIVATED The automation was manually deactivated before all executions were finished. The automation is not executed by the system. Only an automation with a scheduled repetition can have this status.
INACTIVE_DONE All scheduled executions are finished. The automation has been completed by the system for the last time.

AutomationType

Available in version v7+

Enumeration Values

Value Description
EVENT_BASED An automation that executes a job every time a defined event takes place.
TIME_BASED An automation that executes a job on a regular schedule. You can also send instructions to run a time-based automation once.

BatchReport

A report that contains the result of the batch processing job. The report contains a summary of the job execution and detailed information for any errors encountered.

Properties

Name Type Description Constraints
batchSize Long The number of email messages passed for processing. required
succeededCount Long The number of email messages processed successfully. required
errors CallResult A list of errors encountered, if any. required

-

BlacklistEntry

Available in version v4+

A blacklist entry.

Properties

Name Type Description Constraints
type BlacklistEntryType Specifies the entry type. required
pattern String The pattern to be blacklisted. Depending on the type property, this may be an email address, an email domain, or a phone number. required

BlacklistEntryType

Available in version v4+

Specifies the type of a blacklist entry.

Enumeration Values

Value Description
EMAIL A single email address.
EMAIL_DOMAIN An email domain. Entries of this type match all email addresses from the specified email domain.
PHONE_NUMBER A mobile phone number.

CallResult

An object carrying information about result of an API call for a specified entity.

Properties

Name Type Description Constraints
entityKey String The ID assigned to the specified entity, for example, message ID, group ID, name, or index. required maxLength:100
code String A short information code - mostly error code. optionalmaxLength:50
message String Detailed information ### Error message. optionalmaxLength:500

CmsMessageDefinition

Available in version v3+

Contains information about a related CMS message.

Properties

Name Type Description Constraints
id Long The ID of the CMS message. required
superGroupId Long The ID of the SuperGroup. required
ownerId Long The user ID of the CMS message owner. required
masterId String The ID of the master template. required maxLength:30
masterLocation String Location where the master template is saved. required maxLength:50
description String Name of the message created via CMS. required maxLength:500
externalId String The external ID assigned to the message. You can add this ID as a parameter to links within a message. This information helps you track statistics in an external web analytics platform. required maxLength:250
subject String Subject of the message created with the CMS. required maxLength:500
dueDate String Date when the message will be sent. required maxLength:32
creationDate String Date on which the CMS message was created. required maxLength:32
encoding String Encoding of the message created with the CMS. required maxLength:200
active Boolean A currently active CMS message. Active CMS messages can be previewed, edited, and sent. required
archived Boolean A currently archived CMS message. Archived CMS messages can only be previewed (not edited or sent). required

Contact Type

Available in version v7+

An object that represents a contact in Mapp Engage, including any identifiers and attributes. You must specify at least one of the following identifiers to store or retrieve a valid contact object: email address, mobile number, or mobile app alias.

Properties

Name Type Description Constraints
contactId Long The internal ID assigned to the contact profile. required
emailAddress String The contact email address. Must be unique in the system. required
mobileNumber String The contact mobile number. Must be unique in the system. required
applicationAlias String The contact mobile app alias. Must be unique in the system. required
identifier String An identifier for the contact which was generated by an external system. required
attributes Attribute A list of profile attributes. Can include both standard and custom attributes. required

Contact_

Available in version v7+

An object that represents a contact in Mapp Engage, including any identifiers and attributes. You must specify at least one of the following identifiers* to store or retrieve a valid contact object: email address, mobile number, or mobile app alias.

Properties

Name Type Description Constraints
contactId Long The internal ID assigned to the contact profile. required
emailAddress String The contact email address. Must be unique in the system. required*
mobileNumber String The contact mobile number. Must be unique in the system. required*
applicationAlias String The contact mobile app alias. Must be unique in the system. required*
identifier String An identifier for the contact which was generated by an external system. required*
attributes Attribute A list of profile attributes.Can include both standard and custom attributes.

ContactIdentifier

Available in version v7+

An object that associates a contact identifier with a value.

Properties

Name Type Description Constraints
type ContactIdentifierType The type of identifier. required
value String The value of the contact identifier. requiredminLength:1

ContactIdentifierType

Available in version v7+

An enumerated type that indicates which identifer is used to reference the contact.

Enumeration Values

Value Description
APP_ALIAS The identifier is a mobile app alias.
EMAIL The identifier is an email address.
EXTERNAL The identifier is a value generated by an external system.
ID Identifier.
MOBILE The identifier is a mobile number.

CreateResult

Available in version v4+

An object that describes whether the corresponding blacklist entry has been added to the system or not.

Datetime type

The number of milliseconds that have elapsed since January 1, 1970. For example "1532606566000"

To convert from "2018-07-26" use epochconverter.com

DeleteResult

Available in version v4+

An object that describes whether the corresponding blacklist entry has been deleted from the system or not.

DraftMessage Type

Available in version v6+

An object that contains the definitions for a draft message. A draft message has not been scheduled or sent and is not assigned to a group for sendout. A draft can be saved and edited at a later date or used as a template for other messages.

Properties

Name Type Description Constraints
id Long The ID of the draft message. optional
name String The name of the draft message. required
externalId String The external message ID assigned to the draft message. The external message ID is inserted into message links through the use of link parameters. optionalmaxLength:250
messageCategoryId Long The message category ID. optional
message MessageBase An object that contains the message content and content-related properties. required

DraftMessageFilter

Available in version v7+

A filter object that determines which messages are included in the list of returned draft message summary objects.

Properties

Name Type Description Constraints
externalMessageId String The external message ID. optional
messageName String The name of the messsage. optional
subjectLine String The message subject line. optional
authorName String The name of the message author. Uses the format: lastname, firstname. optional
authorId Long The user ID of the message author. optional
messageCategoryId Long The message category ID. optional
creationDateFrom String Start date of time frame from which a draft message was created. Uses ISO 8601 date time format. optional
creationDateTo String End date of time frame until which a draft message was created. Uses ISO 8601 date time format. optional
lastUpdateDateFrom String Start date of time frame from which a draft message was last updated. Uses ISO 8601 date time format. optional
lastUpdateDateTo String End date of time frame until which a draft message was last updated. Uses ISO 8601 date time format. optional

DraftMessageSummary

Available in version v7+

An object that provides summary information for a draft message.

Properties

Name Type Description Constraints
authorId Long The user ID of the message author. optional
authorName String The name of the message author. Uses the format: lastname, firstname. optional
creationDate String The date the draft message was created. Uses ISO 8601 format. optional
externalMessageId String The external message ID. optional
id Long The message ID. optional
isArchived Boolean Indicates whether the message is archived. required
lastUpdateDate String The date the draft message was last updated. Uses ISO 8601 format. optional
messageCategoryId Long The message category ID. optional
messageName String The name of the message. optional
subjectLine String The message subject line. optional

ErrorActor

Enumeration Values

Value Description
CLIENT The client who issued the request.
SERVER The server.

ErrorCode

The complete list of error codes returned by the API.

Enumeration Values

Value Description
ARCHIVED_ATTRIBUTE Name of the attribute that is archived.
BLACKLISTED The contact or email domain is blacklisted.
INCORRECT_STATUS
INVALID_ATTRIBUTE Name of the attribute that generates an error.
INVALID_ATTRIBUTE_VALUE Value of the attribute that generates an error.
INVALID_JOB_ARGUMENT
INVALID_JOB_DEFINITION_ID
INVALID_PARAMETER A parameter value is invalid.
INVALID_REQUEST The request could not be processed. Please check the error detail message.
MAXIMUM_ATTRIBUTE_COUNT_EXCEEDED The maximum number of custom attributes has been reached. No further attributes can be created.
MAXIMUM_SIZE_EXCEEDED
MISSING_JOB_ARGUMENT
MISSING_PARAMETER A mandatory parameter is missing.
NO_SUCH_ATTRIBUTE There is no attribute with the given name.
NO_SUCH_OBJECT An object reference points to an object that does not exist.
OBJECT_ALREADY_EXISTS An object to be created already exists.
OPERATION_DISABLED This operation is disabled for this system.
PERMISSION_DENIED The API user account does not have the required permission.
SOCIAL_USER_MANAGEMENT_ERROR Social system role cannot be updated, because Mapp Engage was unable to connect to Social.
SYSTEM_USER_HAS_BILLING_ITEMS There are billing items referenced to system user.
SYSTEM_USER_HAS_SOCIAL_ROLE System user has an assigned Social Role.
SYSTEM_USER_IS_INACTIVE System user is deactivated (expiration date is in past).
SYSTEM_USER_IS_OWNER System user is an owner of at least one entity in the system.
UNEXPECTED_ERROR An unexpected backend error has occurred.

Group Type

The object that describes the main properties of a group.

Properties

Name Type Description Constraints
id Long Internal ID of the group. required
name String Name of the group. The name must be unique in the system. required maxLength:150
description String A description of the group. optionalmaxLength:3,000
email String Email for the group clone. The email must be unique and valid. required maxLength:128 minLength:5

GroupCloneOptions

Object for description of how to clone a given group and mandatory fields for the cloned group.

Properties

Name Type Description Constraints
name String Name of the group clone. The name must be unique in the system. required maxLength:150
description String Description for the group clone. optionalmaxLength:3,000
email String Email for the group clone. The email must be unique and valid. required
includePreparedMessages Boolean If true, the group is cloned with all prepared messages, otherwise without. required
includeTestUsers Boolean If true, group is cloned with the test recipients, otherwise without. required
keepOwner Boolean If true, group owner from source group is added as member to the destination group and also keeps ownership of the group. required
withOwnerAsMember Boolean If true, member for the owner is created. required

GroupSettingsTemplate

A collection of group settings.

Properties

Name Type Description Constraints
id Long Every group settings template has a unique ID within the system. required
name String Name of the group settings template. required maxLength:100

HistoricalMessage

Available in version v8+

A (group) message that was sent. All personalization placeholders are resolved based upon the provided contact ID, with attribute values from the time of sendout. (Only possible if DataStore is connected.)

Properties

Name Type Description Constraints
contactId Long Unique ID of the contact for whom the message was generated required
messageId Long Unique ID of the (group) message required
name String Name of the message required
externalId String Optional external Id of the message (including resolved personalization if possible) optional
description String Optional description of the message optional
messageCategoryId Long Optional id of the message Category assigned to the message optional
processingDate String Timestamp in ISO 8601 format with processing date for this message / the sendout of the whole group message (TBD how granular the information is that we have available on message level) required
type MessageBase Image and attachment references (content store). required

LandingpageFilter

Available in version v7+

A filter object that determines which landing pages are included in the list of returned landing page summary objects.

Properties

Name Type Description Constraints
status String The current status of the landing page. required
name String The name of the landing page. required
pageName String The page name used in the URL of the landing page. required
ownerId String The user ID of the landing page owner. required
URL String The URL of the landing page. required
publishedFrom String Start date of time frame during which a landing page was published. Uses ISO 8601 date time format. required
publishedTo String End date of time frame during which a landing page was published. Uses ISO 8601 date time format. required

LandingpageSummary

Available in version v7+

An object that provides summary information for a landing page.

Properties

Name Type Description Constraints
id Long The ID of the landing page. required
status String The current status of the landing page. required
name String The name of the landing page. required
pageName String The page name used in the URL of the landing page. required
ownerId String The user ID of the landing page owner. required
description String The description entered for the landing page. required
URL String The URL of the landing page. required
redirection String The URL of the alternative website to which the recipient is redirected when the landing page is deactivated. required
expirationDate String The date when the landing page is scheduled to be automatically deactivated by the system. Uses ISO 8601 date time format. required
publishedDate String The publication date of the landing page. required
lastPublishedDate String The last publication date of the landing page. required

LinkCategory

An entity that represents a link category.

Properties

Name Type Description Constraints
id Long The ID assigned to the link category. optional
name String The name of the link category. required maxLength:200
description String A description of the link category. optional
pattern String The regular expression that defines the criteria used to determine when a link is assigned to a particular link category. For example, the regular expression .*hotel.* assigns a link category to any URL that contains the word hotel (case-sensitive). required maxLength:200

Membership Type

Available in version v2+

This object represents the relationship between a contact and a group.

Properties

Name Type Description Constraints
userId Long The ID of the contact who is a member of a group. required
groupId Long The ID of the group to which the contact belongs. required
attributes Attribute[] The member attributes for this contact in the group. required

MergeResult

A result object for attributes changes.

Properties

Name Type Description Constraints
attributeName String The attribute name. required
result MergeResultType Action that was performed. required
error ErrorCode Error code the error produced (if any). required

MergeResultType

An enumerated type that defines which action was performed on an attribute during merge and its result.

Enumeration Values

Value Description
ACTIVATED The attribute was created or archived before.
ARCHIVED The attribute was active or archived before.
CREATED A new attribute was created.
ENUM_EXTENDED An enumeration value was added to an existing attribute.
ERROR An error occurred during operation. Error details are described in the corresponding error string.

Message Type

The definition of a complete message to be sent by Mapp Engage. The properties provided determine what type of message is sent. Message types include:

- - Simple MIME messages (text or HTML part). - Multipart alternative MIME messages (text and HTML). - Multipart-mixed MIME messages.

Message attachments are referenced from the Content Store.

Properties

Name Type Description Constraints
sendoutRef String An ID assigned to the sendout. Where possible, use a number. Only characters A-Z and 0-9 are allowed. This property is not available for API versions 6 and higher. required
recipientRef String An ID assigned to the message recipient. Where possible, use a number. Only characters A-Z and 0-9 are allowed. This property is not available for API versions 6 and higher. required
from String The From address of the email in RFC-822 format. For API versions 6 and higher, this property is restricted to the format "localpart@domain". required
fromName String The name displayed in the email client as the From address in the email. This property is not available for API versions 6 and higher. required
to String The To address of the email or comma-separated list of email addresses in RFC-822 format. For API versions lower than version 6, this property is restricted to a single email address with the format "localpart@domain". API versions 6 and higher can enter a comma-separated list of recipients. The To address is required for each recipient. A name is optional. Enter addresses in the correct format recognized by the email header. An email address with name is entered as: "Joe Sample" <joe.sample@email.com>. This property is required. required
cc String The CC address of the email or comma-separated list of email addresses in RFC-822 format. This property is only available for API versions 6 and higher. This property is optional. required
bcc String The BCC address of the email or comma-separated list of email addresses in RFC-822 format. This property is only available for API versions 6 and higher. This property is optional. required
toName String The name displayed in the email client for the To address. This property is not available for API versions 6 and higher. API versions 6 and higher enter this value as part of the "to" property. required
replyTo String The Reply-To email address in RFC-822 format. For API versions 6 and higher, this property is restricted to a single email address with the format "localpart@domain". required
replyToName String The name displayed in the email client for the Reply-To email address. This property is not available for API versions 6 and higher. required
headers Attribute[] Additional email headers that are added to the message. required
subject String The message subject. required
textBody String The text body part of the message. required
htmlBody String The HTML body part of the message. required
attachmentReferences AttachmentReference[] A list of references to images and attachments saved to the Content Store. required
attachments Attachment[] A list of attachments. required

MessageBase

Available in version v6+

An object that contains the message content and content-related properties. The MessageBase object does not contain information related to the message context, for example sendout status and group assignment. This object can be embedded in wrapper objects which provide the required context.

Properties

Name Type Description Constraints
subject String The message subject. required
emailBodyText String The text body part of the message. optional
emailBodyHtml String The HTML body part of the message. optional
smsText String The SMS text part of the message. optional
faxText String The fax text part of the message. optional
emailHeaders Attribute[] Additional email headers that are added to the message. required
attachments Attachment[] A list of attachments. required
attachmentReferences AttachmentReference[] A list of references to images and attachments saved to the Content Store. required
encoding String Specifies the encoding of the message. If not specified, the default encoding is used. optional
encodingSMS String Specifies the encoding used to transmit the message from Mapp Engage to the cellular network. The actual encoding used to send the SMS message is based on definitions used for cellular communication:

- - Messages transmitted with ISO-8859-1 are sent with GSM 7-bit encoding. - Messages transmitted with UTF-8 are sent with 16-bit encoding. If not specified, the default encoding is used. | optional | | imageHandlingMode | String | Defines how images are embedded in the message.

Possible options: - "none": Images are left untouched: This item leaves the tags (addresses) of the images unchanged. The images are loaded from the provided address. This setting is used when additional information is included in the link, for example, in the form of a tracking pixel. This is the default option. - "inline": Images are inlined into the message (Offline HTML): The images are included as inline attachments in the email. Mapp Engage accesses the pictures from the location where they are saved (HTTP or HTTPS address) and includes them in the email. Afterward, the addresses of the pictures in the message (HTML tags) are updated to refer to the inline attachments. The images included in the message do not have to be loaded from an external address. The message recipient does not have to be online to view the images in the message. - "host": Images are hosted on the Mapp Engage servers (Online HTML): The images are not provided from their original servers, they are uploaded to the Mapp Engage servers and linked from there. Flash movies (*.swf) in the HTML and Flash HTML fields in the message are treated as images. It is not possible to inline files with these formats. The flash movies are specified with a specially formatted <object> block. If not specified, the default option is applied. | optional |

MessageContent

Additional message content for personalization.

Properties

Name Type Description Constraints
parameters Attribute[] A list of attributes that can be used to further personalize the sendout. These values are accessible by a "param" placeholder. required
attachments Attachment[] A list of attachments. required

MessageFilter

Available in version v7+

A filter object that determines which messages are included in the list of returned message summary objects.

Properties

Name Type Description Constraints
externalMessageId String The external message ID optional
messageName String The name of the message. optional
subjectLine String The message subject line. optional
authorName String The name of the message author. Uses the format: lastname, firstname. optional
authorId Long The user ID of the message author. optional
messageCategoryId Long The message category ID. optional
groupName String Name of the group assigned to the message. optional
groupId Long The group ID. optional
groupCategoryName String The name of the group category. optional
groupCategoryId Long The group category ID. optional
type MessageType The message type. optional
status MessageStatus The current status of the message. optional
sendoutDateFrom String Start date of time frame from which a message was sent. Uses ISO 8601 date time format. optional
sendoutDateTo String End date of time frame until which a message was sent. Uses ISO 8601 date time format. optional

MessageHistory

Available in version v6+

An object that contains details for a specific sent message.

Properties

Name Type Description Constraints
messageID Long The ID of the sent message. required
externalTransactionId String The transactional message ID assigned to the sent message, if defined. required
externalMessageID String The external message ID assigned to the sent message, if defined. required
messageName String The name of the message. required
messageSubject String The subject line of the message, excluding personalizations. required
groupId Long The ID of the group with which the message was sent. required
groupName String The name of the group with which the message was sent. required
groupEmail String The email address of the group with which the message was sent. required
sendDate Long Date and time the message was sent. required
messageType String The message type assigned to the sent message. required
status String The status of the message, either Sent or Skipped. required
clicked Boolean The Clicked status for the sent message. When true, the recipient clicked a link in the message. When false, the recipient has not yet clicked a link in the message. required
opened Boolean The Opened status for the sent message. When true, the recipient opened the message. When false, the recipient has not yet opened the message. required

MessageStatistics

Available in version v5+

An object that contains detailed information and statistical values that are related to a sent message.

Properties

Name Type Description Constraints
messageId Long ID of the message. required
messageName String Name of the message. required
messageSubject String Subject of the message. required
externalMessageId String External ID assigned to the message. required
groupId Long ID of the group with which the message was sent. required
groupName String Name of the group with which the message was sent. required
groupSize Long The number of members contained in the group with which the message was sent. required
sendoutStartDate Long Start date of the sendout. required
sendoutEndDate Long End date of the sendout. required
transferStartDate Long Date and time when the message transfer started. required
transferEndDate Long Date and time when the message transfer finished. required
selectionName String Name of the selection applied to the sendout, if used. required
statisticValues Attribute A list of attributes that contain the statistical values related to the sent message. required

MessageStatus

Available in version v7+

The current status of a message.

Enumeration Values

Value Description
CANCELLED
INTERUPTED
MODERATED
PROCESSED
PROCESSING
READY
SCHEDULED
SENT
TRANSPORTING

MessageSummary

Available in version v7+

An object that provides summary information for a message.

Properties

Name Type Description Constraints
authorId Long The user ID of the message author. optional
authorName String The name of the message author. Uses the format: lastname, firstname. optional
externalMessageId String The external message ID. optional
groupCategoryId Long The group category ID. optional
groupId Long The group ID. optional
id Long The message ID. optional
isArchived Boolean Indicates whether the message is archived. required
isSystemMessage Boolean Indicates whether the message was generated automatically by the system. required
messageCategoryId Long The message category ID. optional
messageName String The name of the message. optional
originalMessageId Long The ID of the prepared message from which a message sendout was generated. optional
sendoutDate String The date the message was sent. Uses ISO 8601 format. optional
status MessageStatus The current status of the message. optional
subjectLine String The message subject line. optional
type MessageType The message type. optional

MessageTimeDistribution

Available in version v6+

An object that contains basic message properties and time distribution statsitics for recipient activity. This information can be retrieved for sent group and single messages.

Properties

Name Type Description Constraints
messageId Long The message ID. required
messageName String The name of the message. required
messageSubject String The message subject line. required
groupName String Name of the group to which the message was sent. required
sendout Long The date and time on which the sendout was started. required
confirmedOpens Long The total number of times a message was opened. required
confirmedOpeners Long The number of recipients who opened a message. required
totalClicks Long The total number of clicks on a link. required
clickers Long The number of recipients who have clicked on any link in the message. required
acceptedMessages Long The number of messages that were accepted by the email provider's Message Transfer Agent (MTA). required
messagesOpened Long The number of recipients who have opened a message. required
messagesClicked Long The number of recipients who have clicked on any link in the message. required
timeFrameStart Long The start of the time period for which statistics are reported. required
timeFrameEnd Long The end of the time period for which statistics are reported. required
interval TimeDistributionInterval An enumerated type object that determines the interval for which message statistics are aggregated. Available aggregations are daily or hourly. required
periods MessageTimeDistributionPeriod[] A list of MessageTimeDistributionPeriod objects that refer to statistical data points within the time frame. required

MessageTimeDistributionPeriod

Available in version v6+

An object that represents the statistical data points pertaining to a specific time period.

Properties

Name Type Description Constraints
messageId Long The message ID. required
periodStart Long The start of the time period. required
periodEnd Long The end of the time period. required
statisticValues Attribute[] A list of Attribute objects that contain aggregated message statistics data for the time period. required

MessageType

Available in version v7+

The message type.

Enumeration Values

Value Description
NORMAL A message that was sent as part of a group sendout, in other words, a group message. A group message is a message that is generated by a sendout to a group.
SINGLE A message that was sent as part of a single message sendout, in other words, a single message sent to a single recipient. A single message is always a prepared message.
SPLIT_MAIN The main message of a split sendout.
SPLIT_TEST A test variation sent as part of a split sendout.
SUB A message that was sent as part of a SuperMessage to a SuperGroup.

MethodResult

Available in version v1-2

An object that contains information that describes the result of a method for a given entity.

Properties

Name Type Description Constraints
entityId Long The ID of the entity (message ID, group ID). This property is not available for API versions 3 and higher. required
errorCode ErrorCode The error code. This property is not available for API versions 3 and higher. required
errorMessage String The error message. This property is not available for API versions 3 and higher. required

PreparedMessageFilter

Available in version v7+

A filter object that determines which prepared messages are included in the list of returned prepared message summary objects.

Properties

Name Type Description Constraints
externalMessageId String The external message ID optional
messageName String The name of the message. optional
subjectLine String The message subject line. optional
authorName String The name of the message author. Uses the format: lastname, firstname. optional
authorId Long The user ID of the message author. optional
messageCategoryId Long The message category ID. optional
groupName String Name of the group assigned to the message. optional
groupId Long The group ID. optional
groupCategoryName String The name of the group category. optional
groupCategoryId Long The group category ID. optional
creationDateFrom String Start date of time frame from which a prepared message was created. Uses ISO 8601 date time format. optional
creationDateTo String End date of time frame until which a prepared message was created. Uses ISO 8601 date time format. optional
lastUpdateDateFrom String Start date of time frame from which a prepared message was last updated. Uses ISO 8601 date time format. optional
lastUpdateDateTo String End date of time frame until which a prepared message was last updated. Uses ISO 8601 date time format. optional

PreparedMessageSummary

Available in version v7+

An object that provides summary information suitable for a prepared message.

Properties

Name Type Description Constraints
authorId Long The user ID of the message author. optional
authorName String The name of the message author. Uses the format: lastname, firstname. optional
creationDate String The date the prepared message was created. Uses ISO 8601 format. optional
externalMessageId String The external message ID. optional
groupCategoryId Long The group category ID. optional
groupCategoryName String The name of the group category. optional
groupId Long The group ID. optional
groupName String Name of the group assigned to the message. optional
id Long The message ID. optional
isArchived Boolean Indicates whether the prepared message is archived. required
isSystemMessage Boolean Indicates whether the message was generated automatically by the system. required
lastUpdateDate String The date the prepared message was last updated. Uses ISO 8601 format. optional
messageCategoryId Long The message category ID. optional
messageName String The name of the message. optional
subjectLine String The message subject line. optional

ProcessAction

Available in version v7+

An enumerated type that represents an action that can be applied to a running process.

Enumeration Values

Value Description
CANCEL Permanently stops work on a paused process. Can only be applied to a process with the status value PAUSED. Work cannot be resumed on a cancelled process.
PAUSE Temporarily halts work on a process. Can only be applied to a process with the status value PROCESSING. It is possible to resume work on a paused process.
RESUME Continues work on a process that is paused. Can only be applied to a process with the status value PAUSED.

ProcessDetails

Available in version v7+

An object that contains detailed information about a process.

Properties

Name Type Description Constraints
processId Long The ID of the process for which the information is returned. required
processName String The name of the entity that the process executes. A name is assigned to each entity by an individual system user or by the system when the entity is created. The name provides additional information about the task that is performed. required
entityType String The kind of entity the process executes. required
entityId String The unique identification number that the system automatically assigns to each entity. required
status ProcessStatus An enumerated type that represents the current status of a process. required
processedCount Long The number of chunks on which work is successfully completed. required
totalCount Long The entire number of chunks in the process (meaning, the number of chunks into which the work of the process is divided). required
startDate String The date and time the process began. required
estimatedEndDate String The date and time that a process is expected to be finished (if an estimate is available). required
endDate String The date and time that the process was completed. required
duration Long The length of time the process runs in hours, minutes, and seconds. required
executorName String The name of the system user who created the entity that is executed in the process. Provided in the format LastName, FirstName. required
executorEmail String The email address of the system user who created the entity that is executed in the process. required
error String If an error causes the execution of a process to fail, this property contains information about the kind of error that occurred. required

ProcessingType

Available in version v7+

An enumerated type that indicates how the process is executed.

Enumeration Values

Value Description
ASYNC The process is executed asynchronously.
SYNC The process is executed synchronously.

ProcessStatus

Available in version v7+

An enumerated type that represents the current status of a process.

Enumeration Values

Value Description
FAILED Work for this process has ended. This process could not be completed successfully.
FINISHED All work for this process is successfully completed.
PAUSED Work for this process is temporarily halted. Work on this process can be resumed.
PROCESSING The process is currently running.

RelatedDataFilter

Available in version v4+

Object for flitering the records to be selected by related data methods. If filter attributes are provided, only records with matching values for all column and value pairs are selected.

Properties

Name Type Description Constraints
datasetName String Name of the related data set. All related data records reside within a data set identified by a unique name. required
key String Key defining which record(s) to select from the data set. required
filter Attribute Optional list of Attribute objects used for filtering which records to select. Each Attribute object represents a column name and the desired value the records need to have in that column in order to be selected. All other records are filtered from the result set. Providing a filter prevents an operation from being carried out on all records with the same key in a dataset defined with non-unique keys, e.g. when updating a specific order when order history is stored with email address as keys. optional

RelatedDataRecord

Available in version v4+

Object that contains a Related Data record.

Properties

Name Type Description Constraints
datasetName String Name of the related data set. All related data records reside within a data set identified by a unique name. required
key String Key defining which record(s) to select from the related data set. required
data Attribute[] Data values to be written to one or more related data records by providing pairs of column names and values to be written into each column. The Attribute type is also used to transmit other name and value pairs, for example, profile attributes. required

RelatedDataRecordAndFilter

Available in version v4+

Object containing a related data record and a filter describing which records to select. Used to update rows in a related data set. If filter attributes are provided, only records with matching values for all column and value pairs are selected.

Properties

Name Type Description Constraints
datasetName String Name of the related data set in which records will be updated. All related data records reside within a data set identified by a unique name. required
key String Key defining which record(s) to select from the related data set. required
data Attribute[] A list of Attribute objects describing data values to be written to one or more related data records. Each Attribute object represents a column name and the desired value to be written into that column. Only the subset of columns to be updated needs to be provided. Columns for provided column names not exiting in the dataset will not be created on the fly. required
filter Attribute[] Optional list of Attribute objects used for filtering which related data records to select. Each Attribute object represents a column name and the desired value the records need to have in that column in order to be selected. All other records are filtered from the result set. Providing a filter is used to prevent an operation to be carried out on all records with the same key in a dataset defined with non-unique keys, e.g. when updating a specific order when order history is stored with email address as keys. optional

Available in version v7+

An object that contains the ID of the process initiated by the request and the processing type. The result of an time-based automation that was executed using the runOnce request. When there is no value for the processID property, there were no system processes involved in the execution.

Properties

Name Type Description Constraints
processId Long The ID of the process initiated by the request. optional
processingType ProcessingType The type of processing use to execute the process. required

SubscriptionMode

Available in version v2+

Defines the subscription method used to add a contact to a group.

Enumeration Values

Value Description
CONFIRMED_OPT_IN New contacts receive a welcome message via email when they are added to the group. Despite the label used for this value, the contact does not need to confirm the subscription. A single opt-in subscription.
DOUBLE_OPT_IN New contacts receive an invitation to join the group via email. The contact must accept the invitation before they are added to the group. A double opt-in subscription.
OPT_IN New contacts are added to the group without notification.

SystemUser Type

Available in version v8+

This object represents a system user who will be created/updated in system.

Properties

Name Type Description Constraints
id Long All system users have a unique ID within the system. Not used in create method. optional
type String Defines type of a system user. required
email String All system users in the system must have an email address. The email address must be unique in the system. required maxLength:128
firstName String FirstName of a system user. required maxLength:49
lastName String LastName of a system user. required maxLength:49
language String ISO-639 code for a language of a system user. required
timeZone String The time zone of the system user. required
messagingRole String Messaging role of a system user. required
expiryDate String Expiration date of a system user. required
externalId String External ID of a system user. The external ID must be unique in the system. required maxLength:99
lastLoginDate String Last login date to system of a system user. Not used in create/update method. optional

User Type

This object represents a single system user or contact. Accounts for system users and contacts were previously managed in the same data tables in Mapp Engage. You can still use this type definition to work with system user and contact records.

Properties

Name Type Description Constraints
id Long All system users and contacts have a unique ID within the system. required
email String All system users and contacts in the system must have an email address. The email address must be unique in the system. required maxLength:128 minLength:5
mobileNumber String A system user or contact can have a mobile number. The mobile number must be unique in the system. required
identifier String Optionally, a contact may have an identifier generated by an external system. required