Issuu on Google+

emarsys eMarketing Suite API Reference Manual April, 2013 Based on emarsys eMarketing Suite 7.1

Š 2000-2013 emarsys eMarketing Systems AG


emarsys eMarketing Suite

Contents Introduction API Interface Reference .................................................................................................................................. 5 1 E-Mails ....................................................................................................................... 5 Querying E-Mail Lists 7 Creating....................................................................................................................... E-Mails ....................................................................................................................... 9 E-Mail Attributes ....................................................................................................................... 11 Launching E-Mails ....................................................................................................................... 13 Previewing E-Mails ....................................................................................................................... 14 Sending Test E-Mails 16 Viewing....................................................................................................................... Response Summaries 17 Viewing....................................................................................................................... URLs of Online Versions 19 Getting....................................................................................................................... Launches of E-Mail 19 Getting....................................................................................................................... Delivery Status ....................................................................................................................... 21 Email Category ............................................................................................................................... 21 Querying E-Mail Category Lists .................................................................................................................................. 22 2 Language ....................................................................................................................... 22 Querying Language Lists .................................................................................................................................. 23 3 Segments ....................................................................................................................... 23 Querying Available Segments .................................................................................................................................. 24 4 Form 24 Getting....................................................................................................................... Customer Forms .................................................................................................................................. 25 5 Condition ....................................................................................................................... 25 Querying Condition Lists .................................................................................................................................. 26 6 Contacts ....................................................................................................................... 26 Creating a Contact ....................................................................................................................... 29 Updating a Contact ....................................................................................................................... 31 Creating Multiple Contacts at Once ....................................................................................................................... 32 Updating Multiple Contacts at Once ....................................................................................................................... 34 Checking Internal Contact IDs 35 Getting....................................................................................................................... Contact History 37 Getting....................................................................................................................... Contact Data ....................................................................................................................... 38 Contact Lists ............................................................................................................................... 38 Querying Contact Lists ............................................................................................................................... 39 Creating Contact Lists ............................................................................................................................... 41 Adding Contacts to Contact Lists ............................................................................................................................... 43 Removing Contacts from Contact Lists .................................................................................................................................. 45 7 Export


....................................................................................................................... 45 Querying Export Status ....................................................................................................................... 47 Exporting Responses ....................................................................................................................... 50 Exporting Registrations ....................................................................................................................... 53 Exporting Contact Lists ....................................................................................................................... 54 Exporting Changes .................................................................................................................................. 57 8 Files and Folders ....................................................................................................................... 57 Querying Files ....................................................................................................................... 59 Uploading Files to a Media Database

Folder ....................................................................................................................... 61 ............................................................................................................................... 61 Querying Folders .................................................................................................................................. 62 9 External Event 62 Getting....................................................................................................................... All External Events ....................................................................................................................... 63 Triggering External Events .................................................................................................................................. 64 10 Source 64 Getting....................................................................................................................... All Sources ....................................................................................................................... 65 Creating a Source ....................................................................................................................... 66 Deleting Sources .................................................................................................................................. 67 11 Field ....................................................................................................................... 67 Querying Field Lists ....................................................................................................................... 69 Querying Choice Lists

Appendix .................................................................................................................................. 70 1 Email and Form Types .................................................................................................................................. 70 2 Error Codes .................................................................................................................................. 71 3 Status Codes .................................................................................................................................. 72 4 Language Codes 73 5 List.................................................................................................................................. of Interfaces

3


emarsys eMarketing Suite

1

Introduction This section describes the various contexts in which you can use the eMarketing Suite API and gives an overview of the functionality. It describes what can be achieved via the API and gives some examples. However, this document does not describe how the API itself works.

2

API Interface Reference This section describes the various interfaces available via the Suite API. HTTP Header and Response Codes Every call to the API must be authenticated. This must be done by adding the following custom HTTP (X-WSSE) header: X-WSSE: UsernameToken Username="<username>", PasswordDigest="<calculatedDigest>", Nonce="<md5>", Created="<ISO 8601 Date>"

· Replace <field content> with actual data.

Username =<username>: as provided by emarsys Nonce =<md5>: the md5 of a random string . e.g. a timestamp Created =<ISO 8601 Date>: the current time encoded as an ISO 8601 date string Example: 2010 -12 -31 T15 :30:59+02:00 PasswordDigest =<calculatedDigest>: The algorithm to generate the digest is as follows: Concatenate: Nonce + Created + Secret Hash the result using the SHA1 algorithm Encode the result to base64

Incorrect requests will result in errors, i.e. HTTP responses. Success or failure of a request must be checked against the HTTP status codes; a detailed list can be found at: http://www.iana.org/assignments/http-status-codes Encoding · The parameters should be URL encoded: The '/' character has to be sent doubled ('//') in order to get the expected results. · If the key field is a multichoice field, the choices have to be separated by commas in the request URI. Example A correct request will result in a code 200. If the authentication failed, a 401 code is sent instead. You may find additional information in the message body. · Content type is 'application/json' · Return values: The API sends data encapsulated in the following JSON structure: replyCode:<value> replyText:<value>

4


API Interface Reference

data:<value>

If no error occurred, the reply code is 0 (zero). Any other value indicates a problem which must be taken care of.

2.1

E-Mails

2.1.1

Querying E-Mail Lists Returns a list of emails. URI /api/v2/email

Method GET

Required Parameters (none)

Optional parameters (integer) /status (integer) /contactlist

· If both parameters are used, they must be separated by an '&' character. Result Data Structure id:integer root_email:integer language:string created:datetime name:string fromemail:string fromname:string subject:string email_category:integer segment:integer contactlist:integer status:integer api_status:integer api_error:integer id:integer root_email:integer language:string ...

Where... · · · · · ·

id - The internal identifier of the email. name - The name of the email fromemail - Sender email address fromname - Sender name subject - Email subject email category - Category identifier for this email. Categories can be retrieved via /api/

v2/emailcategory. · segment - Segment identifer. Available segments can be retrieved via /api/v2/filter.

5


emarsys eMarketing Suite

路 contactlist - Contact list identifer. Contact lists can be retrieved via /api/v2/contactlist. 路 status - See section E-Mail Statuses in the appendix 路 api_status - See section API launch statuses in the appendix 路 api_error - See section API launch errors in the appendix URI Example /api/v2/email/status=3 /api/v2/email/contactlist=123 /api/v2/email/status=3&contactlist=123

JSON Payload Example N/A

Result Example { "replyCode":0, "replyText":" OK", "data": [ { "id":"12345" "root_email":"0" "language":"en" "created":"2011-08-12 18:12:23" "name":"Test1" "status":"3" "api_status":"2" "api_error":"0" "fromemail":"emarsys@emarsys.net" "fromname":"emarsys" "subject":"Test mail" "email_category":"11111" "segment":"22222" "contactlist":"0" "html_source":"Hello $Last Name$. How are you?" "text_source":"Hello $Last Name$ http://login.emarsys.net/u/nrd.php?p= $uid$_$llid$_$cid$_$sid$_2 } { "id":"67890" "root_email":"0" "language":"en" "created":"2011-08-12 18:20:23" "name":"Test2" "status":"3" "api_status":"2" "api_error":"0" "fromemail":"emarsys@emarsys.net" "fromname":"emarsys" "subject":"Test mail" "email_category":"11111" "segment":"22222" "contactlist":"0" "html_source":"Hello $Last Name$. How are you?" "text_source":"Hello $Last Name$ http://login.emarsys.net/u/ nrd.php?p= $uid$_$llid$_$cid$_$sid$_2 }

6


API Interface Reference

] }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Invalid segment: <segment>

The specified segment is not supported.

400

6003

Invalid email status in The specified status

400

Û 2.1.2

10001

segment: <status>

is not valid.

Invalid contact list id: <id>

The specified contact list ID is not valid.

Back to API Interface Overview

Creating E-Mails Creates an email in eMarketing Suite and assigns it the respective parameters. URI /api/v2/email

Method POST

Required Parameters (string) language (string) name (string) fromemail (string) fromname (string) subject (string) email_category (integer) segment (integer) contactlist (string) html_source (string) text_source

· For segment and contactlist , at least one property must be sent and must not be 0 (zero). If both are sent, only one must be different from 0 (zero). · Creation is only successful if all the parameters are correctly set. Optional parameters (integer) unsubscribe (integer) browse

· browse and unsubscribe are used like Boolean values. The values passed are "0" and "1", hence the data type 'integer'. · If browse is true (1), the email contains a link to the online version. · If unsubscribe is true (1), the email contains a link to unsubscribe. Result Data Structure id:integer

7


emarsys eMarketing Suite

Where... 路 id - Message ID URI Example N/A

JSON Payload Example { "name":"test api 010", "language":"en", "subject":"subject here", "fromname":"sender email", "fromemail":"sender@example.com", "email_category":"17", "html_source":"<html>Hello $First Name$,... </html>", "text_source":"email text", "browse":0, "unsubscribe":1, "segment":"1121", "contactlist":0 }

Result Example { " replyCode ":0 , " replyText ":"OK", " data ": { "id ":2140 } }

Errors HTTP Code

Reply Code

Message

Description

500

1

Database connection An error occurred error while saving.

400

10001

Invalid email name

The name parameter contains forbidden characters.

400

10001

An email with this name already exists

A unique name for the email must be provided.

400

10001

Invalid language

The provided language code is not supported. For a list of supported languages, see appendix.

400

10001

Invalid value: contactlist

The contact list ID must be numeric.

400

10001

Invalid value:

The segment ID must

8


API Interface Reference

segment 400

10001

be numeric.

Invalid email address fromemail must be a valid email address.

400

10001

Invalid value: fromname

400

10001

Subject must not be empty

400

10001

Invalid value: email_category

400

10001

You must select A contact list ID or a either a contact list or segment ID must be a segment. specified. This error message is returned if either both or none are specified.

400

10001

No content

Ă&#x203A; 2.1.3

The fromname parameter contains forbidden characters.

The email category must be numeric.

Both the html_source and the text_source are empty.

Back to API Interface Overview

E-Mail Attributes Returns the attributes of an email and the personalized text and HTML source. URI /api/v2/email/<id>

Method GET

Required Parameters (integer) /id

Optional parameters (none)

Result Data Structure id:integer language:string created:datetime name:string fromemail:string fromname:string subject:string email_category:integer segment:integer contactlist:integer html_source:string text_source:string status:integer api_status:integer

9


emarsys eMarketing Suite

api_error:integer

Where... · · · · · ·

id - the internal identifier of the email name - the name of the email fromemail - from email fromname - from name subject - subject email_category - the category identifier of the email. Categories may be retrieved via

the /api/v2/emailcategory interface. · segment - the identifer of the segment. Available segments can retrieved via the /api/v2/ filter interface. · contactlist - the identifer of the contact list. Contact lists may be retrieved via the /api/v2/ contactlist interface. · html source - HTML source of the email · text source - TEXT source of the email · status - for a list and description, see: email statuses · api_status - for a list and description, see API launch statuses · api_error - for a list and description, see: API launch errors URI Example N/A

JSON Payload Example N/A

Result Example { "replyCode":0, "replyText":" OK", "data": [ { "id":"12345" "language":"en" "created":"2011-08-12 18:12:23" "name":"Test" "status":"3" "api_status":"2" "api_error":"0" "fromemail":"emarsys@emarsys.net" "fromname":"emarsys" "subject":"Test mail" "email_category":"11111" "segment":"22222" "contactlist":"0" "html_source":"Hello $Last Name$. How are you?" "text_source":"Hello $Last Name$ http://login.emarsys.net/u/ nrd.php?p= $uid$_$llid$_$cid$_$sid$_2 } ] }

Errors HTTP Code

Reply Code

Message

Description

10


API Interface Reference

500

1

Database connection An error occurred error while saving.

400

10001

Invalid email name

The name parameter contains forbidden characters.

400

10001

An email with this name already exists

A unique name for the email must be provided.

400

10001

Invalid language

The provided language code is not supported. For a list of supported languages, see appendix.

400

10001

Invalid value: contactlist

The contact list ID must be numeric.

400

10001

Invalid value: segment

The segment ID must be numeric.

400

10001

Invalid email address fromemail must be a valid email address.

400

10001

Invalid value: fromname

400

10001

Subject must not be empty

400

10001

Invalid value: email_category

400

10001

You must select A contact list ID or a either a contact list or segment ID must be a segment. specified. This error message is returned if either both or none are specified.

400

10001

No content

Ă&#x203A; 2.1.4

The fromname parameter contains forbidden characters.

The email category must be numeric.

Both the html_source and the text_source are empty.

Back to API Interface Overview

Launching E-Mails Launches an email. This is an asynchronous call, which returns 'OK' if the email is able to launch. Query the /api/v2/email interface to obtain information on the launch progress. URI /api/v2/email/<id>/launch

Method

11


emarsys eMarketing Suite

POST

Required Parameters (integer) <id>

Optional parameters (datetime) schedule (string) timezone

· Both parameters may be empty in which case the email is launched immediately. · If a date and time are specified in the schedule parameter, the launch is scheduled for that time in the default time zone of the customer. · The format of the time zone specification must correspond to the PHP time zones (e.g. Europe/Vienna, Australia/Melbourne, etc.). · If the time zone is specified the schedule parameter is interpreted in the specified time zone. Result Data Structure data (no content) Where... · (no content)

URI Example Launch email with ID '12345': /api/v2/email/12345/launch

JSON Payload Example { "schedule":"2011-08-12 08:35", "timezone":"America/New_York" }

- or { "schedule":"2011-08-12 07:00", }

Result Example { "replyCode":0, "replyText":"OK", "data":"" }

Errors HTTP Code

Reply Code

Message

Description

400

6004

Invalid email ID

No email with the provided ID exists.

409

6003

Invalid email status

The email cannot be launched. Reason: It has already been launched either via

12


API Interface Reference

the API or the emarsys eMarketing Suite user interface. 409

6005

Invalid email type

Launching an onevent email is not supported in this version.

409

6005

Child email cannot be Launching an A/B launched version child or a recurring email child is not supported.

400

6009

Invalid date/time format

Wrong formatting of the date/datetime value in the schedule parameter.

400

6008

Invalid time zone

The value in the time zone parameter is invalid or not supported by the application.

Û 2.1.5

Back to API Interface Overview

Previewing E-Mails Returns the HTML or text version of the email either as content type 'application/json' or 'text/ html'. URI /api/v2/email/<id>/preview

Method POST

Required Parameters (integer) <id> (string) version

· 'version' can be 'html' or 'text' Optional parameters (none)

Result Data Structure TBD

Where... · one - Meaning · two - Meaning · three - Meaning URI Example

13


emarsys eMarketing Suite

TBD

JSON Payload Example { "version":"html", }

Result Example { "replyCode ":0, "replyText ":"OK", "data":" <html><head><\/head><body> ... <\/body><\/html>" }

Errors HTTP Code

Reply Code

Message

Description

400

6004

Invalid email ID

The requested email does not exist.

400

6003

Invalid email status

The requested email was deleted.

400

6003

Invalid version: <version>

The version parameter must be either "html" or "text".

Û 2.1.6

Back to API Interface Overview

Sending Test E-Mails Instructs the system to send a test email. URI /api/v2/email/<id>/sendtestmail

Method POST

Required Parameters (integer) <id> (string) recipientlist (integer) segment_id (integer) contactlist_id

· One and only one of the three required parameters recipientlist, segment_id and contactlist_id must be sent. · recipientlist can contain multiple email addresses separated by ';'. · The number of recipients in any of the parameters must be less than 50. Optional parameters (string) subject

· If the subject parameter is omitted, it will default to the email name; otherwise, the given

14


API Interface Reference

subject will be appended to the email name. Result Data Structure data (no content)

Where... 路 (no content)

URI Example Send test email with ID '12345': /api/v2/email/12345/sendtestmail

JSON Payload Example { "subject":"subject here", "recipientlist":"address@example.com" }

- or { "subject":"subject here", "recipientlist":"address1@example.com;address2@example.com" }

- or { "subject":"subject here", "segment_id":"123" }

- or { "contactlist_id":"987" }

Result Example { "replyCode":0, "replyText":"OK", "data":"" }

Errors HTTP Code

Reply Code

Message

Description

400

6004

Invalid email ID

No email with the provided ID exists.

400

6003

Invalid email status

The email was deleted.

400

6005

Invalid email type

On-event emails are not supported in this

15


emarsys eMarketing Suite

version. 400

One source has to be Only one source has specified

to be specified, either a recipientlist, a segment_id or a contactlist_id.

400

3004

Invalid contact list id: <id>

The provided contact list does not exist.

400

10001

Invalid segment id: <id>

The provided segment does not exist.

400

10001

Invalid recipient list: <recipientlist>

The provided recipient list contains an invalid email format.

Û 2.1.7

10001

Back to API Interface Overview

Viewing Response Summaries Returns the summary of the responses of a launched, paused, activated or deactivated email. URI /api/v2/email/<id>/responsesummary

Method GET

Required Parameters (integer) <id>

Optional parameters (none)

Result Data Structure sent:integer planned:integer soft_bounces:integer hard_bounces:integer block_bounces:integer opened:integer unsubscribe:integer total_clicks:integer unique_clicks:integer

Where... · sent - the number of emails which have actually left the emarsys eMarketing Suite mail servers · planned - the number of all contacts which are assigned to this launch · soft_bounces - the number of emails which were bounced (returned to sender) due to temporary problems · hard_bounces - the number of emails which were bounced (returned to sender) due to

16


API Interface Reference

permanent problems · block_bounces - the number of emails which were bounced (returned to sender) due to being blocked by spam filters · opened - the number of emails which were opened by recipients; the open rate refers to graphic (HTML) emails only · unsubscribe - the number of clicks on the unsubscribe link · total_clicks - the number of total clicks (multiple clicks per contact are counted) on links tracked by emarsys eMarketing Suite within an email · unique_clicks - the number of unique clicks (one click per contact is counted) on links tracked by emarsys eMarketing Suite within an email URI Example View response summary for email with ID '12345': /api/v2/email/12345/responsesummary

JSON Payload Example N/A

Result Example { "replyCode":0, "replyText":"OK", "data": { "sent":"1", "planned":"2", "soft_bounces":"3", "hard_bounces":"4", "block_bounces":"5", "opened":"6", "unsubscribe":"7", "total_clicks":"8", "unique_clicks":"9" } }

Errors HTTP Code

Reply Code

Message

Description

400

6004

Invalid email ID

No email with the provided ID exists.

400

6003

Invalid email status

The status of the email is not one of the following: launched, paused, activated, deactivated.

Û 2.1.8

Back to API Interface Overview

Viewing URLs of Online Versions Returns the URL to the online version of an email, provided it has been sent to the specified contact. URI

17


emarsys eMarketing Suite

/api/v2/email/<id>/url

Method POST

Required Parameters (integer) <id> (integer) key_id (mixed) key_field

Optional parameters (none)

Result Data Structure (string) url

Where... 路 url - URL of online version URI Example [URI Example]

JSON Payload Example { "key_id":"3", "key_value":"test@ema.il" }

Result Example { "replyCode":0 , "replyText":"OK", "data": { "url":"http://www.emarsys.com/u/gm.php? prm=uid369_119948266_123456789_369258147" } }

Errors 路 The error codes associated with the contact field ID and value can be found in the check contact internal ID section.

HTTP Code

Reply Code

Message

Description

400

6004

Invalid email ID

No email found with the specified email ID.

400

6003

Invalid email status

The email has been deleted, or its status is invalid. Allowed statuses: LAUNCHED, DEACTIVATED

400

6002

The email has not

18


API Interface Reference

been sent to the specified contact

Ă&#x203A; 2.1.9

Back to API Interface Overview

Getting Launches of E-Mail Lists all the launches of an email with ID, launch date and 'done' status. URI /api/v2/email/getlaunchesofemail

Method POST

Required Parameters (integer) emailId

Optional parameters N/A

Result Data Structure id:string, done:string, launch_date:string id:string, done:string, launch_date:string ...

URI Example [URI Example]

JSON Payload Example { "emailid":"1234" }

Result Example { "replyCode" : 0 , "replyText" : "OK", "data" : [{"id": "7555", "done": "y", "launch_date": "2012-05-05"}, {"id" : "7556", "done" : "n", "launch_date": "2012-05-05"}] }

Errors HTTP Code

Ă&#x203A; 2.1.10

Reply Code

Message

Description

Back to API Interface Overview

Getting Delivery Status Returns the delivery status of an email. URI /api/v2/email/getdeliverystatus

19


emarsys eMarketing Suite

Method POST

Required Parameters (integer) emailid

For emailId, a valid email ID must be provided. Optional parameters (integer) lastId (integer) launchId

· For launchId, a valid launch ID must be provided · This parameter is mandatory if the campaign has multiple launches · The launch must be finished before you can retrieve its delivery status Result Data Structure resultSet:array lastId:integer ... id:integer user_id:integer email:string status:string mail_type:string bounce_reason:string

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { "emailId":"1234", "launchId" : "5678", "lastId" : "999" }

Result Example { "replyCode":0 , "replyText":"OK", "data": { "resultSet": [{"id": "1", "user_id": "1", "bounce_reason" : "soft", "status" : "launched", "mail_type" : "html"}] "lastId" : "1" }

20


API Interface Reference

}

Errors HTTP Code

Û 2.1.11

Reply Code

Message

Description

Back to API Interface Overview

Email Category

2.1.11.1 Querying E-Mail Category Lists Returns a list of email categories which can be used in email creation. The list is sorted by category names. URI /api/v2/emailcategory

Method GET

Required Parameters (none)

Optional parameters (none)

Result Data Structure id:string, category:string id:string, category:string ...

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": { { "id":"1111" "name":"Cat1"

21


emarsys eMarketing Suite

}, { "id":"1112" "name":"Cat2" } } }

Errors HTTP Code

Û

Reply Code

Message

Description

Back to API Interface Overview

2.2

Language

2.2.1

Querying Language Lists Returns a list of languages which you can use in email creation. URI /api/v2/language

Method GET

Required Parameters (none)

Optional parameters /translate/<language_code>

· Language_code is one of the IDs returned in the list (e.g. 'en').

· For a list of supported languages, see appendix. Result Data Structure id:string, language:string id:string, language:string ...

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example]

22


API Interface Reference

}

Result Example { "replyCode":0, "replyText":"OK", "data": { { "id":"en", "language":"english" }, { "id":"de", "language":"german" }, { "id":"ru", "language":"russian" } } }

Errors HTTP Code

Reply Code

Message

400

1002

Invalid language code The requested language code is not supported. For a list of supported languages, see appendix.

Ă&#x203A;

Description

Back to API Interface Overview

2.3

Segments

2.3.1

Querying Available Segments Returns a list of segments which can be used as recipient source for the email. URI /api/v2/filter

Method GET

Required Parameters (none)

Optional parameters (none)

Result Data Structure id:integer, name:string id:integer, name:string ...

23


emarsys eMarketing Suite

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "id":"123", "name":"segment name 1" } { "id":"456", "name":"segment name 2" } ] }

Errors HTTP Code

Û

Reply Code

Message

Description

Back to API Interface Overview

2.4

Form

2.4.1

Getting Customer Forms Returns a list of the customer's forms. URI /api/v2/form

Method GET

Required Parameters (none)

Optional parameters (none)

Result Data Structure id:integer type:integer

Where... · type : Form type. See appendix. URI Example /api/v2/form

JSON Payload Example { [Payload Example]

24


API Interface Reference

}

Result Example { "replyCode":0, "replyText":"OK", "data": [ {"id":"123","type":"2"}, {"id":"124","type":"3"} ... ] }

Errors HTTP Code

Û

Reply Code

Message

Description

Back to API Interface Overview

2.5

Condition

2.5.1

Querying Condition Lists Returns a list of condition rules. URI /api/v2/condition

Method GET

Required Parameters (none)

Optional parameters (none)

Result Data Structure id:integer, name:string, condName:string id:integer, name:string, condName:string ...

Where... · condName : placeholder to use in the email's HTML or text source. URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example

25


emarsys eMarketing Suite

{ "replyCode":0, "replyText":"OK", "data": [ { "id":"123", "name":"Rule 1" "condName":"$COND_Rule 1$" }, { "id":"124" , "name":"Rule 2" "condName":"$COND_Rule 2$" } ] }

Errors HTTP Code

Û

Reply Code

Message

Description

Back to API Interface Overview

2.6

Contacts

2.6.1

Creating a Contact Creates one or more new contacts/recipients. URI /api/v2/contact

Method POST

Required Parameters key_id = [field_id]

· The ID of key_field can be specified using the key_id parameter. · If omitted, the default value for key_field ID is '3'. · If the same field ID is provided more than once, the last occurrence is accepted. Optional parameters [field_id] = [field_value] [field_id] = [field_value] ... source_id = [source_id]

· Multichoice values must be passed as an array, even if they contain only one ID. · Empty arrays are not allowed. · The following parameters are supported:

26


API Interface Reference

§ username § password § all fields returned by the API except: · 0 - interests · 27 - avg. length of visit · 28 - avg. pages per day · 29 - last mail received · 30 - response rate · 32 - user status · 33 - contact source · 34 - contact form · 36 - newsletter · 47 - email valid · 48 - first registration · voucher fields · Opt-in · The default opt-in value for new contacts is false. · To enable opt-in, send parameter 31=1. Result Data Structure [Result]

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example (default key_field) { "3":"test@example.com", }

JSON Payload Example (key_field selected) key_field selected, parameters are passed: { "key_id":"15", "15":"1234567", "7":"3", "source_id":"123" }

JSON Payload Example (multichoice field) Request containing a multichoice field '405067': { "key_id":"10675", "10675":"1234567", "405067": [ "6789",

27


emarsys eMarketing Suite

"6792" ] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "id":123 } }

Errors HTTP Code

Reply Code

Message

Description

400

2006

Empty field id for value: [value]

A value has been provided without defining its field.

400

2004

Invalid key field id: [id] The provided field ID does not exist.

400

2005

No value provided for The value of the key key field: [id] field has not been provided or is empty.

400

2005

Invalid key field value: The value of the key [error message] field was provided but the value is invalid. The [error message] contains information on the error.

400

2009

Contacts with the external id already exist: [id]

More than one contact with the provided key field value exists in the database; the specified key field is not unique.

400

2006

Contact with the external id already exists: [id]

A contact with the provided key field value exists in the database. It can be updated via POST call.

400

2007

Invalid field id: [id]

The provided field ID does not exist.

400

2007

Invalid field type: The request contains voucher. The value of a voucher field. vouchers cannot be changed.

400

2007

Invalid date format for The date format field id: [id] provided for the

28


API Interface Reference

specified field is invalid. 400

2007

Invalid choice id for field id: [id]

400

2007

Invalid data format for The value provided for field id: [id]. Array a multichoice field is expected not an array.

400

2007

Invalid data format for An array value was field id: [id]. Scalar provided for a nonexpected multichoice field.

400

2007

No choice provided for field id: [id].

500

2011

Database connection An error occurred error during the save process.

400

2013

Invalid source id: [id]

Û 2.6.2

The choice ID provided for the specified field is invalid.

An empty array was provided in the request for a multichoice field.

The customer has no source with the requested id.

Back to API Interface Overview

Updating a Contact Updates one or more contacts/recipients, identified by an external ID. URI /api/v2/contact

Method PUT

Required Parameters key_id = [field_id]

· The value provided for key_id field identifies the contact which will be updated. · The other fields contain the changes requested for the contact. · If more than one contact with the requested external ID is found, an error message is returned.

· See Create a Contact for further information. Optional parameters [field_id] = [field_value] [field_id] = [field_value] ... source_id = [source_id]

29


emarsys eMarketing Suite

· The value provided for key_id field identifies the contact which will be updated. · The other fields contain the changes requested for the contact. · If more than one contact with the requested external ID is found, an error message is returned.

· See Create a Contact for further information. Result Data Structure [Result]

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example { [Result Example] }

Errors HTTP Code

Reply Code

Message

Description

400

2010

More contacts found with the external id: [field_id] - [value]

More than one contact with the provided key field value exist in the database. A unique external key must be provided.

400

2008

No contact found with No contact with the the external id: provided key field [field_id] - [value] value exists in the database. The contact must be created; see Create a Contact.

· Also see Create a Contact for further information.

Û

Back to API Interface Overview

30


API Interface Reference

2.6.3

Creating Multiple Contacts at Once Creates multiple new contacts/recipients at once. URI /api/v2/contact

Method POST

Required Parameters key_id = [field_id] [field_id] = [field_value] [field_id] = [field_value] ... [field_id] = [field_value] [field_id] = [field_value] ...

· · · ·

The ID of key_field can be specified using the key_id parameter. If omitted, the default value for key_field ID is '3'. If the same field ID is provided more than once, the last occurrence is accepted. In contrast to single contact creation, key_id must be provided once, and the parameters of the different contacts must be in an array. The maximum size of the array (and therefore the maximum number of new contacts) is depends on the batch size you select. However, the upper batch size limit is 10,000. Optional parameters source_id = [source_id]

Result Data Structure [id1] [id2] ... [key_field_value1] = [error1] [key_field_value2] = [error2]

Where... · [idx] - The IDs of successfully created contacts are returned in an array. · [errorx] - If an error occurred during the creation of a contact, the error message is returned with the value of the key_id. URI Example [URI Example]

JSON Payload Example { "key_id":"3", "contacts": [ { "3":"test1@ema.il", "2":"name1", "source_id":"1234"

31


emarsys eMarketing Suite

}, { "3":"test2@ema.il", "2":"name2" }, { "3":"test3@ema.il", "2":"name3", "source_id":"5678" }, { "3":"test4@ema.il", "2":"name4" } ] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "ids": [ 123, 456 ], "errors": { "test1@ema.il": { "2009":"Contact with the external id already exists: 3" }, "test2@ema.il": { "2009":"Contact with the external id already exists: 3" } } } }

Errors HTTP Code

Reply Code

Message

Description

400

1000

The request exceeded the maximum batch size 10,000

Too many contacts were requested; contact creation is limited to 10,000.

Ă&#x203A; 2.6.4

Back to API Interface Overview

Updating Multiple Contacts at Once Updates multiple contacts/recipients at once. URI

32


API Interface Reference

/api/v2/contact

Method PUT

Required Parameters key_id = [field_id] [field_id] = [field_value] [field_id] = [field_value] ... [field_id] = [field_value] [field_id] = [field_value] ...

· key_id identifies the contact to be updated. · The other fields contain the changes requested for the contact. · If more than one contact with the requested external ID is found, an error message is returned.

· See Batch Create Contact for further information. Optional parameters source_id = [source_id]

· See Batch Create Contact for further information. Result Data Structure [id1] [id2] ... [key_field_value1] = [error1] [key_field_value2] = [error2]

Where... · [idx] - The IDs of successfully created contacts are returned in an array. · [errorx] - If an error occurred during the creation of a contact, the error message is returned with the value of the key_id. URI Example [URI Example]

JSON Payload Example { "key_id":"67", "contacts": [ { "67":"identifier 1", "2":"name1" }, { "67":"identifier 2",

33


emarsys eMarketing Suite

"679":["1","2"] } ] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "ids": [ 123, 456 ], "errors": { "test1@ema.il": { "2009":"Contact with the external id already exists: 3" }, "test2@ema.il": { "2009":"Contact with the external id already exists: 3" } } } }

Errors HTTP Code

Reply Code

Message

Description

400

1000

The request exceeded the maximum batch size 1,000

Too many contacts were requested; contact creation is limited to 1,000.

Ă&#x203A; 2.6.5

Back to API Interface Overview

Checking Internal Contact IDs Returns the internal ID of a contact specified by its external ID. URI /api/v2/contact/<key_field_id>=<key_field_value>

Method GET

Required Parameters (integer) key_field_id (field dependent) key_field_value

Optional parameters (none)

Result Data Structure

34


API Interface Reference

[id]

Where... · [id] - Internal ID of the contact URI Examples /api/v2/contact/3=email@example.com /api/v2/contact/5=1 /api/v2/contact/98012=1,2,3,4 /api/v2/contact/98205=http:////www.example.com JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "id":"123" } }

Errors HTTP Code

Reply Code

Message

Description

400

2004

Invalid key field id: [field_id]

The provided field ID does not exist.

400

2005

No value provided for The value of the key key field: [field_id] field has not been provided or is empty.

400

2010

More contacts found with the external id: [field_id]

400

2008

No contact found with No contact with the the external id: provided key field [field_id] value exists in the database.

Û 2.6.6

More than one contact with the provided key field value exist in the database.

Back to API Interface Overview

Getting Contact History Returns the list of emails sent to the specified contacts. URI /api/v2/contact/getcontacthistory

Method POST

35


emarsys eMarketing Suite

Required Parameters contacts:[integer]

· contacts is an integer array which contains the contact IDs to check Optional parameters startDate:date endDate:date

· startDate and endDate can be used to filter the launch date of emails Result Data Structure [ { emailId:integer contactId:integer launch_date:date delivery_status:string bounce_status:string } ]

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { "startDate":"2012-05-01", "endDate":"2012-06-01", "contacts":[1,2,3] }

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "emailId":"123456", "contactId":"15", "launch_date":"2012-05-05", "delivery_status":"launched", "bounce_status":"soft" } } }

Errors

36


API Interface Reference

HTTP Code

Reply Code

Message

Description

400

10001

Missing parameter:

contacts is a required

contacts

parameter. Comma-separated list of contact IDs.

400

10001

Contacts must be an integer array

400

10001

Invalid data format for Wrong date format. startDate/endDate. Date expected

400

10001

Max. number of contacts: 1000

Û 2.6.7

Number of contacts is limited to 1,000.

Back to API Interface Overview

Getting Contact Data Returns all data associated with a contact. · Search can be based on key (email, customerID) and User_ID). · Search by User_ID: use key "id" URI /api/v2/contact/getdata

Method POST

Required Parameters keyValues:array

· keyValues : an array containing contact IDs or values of the column used to select contacts Optional parameters keyId:integer fields:array

· keyId : contact element used as a key to select the contacts. If empty, internal id will be used. · fields : The fields in the result set can be set with the fields parameter. If empty, all fields will be returned. Result Data Structure Error condition: {"key":"fakeemail1@test.com", "errorCode":"2008", "errorMsg": "No contact found with the external id: 3"} {"key":"fakeemail2@test.com", "errorCode":"2008", "errorMsg": "No contact found with the external id: 3"} ...

Normal result: {"id":"23897","1":"testName1","3":"fakeemail1@test.com"} {"id":"23898","1":"testName2","3":"fakeemail2@test.com"}

Where...

37


emarsys eMarketing Suite

· one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { "keyId:3, "keyValues":"["Zoe.Thomas@g.ma.il.com","Zoe@@h.otma.il.com"]", "fields:[1,2,3] }

Result Example { "replyCode":0, "replyText":"OK", "data": { errors:[] result: [ {"id":"23897","1":"testName1","3":"fakeemail1@test.com"} ] } }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Missing parameter: keyValues

keyValues is a required parameter.

400

10001

KeyValues must be an array

Comma-separated list of key values.

400

10001

Fields must be an array

Comma-separated list of field IDs.

400

10001

KeyId must be an integer

If filled, must be an integer.

400

10001

Max. number of contacts: 1000

Number of contacts is limited to 1,000.

Û 2.6.8

Back to API Interface Overview

Contact Lists

2.6.8.1 Querying Contact Lists Returns a list of contact lists which can be used as recipient source for the email. URI /api/v2/contactlist

Method GET

38


API Interface Reference

Required Parameters (none)

Optional parameters (none)

Result Data Structure id:integer, name:string id:integer, name:string ...

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "id":"123", "name":"List 1" }, { "id":"124" , "name":"List 2" } ] }

Errors HTTP Code

Û

Reply Code

Message

Description

Back to API Interface Overview

2.6.8.2 Creating Contact Lists Creates a contact list which can be used as recipient source for the email. URI /api/v2/contactlist

39


emarsys eMarketing Suite

Method POST

Required Parameters key_id:integer name:string external_ids:[id1],[id2],...

路 external_id: The maximum value is 10,000 contacts Optional parameters description:string

Result Data Structure id:integer errors: [id1]:string [id2]:string

Where... 路 one - Meaning 路 two - Meaning 路 three - Meaning URI Example [URI Example]

JSON Payload Example (Simple Value) { "key_id":"3", "name":"test name", "description":"test description", "external_ids": [ "test1@example.com", "test2@example.com", "test3@example.com" ] }

JSON Payload Example (Multichoice Value) { "key_id":"123", "name":"test name", "description":"test description", "external_ids": [ [1,2,3], [2,3], [1,4] ] }

Result Example {

40


API Interface Reference

"replyCode":0, "replyText":"OK", "data": { "id":"123", "errors": [ "test2@example.com": { "2008":"No contact found with the external id: 3 test2@example.com" } ] } }

Errors HTTP Code

Reply Code

Message

Description

400

3004

List name is not set.

No name was provided for the contact list.

400

3004

List name contains invalid character(s).

The provided name contains characters which are not allowed.

400

3005

Contact list with the requested name already exists.

A contact list with the requested name already exists.

400

3004

Description contains invalid character(s).

The provided description contains characters which are not allowed.

400

3003

Invalid datatype for The provided data for the list of external ids. the list of external IDs Array expected. is not an array.

400

3002

The list of external ids Too many contacts exceeds the were requested; maximum size. Number of contacts is limited to 10,000.

Ă&#x203A;

Back to API Interface Overview

2.6.8.3 Adding Contacts to Contact Lists Adds contacts to the contact list which can be used as recipient source for the email. URI /api/v2/contactlist/<list_id>/add

Method POST

41


emarsys eMarketing Suite

Required Parameters (integer) <list_id> (integer) key_id (integer) external_ids:[id1],[id2],...

路 external_id: The maximum value is 10,000 contacts Optional parameters (none)

Result Data Structure inserted_contacts:integer errors: [id1]:string [id2]:string

Where... 路 inserted_contacts - Number of contacts successfully added to the list 路 errors - Array of contacts not added to the list. The array contains ID and reason for the error. JSON Payload Example (Simple Value) { "key_id":"3", "external_ids": [ "test1@example.com", "test2@example.com", "test3@example.com" ] }

JSON Payload Example (Multichoice Value) { "key_id":"123", "external_ids": [ [1,2,3], [2,3], [1,4] ] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "inserted_contacts":"2", "errors": { "test2@example.com": {

42


API Interface Reference

"2008":"No contact found with the external id: 3 test2@example.com" } } } }

Errors HTTP Code

Reply Code

Message

Description

400

3004

List name is not set.

No name was provided for the contact list.

400

3004

List name contains invalid character(s).

The provided name contains characters which are not allowed.

400

3005

Contact list with the requested name already exists.

A contact list with the requested name already exists.

400

3004

Description contains invalid character(s).

The provided description contains characters which are not allowed.

400

3003

Invalid datatype for The provided data for the list of external ids. the list of external IDs Array expected. is not an array.

400

3002

The list of external ids Too many contacts exceeds the were requested; maximum size. Number of contacts is limited to 10,000.

400

3004

Invalid contact list id: [id]

Ă&#x203A;

The provided contact list ID has an invalid format or does not exist.

Back to API Interface Overview

2.6.8.4 Removing Contacts from Contact Lists This deletes contacts from the contact list which can be used as recipient source for the email. URI /api/v2/contactlist/<list_id>/delete

Method POST

Required Parameters (integer) <list_id> (mixed) key_id

43


emarsys eMarketing Suite

(integer) external_ids:[id1],[id2],...

Where... 路 key_id - field id , "id" or "uid" can be used. 路 list_id: The maximum value is 10,000 contacts to be deleted with each request. Optional parameters (none)

Result Data Structure deleted_contacts:integer errors: [id1]:string [id2]:string

Where... 路 deleted_contacts - Number of contacts successfully deleted from the list 路 errors - Array of contacts not removed from the list. The array contains ID and reason for the error. JSON Payload Example (Simple Value) { "key_id":"3", "external_ids": [ "test1@example.com", "test2@example.com", "test3@example.com" ] }

JSON Payload Example (Multichoice Value) { "key_id":"123", "external_ids": [ [1,2,3], [2,3], [1,4] ] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "deleted_contacts":"2", "errors": { "test2@example.com": {

44


API Interface Reference

"2008":"No contact found with the external id: 3 test2@example.com" } } } }

Errors HTTP Code

Reply Code

Message

Description

400

3004

List name is not set.

No name was provided for the contact list.

400

3004

List name contains invalid character(s).

The provided name contains characters which are not allowed.

400

3005

Contact list with the requested name already exists.

A contact list with the requested name already exists.

400

3004

Description contains invalid character(s).

The provided description contains characters which are not allowed.

400

3003

Invalid datatype for The provided data for the list of external ids. the list of external IDs Array expected. is not an array.

400

3002

The list of external ids Too many contacts exceeds the were requested; maximum size. Number of contacts is limited to 10,000.

400

3004

Invalid contact list id: [id]

Ă&#x203A;

The provided contact list ID has an invalid format or does not exist.

Back to API Interface Overview

2.7

Export

2.7.1

Querying Export Status Fetches the status data of an export. Uses the ID returned by /api/v2/email/getresponses or / api/v2/contact/getregistrations . URI /api/v2/export

Method GET

Required Parameters (integer) <id>

45


emarsys eMarketing Suite

Optional parameters (none)

Result Data Structure id:integer created:datetime status:string type:string file_name:string ftp_host:string (for ftp distributed exports only) ftp_dir:string (for ftp distributed exports only)

Where... · o o o o o · o o · · · ·

status can be:

scheduled: the export process has not been started yet in progress: the export is being processed ready: the CSV file is ready to be distributed done: the export finished without errors, the CSV file was created and distributed successfully error: an error occurred during the export process type can be: responses registrations file_name - name of output CSV file if status is 'done'; otherwise it NULL ftp_host - export settings to locate the file if the distribution method is ftp ftp_dir - export settings to locate the file if the distribution method is ftp three - Meaning

· In case of an FTP delivery, and if the FTP host is unavailable or the authentication failed, the export status remains 'ready' and the process will try to connect to the FTP after one hour. · If the export process cannot connect and stays in ready status for more than one hour, contact emarsys support. URI Example /api/v2/export/85569

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": { "id":"123", "created":"2012-05-23 11:08:56" "status":"done" "type":"Responses" "file_name":"clicks_3931993_1_en-df0ef2.csv" "ftp_host":"88.99.123.23" "ftp_dir":"folder/subfolder"

46


API Interface Reference

} }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Invalid export ID

No ID provided in the URI, or an export with the ID does not exist.

400

4002

Invalid export type

In this version, only the export of responses and new registrations is supported.

Û 2.7.2

Back to API Interface Overview

Exporting Responses Exports the selected fields of all contacts which responded to emails in the specified time range. The request starts a background export process and returns its ID which can be used to obtain the status of the process. The background process saves the results as a CSV file, either locally or via FTP on another computer. URI /api/v2/email/getresponses

Method POST

Required Parameters (string) distribution_method (string array) sources (date array) time_range (integer array) contact_fields (integer array) analysis_fields

· o · · · o o o o o

distrib ution_method : 'ftp' or 'local' If distrib ution_method is 'ftp', then ftp_settings is a required parameter. time_range : Array with two elements (start date, end date) origin : 'form' or 'api' contact_fields : an array must be provided; the array must not be empty. It may contain any contact field ID except: 27 - avg. length of visit 28 - avg. pages per day 29 - last mail received 32 - user status 33 - contact source · sources : an array must be provided; containing one or more of:

47


emarsys eMarketing Suite

o trackable_links o registration_forms o o o o o

tell_a_friend contact_us change_profile unsubscribe mail_open

· analysis_fields : an array must be provided; the array must not be empty. It can contain the following IDs: o o o o o o o o o o ·

1 - Campaign title 2 - Section header 3 - Section group 4 - Link title 5 - URL 8 - Time 12 - Campaign ID 13 - Version Name 14 - Campaign category 15 - Link category The number of the fields provided for contact_fields and analysis_fields must be at least 1 and at most 20 in total.

Optional parameters (integer) contactlist (string) delimiter (integer) add_field_names_header (string) language (object) ftp_settings

· contactlist : a valid contact list ID must be provided. · · · · o o o o o ·

delimiter : ',' (comma) or ';' (semicolon). Default value is ',' (comma) add_field_names_header : '0' or '1'. Default value is '1' language : valid language code, Default value: the customer's language. ftp_settings : an object with the following fields must be provided: (string) host (integer) port (string) username (string) password (string) folder - optional If distrib ution_method is 'local', then ftp_settings is ignored.

Result Data Structure id:integer

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

48


API Interface Reference

JSON Payload Example { "distribution_method":"ftp", "contactlist":"123", "sources":["trackables_links","tell_a_friend"], "time_range":["2012-02-09","2012-04-02"], "contact_fields":["1","3","106533"], "analysis_fields":["1","5","8","15"], "delimiter":";", "add_field_names_header":1, "language":"en", "ftp_settings": { "host":"www.example.com", "port":"1234", "username":"user", "password":"pass", "folder":"path/of/a/folder" } }

Result Example { "replyCode":0 , "replyText":"OK", "data": { "id":2140 } }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Missing parameter: [param]

The required [param] parameter is missing.

400

10001

Invalid data format for The value for [parameter]. Array [parameter] is no expected array.

400

10001

Invalid data format for The length of the time_range. Array array for time_range size must be 2 is not 2.

400

10001

Invalid distribution method: [value]

The provided [value] is not "ftp" or "local".

400

10001

Invalid source: [val1], [val2], ...

[val1], [val2], ... values are no valid sources.

400

10001

Invalid value for [param]: [val]

The [val] value for [param] parameter is not valid.

400

10001

Invalid contact field id: [id1], [id2], ... values [id1], [id2] are no valid contact

49


emarsys eMarketing Suite

field IDs. 400

Invalid analysis field

[id1], [id2], ... values

id: [id1], [id2]

are not valid analysis field IDs.

400

10001

Invalid number of fields

The total number of IDs for contact_fields and analysis_fields is 0 or > 10.

400

10001

Valid start_date and end_date is required

One of the given dates in time_range is invalid.

400

10001

Invalid value for end_date: end_date is earlier than the start_date

The second date in time_range must be later than the first one.

400

10001

An export with the same setting is currently running. It is not possible to run the same export more than once simultaneously.

Û 2.7.3

10001

Back to API Interface Overview

Exporting Registrations Exports the selected fields of all contacts which registered in the specified time range. The request starts a background export process and returns its ID which can be used to obtain the status of the process. The background process saves the results as a CSV file, either locally or via FTP on another computer. URI /api/v2/contact/getregistrations

Method POST

Required Parameters (string) (date array) (integer array)

· o · · ·

distribution_method time_range contact_fields

distrib ution_method : 'ftp' or 'local' If distrib ution_method is 'ftp', then ftp_settings is a required parameter. time_range : Array with two elements (start date, end date) origin : 'form' or 'api' contact_fields : an array must be provided; the array must not be empty.

50


API Interface Reference

It may contain any contact field ID except: o 27 - avg. length of visit o o o o

28 - avg. pages per day 29 - last mail received 32 - user status 33 - contact source

Optional parameters (integer) (integer) (string) (integer) (string) (object)

with_timestamp contactlist delimiter add_field_names_header language ftp_settings

· with_timestamp : '0' or '1'. Default value is '1' · contactlist : valid contact list id · · · · o o o o o ·

delimiter : ',' (comma) or ';' (semicolon). Default value is ',' (comma) add_field_names_header : '0' or '1'. Default value is '1' language : valid language code, Default value: the customer's language. ftp_settings : an object with the following fields must be provided: (string) host (integer) port (string) username (string) password (string) folder - optional If distrib ution_method is 'local', then ftp_settings is ignored.

Result Data Structure id:integer

URI Example [URI Example]

JSON Payload Example { "distribution_method":"ftp", "contactlist":"123", "time_range":["2012-02-09","2012-04-02"], "contact_fields":["1","3","106533"], "delimiter":";", "add_field_names_header":1, "language":"en", "with_timestamp":1, "ftp_settings": { "host":"www.example.com", "port":"1234", "username":"user", "password":"pass", "folder":"path/of/a/folder" } }

51


emarsys eMarketing Suite

Result Example { "replyCode":0 , "replyText":"OK", "data": { "id":2140 } }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Missing parameter: [param]

The required [param] parameter is missing.

400

10001

Invalid data format for The [parameter] value [parameter]. Array is not an array. expected

400

10001

Invalid data format for The length of the time_range. Array array provided for size must be 2 time_range is not 2.

400

10001

Invalid distribution method: [value]

The provided [value] is not "ftp" or "local".

400

10001

Invalid source: [val1], [val2], ...

[val1], [val2], ... values are no valid sources.

400

10001

Invalid value for [param]: [val]

The provided [val] value for [param] parameter is not valid.

400

10001

Invalid contact field id: [id1], [id2], ... values [id1], [id2] are no valid contact field IDs.

400

10001

Invalid number of fields

The number of IDs provided for contact_fields is 0.

400

10001

Valid start_date and end_date is required

One of the given dates in time_range is invalid.

400

10001

Invalid value for end_date: end_date is earlier than the start_date

The second date in time_range must be later than the first one.

400

4001

An export with the same setting is currently running. It is not possible to run the same export more than once

52


API Interface Reference

simultaneously.

Û 2.7.4

Back to API Interface Overview

Exporting Contact Lists Exports selected fields of contacts. Contacts are passed as a contact list with the given ID. URI /api/v2/email/getcontacts

Method POST

Required Parameters (string) (integer) (integer array)

· o · ·

distribution_method contactlist contact_fields

distrib ution_method : 'ftp' or 'local' If distrib ution_method is 'ftp', then ftp_settings is a required parameter. time_range : Array with two elements (start date, end date) origin : 'form' or 'api'

· contact_fields : an array must be provided; the array must not be empty. It may contain any contact field ID except: o 27 - avg. length of visit o 28 - avg. pages per day o 29 - last mail received o 32 - user status o 33 - contact source Optional parameters (string) (integer) (string) (object)

· · · · o o o o o ·

delimiter add_field_names_header language ftp_settings

delimiter : ',' (comma) or ';' (semicolon). Default value is ',' (comma) add_field_names_header : '0' or '1'. Default value is '1' language : valid language code, Default value: the customer's language. ftp_settings : an object with the following fields must be provided: (string) host (integer) port (string) username (string) password (string) folder - optional If distrib ution_method is 'local', then ftp_settings is ignored.

53


emarsys eMarketing Suite

Result Data Structure id:integer

URI Example [URI Example]

JSON Payload Example { "distribution_method":"ftp", "contactlist":"123", "contact_fields":["1","3","106533"], "delimiter":";", "add_field_names_header":1, "language":"en", "ftp_settings": { "host":"www.example.com", "port":"1234", "username":"user", "password":"pass", "folder":"path/of/a/folder" } }

Result Example { "replyCode":0 , "replyText":"OK", "data": { "id":2140 } }

Errors HTTP Code

Ă&#x203A; 2.7.5

Reply Code

Message

Description

Back to API Interface Overview

Exporting Changes Exports the selected fields of all contacts with properties changed in the time range specified. The contacts must belong to the given form or API source. The request starts a background export process and returns its ID which can be used to obtain the status of the process. The background process saves the results as a CSV file, either locally or via FTP on another computer. URI /api/v2/contact/getchanges

54


API Interface Reference

Method POST

Required Parameters (string) distribution_method (date array) time_range (string) origin (integer array) origin_id (integer array) contact_fields

· o · · · o o o o o

distrib ution_method : 'ftp' or 'local' If distrib ution_method is 'ftp', then ftp_settings is a required parameter. time_range : Array with two elements (start date, end date) origin : 'form' or 'api' contact_fields : an array must be provided; the array must not be empty. It may contain any contact field ID except: 27 - avg. length of visit 28 - avg. pages per day 29 - last mail received 32 - user status 33 - contact source

Optional parameters (string) delimiter (integer) add_field_names_header (string) language (object) ftp_settings

· · · · o o o o o ·

delimiter : ',' (comma) or ';' (semicolon). Default value is ',' (comma) add_field_names_header : '0' or '1'. Default value is '1' language : valid language code, Default value: the customer's language. ftp_settings : an object with the following fields must be provided: (string) host (integer) port (string) username (string) password (string) folder - optional If distrib ution_method is 'local', then ftp_settings is ignored.

Result Data Structure id:integer

Where... · one - Meaning · two - Meaning · three - Meaning URI Example

55


emarsys eMarketing Suite

[URI Example]

JSON Payload Example { "distribution_method":"ftp", "origin":"form", "origin_id":"123", "time_range":["2012-02-09","2012-04-02"], "contact_fields":["1","3","106533"], "delimiter":";", "add_field_names_header":1, "language":"en", "ftp_settings": { "host":"www.example.com", "port":"1234", "username":"user", "password":"pass", "folder":"path/of/a/folder" } }

Result Example { "replyCode":0 , "replyText":"OK", "data": { "id":2140 } }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Missing parameter: [param]

The required [param] parameter is missing.

400

10001

Invalid data format for The [parameter] value [parameter]. Array is not an array. expected

400

10001

Invalid data format for The length of the time_range. Array array provided for size must be 2 time_range is not 2.

400

10001

Invalid origin: [parameter]

400

10001

Invalid data format for Invalid origin ID (form origin_id. Integer or API source) was expected sent.

400

10001

Invalid distribution method: [value]

The provided [value] is not "ftp" or "local".

400

10001

Invalid value for [param]: [val]

The provided [val] value for the [param]

An invalid origin type was sent.

56


API Interface Reference

parameter is not valid. 400

10001

Invalid contact field id: [id1], [id2], ... values [id1], [id2] are no valid contact field IDs.

400

10001

Invalid number of fields

The number of IDs provided for contact_fields is 0.

400

10001

Valid start_date and end_date is required

One of the given dates in time_range is invalid.

400

10001

Invalid value for end_date: end_date is earlier than the start_date

The second date in time_range must be later than the first one.

400

4001

An export with the same setting is currently running. It is not possible to run the same export more than once simultaneously.

Û

Back to API Interface Overview

2.8

Files and Folders

2.8.1

Querying Files Returns a customer's files. URI /api/v2/file

Method GET

Required Parameters (none)

Optional parameters folder=<folder_id>

· folder_id is the ID of an already existing folder in the media database. · If folder_ID is provided, the files in the folder are returned. Result Data Structure id:integer folder:integer filename:string size:integer original_name:string url:string

57


emarsys eMarketing Suite

Where... 路 one - Meaning 路 two - Meaning 路 three - Meaning URI Example /api/v2/file /api/v2/file/folder=12

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "id":"123", "folder":"1" "filename":"md_2.jpg" "size":"1234" "original_name":"picture.jpg" "url":"http://example.com/custloads/12345678/md_2.jpg" }, { "id":"456", "folder":"1" "filename":"md_3.jpg" "size":"1234" "original_name":"picture2.jpg" "url":"http://example.com/custloads/12345678/md_3.jpg" } ] }

Errors HTTP Code

Reply Code

Message

Description

400

10001

Folder does not exist: The folder parameter [folder] in the request is invalid or a folder with the provided ID does not exist in the media database.

400

10001

Invalid filter: [filter]

400

10001

Invalid value for [filter] The value is invalid filter: [value] for the given filter. The "folder" filter accepts

The filter is invalid. Currently only "folder" is supported.

58


API Interface Reference

only integers.

Û 2.8.2

Back to API Interface Overview

Uploading Files to a Media Database Uploads a file to a media database. URI /api/v2/file

Method POST

Required Parameters filename:string file:string

· The upload limit is 128 kB for images and 4 MB for other file types · filename is the full name of the file plus extension (testimage.jpg) · file is the base64 encoded content of the file Optional parameters folder:integer

· If folder is not specified the file is uploaded to the root directory. · folder is the ID of an already existing folder in the media database. · The list of folders can be retrieved using the /api/v2/folder interface. Result Data Structure d:integer folder:integer filename:string size:integer original_name:string

Where... · filename - Resulting file name in the media database after upload · original_name - File name provided in the request URI Example [URI Example]

JSON Payload Example { "folder":"840559", "filename":"logo.png", "file":"Dm++/ vUMBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEB AQEBAQEBAQEBAQEBAcO/w4Dvv70RCO+/veKCrO+/veKCrAMBIgIRAQ==...", }

Result Example {

59


emarsys eMarketing Suite

"replyCode":0, "replyText":"OK", "data": [ { "id":"123", "folder":"1" "filename":"md_1234.png" "size":"96274211" "original_name":"logo.png" } ] }

Errors HTTP Code

Reply Code

Message

Description

400

5025

Cannot create directory

An error occurred during the creation of the root directory.

400

5026

Invalid file

No file or file name was provided or the file/file name is not valid.

400

5027

File size exceeds the limit

The file size limit is 128 Kb for images and 4 Mb for other file types.

400

5029

File not supported

An error occurred during thumbnail creation.

400

5030

Resize failed

An error occurred during thumbnail creation.

400

5033

Thumbnail creation failed

An error occurred during thumbnail creation.

400

5034

File type is forbidden

The file type is not allowed in the media database (e.g. *.exe).

400

10001

Folder does not exist: The folder parameter [folder] in the request is invalid, or no folder with the ID exists in the media database.

Ă&#x203A;

Back to API Interface Overview

60


API Interface Reference

2.8.3

Folder

2.8.3.1 Querying Folders Returns a customer's folders. URI /api/v2/folder

Method GET

Required Parameters (none)

Optional parameters integer <folder_id>

路 folder_id is the ID of an already existing folder in the media database. If it is provided, its subfolders are returned. Result Data Structure id:integer parent:integer name:string

Where... 路 parent - Parent folder. If a parent folder is specified, only its subfolders are returned. URI Example /api/v2/folder /api/v2/folder/folder=12

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "id":"123", "parent":"1" "name":"folder1" }, { "id":"456", "parent":"1" "name":"folder2" } ] }

Errors

61


emarsys eMarketing Suite

HTTP Code

Reply Code

Message

400

10001

Folder does not exist: The folder parameter

400

10001

Description

[folder]

in the request is invalid or a folder with this ID does not exist in the media database.

Invalid filter: [filter]

The filter is invalid. Currently only "folder" is supported.

400

Û

10001

Invalid value for [filter] The value is invalid filter: [value] for the given filter. The "folder" filter accepts integers only.

Back to API Interface Overview

2.9

External Event

2.9.1

Getting All External Events Returns a list of external events which can be used in programs. URI /api/v2/event

Method GET

Required Parameters (none)

Optional parameters (none)

Result Data Structure id:integer, name:string id:integer, name:string ...

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example {

62


API Interface Reference

"replyCode":0, "replyText":"OK", "data": [ { "id":"123", "name":"event name 1" } { "id":"456", "name":"event name 2" } ] }

Errors HTTP Code

Û 2.9.2

Reply Code

Message

Description

Back to API Interface Overview

Triggering External Events Triggers the given event for the specified contact. URI /api/v2/event/<id>/trigger

Method POST

Required Parameters (integer) <id> (integer) key_id (string) external_id

· key_id is the identifier for the field to retrieve · external_id is the ID for the given field specified with field_id Optional parameters (none)

Result Data Structure [Result]

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

63


emarsys eMarketing Suite

JSON Payload Example { "key_id":"3", "external_id": "test@example.com" }

Result Example { [Result Example] }

Errors HTTP Code

Reply Code

Message

Description

400

2004

Invalid key id field: [field_id]

The field ID does not exist.

400

2005

No value provided for The value of the key key field: [field_id] field was either not provided or is empty.

400

2008

No contact found with There is no match for the external id: the specified key ID/ [key_id] - [external_id] external ID pair.

400

2010

More contacts found There is more than with the external id: one contact selected. [key_id] - [external_id]

400

5001

Invalid event id for customer.

The customer does not have an external event with the specified ID.

400

2012

Invalid contact id for customer.

The customer does not have a contact with the specified external ID.

Ă&#x203A;

Back to API Interface Overview

2.10

Source

2.10.1

Getting All Sources Returns a list of sources which can be used for creating contacts. URI /api/v2/source

Method GET

Required Parameters (none)

Optional parameters (none)

64


API Interface Reference

Result Data Structure id:integer, name:string id:integer, name:string ...

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "id":"123", "name":"source name 1" } { "id":"456", "name":"source name 2" } ] }

Errors HTTP Code

Û 2.10.2

Reply Code

Message

Description

Back to API Interface Overview

Creating a Source Creates a new source for the customer with the specified name. URI /api/v2/source/create

Method POST

Required Parameters (string) name

65


emarsys eMarketing Suite

· name : Name of the source to be created. Optional parameters (none)

Result Data Structure [Result]

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { "name": "my_new_source" }

Result Example { [Result Example] }

Errors HTTP Code

Reply Code

Message

400

7001

An external event with The customer already the requested name has an existing event already exists. with the requested name.

500

7003

Database connection An error occured error. while saving.

Û 2.10.3

Description

Back to API Interface Overview

Deleting Sources Deletes an existing source. URI /api/v2/source/<id>

Method DELETE

Required Parameters (none)

Optional parameters (none)

Result Data Structure

66


API Interface Reference

[Result]

Where... · one - Meaning · two - Meaning · three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example { [Result Example] }

Errors HTTP Code

Reply Code

Message

Description

400

7002

The requested external event does not exist.

The customer has no event with the requested ID.

500

7003

Database connection An error occurred error. while saving.

Û

Back to API Interface Overview

2.11

Field

2.11.1

Querying Field Lists Returns a list of fields (including custom fields and vouchers) which can be used to personalize content. URI /api/v2/field

Method GET

Required Parameters (none)

Optional parameters /translate/<id>

· <id> can be: 'en', 'de', 'ru', ...

· For a full list of supported languages, see appendix. Result Data Structure

67


emarsys eMarketing Suite

id:integer, name:string, application_type:string id:integer, name:string, application_type:string id:integer, name:string, application_type:string ...

Where... 路 one - Meaning 路 two - Meaning 路 three - Meaning URI Example [URI Example]

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0, "replyText":"OK", "data": [ { "id":"0", "name":"Interests" "application_type":"interests" }, { "id":"1" , "name":"First Name" "application_type":"shorttext" }, { "id":"9" , "name":"Title" "application_type":"singlechoice" }, ... { "id":"123", "name":"CustomField18" "application_type":"numeric" }, ... { "id":"456", "name":"Voucher42" "application_type":"voucher" } ] }

Errors HTTP Code

Reply Code

Message

Description

68


API Interface Reference

Û 2.11.2

Back to API Interface Overview

Querying Choice Lists Returns the choice options of a field. URI /api/v2/field/<id>/choice

Method GET

Required Parameters (integer) <id>

Optional parameters /translate/<id>

· <id> can be: 'en', 'de', 'ru', ...

· For a full list of supported languages, see appendix. Result Data Structure id:integer choice:string

Where... · id - Internal identifier of the choice · choice - Name of the choice URI Example List the choices of the field with ID '5' in French: /api/v2/field/5/choice/translate/fr

JSON Payload Example { [Payload Example] }

Result Example { "replyCode":0 , "replyText":"OK", "data": [ { "id":"1" "choice":"HTML" }, {

69


emarsys eMarketing Suite

"id":"2" "choice":"Text only" } ] }

Errors HTTP Code

Û

Reply Code

Message

Description

Back to API Interface Overview

3

Appendix

3.1

Email and Form Types Form Types 1

General Registration

2

Newsletter Registration

3

Contact Us

4

Change-profile form

Field Types TBD

Bounce Types TBD

3.2

Error Codes General Error Codes · For information on the error codes as used by the API, please refer to the documentation of the individual interfaces. If a resource is called with an unsupported method, the following error is returned: HTTP response code

501 Not implemented

Error message

This feature has not been implemented yet.

Problem

Interface was called with an unsupported method.

API Launch Error Codes Launching an email might produce one of the following launch errors:

70


Appendix

3.3

api_error

Description

1

Internal error

2

No permission

3

Missing from email

4

Missing subject

5

Empty launch list

6

Final too early

7

Not checked

8

Scheduling failed

9

Type does not support versioning

16

Unschedule failed

17

Another test impossibe

18

Final depends on tests

19

Launch started

20

Name exists

21

Launch is over

22

Missing from name

23

Lock time out

24

Lock failure

25

Processed by job

32

Large size

33

Missing section profiles

34

HTML code not complete

35

Empty seedlist

Status Codes E-Mail Status Codes Retrieve an email's status like this: /status=<id>

The ID is one of the following: Status

Description

1

In design

2

Tested

3

Launched

4

Ready to launch

-3

Deactivated

API Launch Statuses Emails have one of the following launch statuses:

71


emarsys eMarketing Suite

api_status

Description

0

Not launched

1

Launch called via API, launching in progress

2

Email launched or scheduled for future launch

10

3.4

Error (details in api_error)

Language Codes Language Code

Description

AR

Arabic

BG

Bulgarian

BP

Brazilian Portuguese

CN

Chinese Simplified

CZ

Czech

DE

German

DK

Danish

EL

Greek

EN

English

ES

Spanish

ET

Estonian

FI

Finnish

FR

French

HE

Hebrew

HI

Hindi

HR

Croatian

HU

Hungarian

IT

Italian

JP

Japanese

KO

Korean

LT

Lithuanian

LV

Latvian

MK

Macedonian

MO

Moldavian

MX

Mexican

NL

Dutch

NO

Norwegian

PL

Polish

PR

Portuguese

72


Appendix

3.5

RO

Romanian

RU

Russian

SC

Serbian

SK

Slovakian

SL

Slovenian

SR

Serbocroatian

SV

Swedish

TH

Thai

TR

Turkish

UK

Ukrainian

VI

Vietnamese

List of Interfaces Below is a reference of the interfaces implemented in the emarsys eMarketing Suite API. Interface

Method

Description

/api/v2/condition

GET

Returns a list of condition rules.

/api/v2/contact

POST

Creates one or more new contacts/recipients.

/api/v2/contact

PUT

Updates one or more contacts/recipients, identified by an external ID.

/api/v2/contact/ GET <key_field_id>=<key_f

Returns the internal ID of a contact specified by its external ID.

ield_value> /api/v2/contact/ getchanges

POST

Exports the selected fields of all contacts with properties changed in the time range specified.

/api/v2/contact/ getcontacthistory

POST

Returns the list of emails sent to the specified contacts.

/api/v2/contact/getdata GET

Returns all data associated with a contact.

/api/v2/contact/ getregistrations

POST

Exports the selected fields of all contacts which registered in the specified time range.

/api/v2/contactlist

GET

Returns a list of contact lists which can be used as recipient source for the email.

/api/v2/contactlist

POST

Creates a contact list which can be used as recipient source for the email.

/api/v2/contactlist/ <list_id>/add

POST

Adds contacts to the contact list which can be used as recipient source for the email.

/api/v2/contactlist/ <list_id>/delete

POST

This deletes contacts from the contact list which can be used as recipient source for the email.

/api/v2/email

GET

Returns a list of emails.

/api/v2/email

POST

Creates an email in eMarketing Suite and assigns it the respective parameters.

/api/v2/email/<id>

GET

Returns the attributes of an email and the personalized text and HTML source.

73


emarsys eMarketing Suite

/api/v2/email/<id>/ launch

POST

Launches an email. This is an asynchronous call, which returns 'OK' if the email is able to launch.

/api/v2/email/<id>/ preview

POST

Returns the HTML or text version of the email either as content type 'application/json' or 'text/html'.

/api/v2/email/<id>/ responsesummary

POST

Returns the summary of the responses of a launched, paused, activated or deactivated email.

/api/v2/email/<id>/ sendtestmail

POST

Instructs the system to send a test email.

/api/v2/email/<id>/url

POST

Returns the URL to the online version of an email, provided it has been sent to the specified contact.

/api/v2/email/ getdeliverystatus

POST

Returns the delivery status of an email.

/api/v2/email/ getlaunchesofemail

GET

Lists all the launches of an email with ID, launch date and 'done' status.

/api/v2/email/ getresponses

POST

Exports the selected fields of all contacts which responded to emails in the specified time range.

/api/v2/emailcategory

GET

Returns a list of email categories which can be used in email creation.

/api/v2/event

GET

Returns a list of external events which can be used in programs.

/api/v2/event/<id>/ trigger

POST

Triggers the given event for the specified contact.

/api/v2/export

GET

Fetches the status data of an export.

/api/v2/field

GET

Returns a list of fields (including custom fields and vouchers) which can be used to personalize content.

/api/v2/field/<id>/ choice

GET

Returns the choice options of a field.

/api/v2/file

GET

Returns a customer's files.

/api/v2/file

POST

Uploads a file to a media database.

/api/v2/filter

GET

Returns a list of segments which can be used as recipient source for the email.

/api/v2/folder

GET

Returns a customer's folders.

/api/v2/form

GET

Returns a list of the customer's forms.

/api/v2/language

GET

Returns a list of languages which you can use in email creation.

/api/v2/source

GET

Returns a list of sources which can be used for creating contacts.

/api/v2/source/<id>

DELETE

Deletes an existing source.

/api/v2/source/create

POST

Creates a new source for the customer with the specified name.

74


EMS_00126.04

en-GB

Printed 19/04/2013


Testing book