Web Service (REST)

From eMarketeer Documentation
Jump to: navigation, search

The eMarketeer API is a so called Representational State Transfer (REST) Web Service.

Contents

Transfer

eMarketeer REST Service uses the HTTP protocol as message carrier.
The HTTP verbs used is POST and GET.

  • GET is used for read only operations
  • POST is used for all CRUD operations

URI Structure

The ReST cornerstone are the URI. The URI should point to the desired recourse by using nouns. We divert slightly from the rule by occasionally adding a verb into the URI. The eMarketeer URI is compiled by four parts.

  • First part points out the service. https://app.emarketeer.com/api/
  • Followed by your API ID for authentication. EXAMPLE/
  • The third part is the function or resource. contacts/
  • Last comes the parameters needed to fulfil the task. contacts[0][id]=144784&response=json

Don't forget the trailing / on parameter less queries.

Example URI
https://app.emarketeer.com/api/AJ237S45D23F4T5/contacts/&response=json&campaign=345

If you've customized your domain and want to use your new URI, you must not use HTTPS.
http://marketing.company.co.uk/api/EXAMPLE/campaigns/&response=xml

Payload

Type

Content type for CRUD calls (POST) are application/x-www-form-urlencoded

Encoding

Our system is primarily Unicode (UTF-8) encoded which means that all messages sent to us must be UTF-8 encoded.
Data posted as e.g. ISO/IEC 8859-1 Latin-1 might in best cases appear strange when viewed in eMarketeer and in worst case be inaccessible due to mismatching data.

Data containing '&' (ampersand) needs to be url-encoded in order to not corrupt the parameter string when posting data.

E-mail

To prevent failed deliveries it is strongly recommended to validate E-mail addresses before they are sent to eMarketeer. In some cases the e-mail address is used to match contacts. if corrupt addresses are used duplicates may be created.

eMarketeer support simple e-Mail addresses. The characters ! # $ % * / ? ^ ` { | } ~ are not allowed anywhere in the e-mail address.

Phone numbers

The format of the phone number is important for the mobile phone field if you intend to send text messages (SMS). eMarketeer has the ability to send SMS/Text messages to most countries in the world, so a incorrectly formatted number might miss its intended destination.

Format numbers with international call prefix (+ or 00)
If regional code starts with a 0, remove it or encapsulate it with parentheses (0).

Format: int. call prefix + country code + region code + phone number
+ 1 (234) 235 5678 (US)
00 46 730 898 345 (Swedish)
+ 47 410 08 341 (Norwegian)
+ 49 15221653225 (German)

Don't forget to URL-encode the phone number. If not the international call prefix (+) will get lost.

WADL

A complete list of functions are available in Web Application Description Language (WADL) format. WADL is an XML-based file format that provides a machine-readable description of HTTP-based web applications. WADL serves the same purpose for REST as WSDL does for SOAP.
https://app.emarketeer.com/api/EXAMPLE/description/

GET Functions

The read only functions of the web service is easily debugged using a web browser.

Contacts

The contacts function will list your contacts with the max 300 contacts per API Call restriction. To get the remaining contacts you'll need to iteratively call the function with a offset parameter. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/contacts/

Maximum number of contacts returned. Default and maximum value is 300. 

&max=300

Offset is an integer indicating the distance from start of the result source. 

&offset=300

Lists is the id of your list. 

&list=12

The search parameter will return contacts where the first name, last name, company or e-mail matches the search string. search parameter is ignored if it's combined with the list parameter. 

&search=Simpson

You can use the contacts parameter to pinpoint a contact. Contacts parameter can't be used together with the list or search parameters. The function is only able to get one contact at the moment. It's only possible to match on 'id' and 'email' fields at the moment. 

&contacts[0][id]=547484

&contacts[0][email]=ned@flanders.com

Lists

Gives you all your lists. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/lists/response=json

JSON Response 

{"rest":
{"lists":[
{"id":"176","name":"Spring campaign leads"},
{"id":"182","name":"New customers"},
{"id":"214","name":"Staff"},...
...

Campaigns

Lists all your campaigns. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/campaigns/response=xml

XMLResponse 

 <?xml version="1.0" encoding="utf-8" ?> 
 <rest>
 <campaigns>
 <campaign>
  <id>1764</id> 
  <name>Corporate Newsletter</name> 
  <created>2011-05-21 08:52:42</created> 
  <creator>Montgomery Burns</creator> 
  </campaign>
  <campaign>
  <id>1241</id> 
  <name>Kaizen</name> 
  <created>2011-02-19 16:01:34</created> 
  <creator>Homer Simpson</creator> 
...

Components

The components (E-Mail, SMS, Web pages & Forms) are organized in campaigns. To list the components in a campaign use the components function.

"campaign" is a mandatory parameter, "type" is a filtering parameter. 

&campaign=2312

E-Mail

&type=mail

Forms

&type=form

Web pages

&type=www

SMS

&type=sms

Counter

Shows your current API call counter status

XML response 

<?xml version="1.0" encoding="utf-8" ?> 
<rest>
<counter>
<calls>83</calls> 
<limit>100000</limit> 
<since>2010-12-29 10:22:39</since> 
</counter>
</rest>

Fields

Shows all your API accessible fields

XML example 

<?xml version="1.0" encoding="utf-8" ?> 
<rest>
 <fields>
  <field>
   <name>title</name> 
   <label>Title</label> 
  </field>
  <field>
   <name>email</name> 
   <label>E-mail Address</label> 
  </field>
  <field>
...
  <field>
   <name>c__is_vegetarian</name> 
   <label>Vegetarian</label> 
  </field>
  <field>
   <name>c__plays_golf</name> 
   <label>Golf player</label> 
  </field>
 </fields>
</rest>

POST Functions

Upsert Contacts

Use upsert contacts when you want to update or insert contacts into eMarketeer. The contacts array must not include more than 300 contacts. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/upsert_contacts/

Example of a parameters section of a HTTP POST 

&response=json
&contacts[0][email]=homer.j.simpson@emarketeer.com
&contacts[0][firstname]=Homer
&contacts[0][lastname]=Simpson 
&contacts[0][company]=Burs Energy Inc.
&contacts[0][c__miniature_golf_score]=58
&contacts[0][mobile]=+1 646 8435
&contacts[0][address1]=742 Evergreen Terrace
&contacts[0][city]=Springfield
&contacts[1][id]=554784
&contacts[1][email]=nahasapeemapetilon_12548@hotmail.com
&contacts[1][firstname]=Apu
&contacts[1][lastname]=Nahasapeemapetilon
&contacts[1][company]=Kwik-E-Mart
&contacts[1][c__degree]=Ph.D Computer Science
&contacts[1][telephone]=+1 344 2144
&contacts[1][city]=Springfield

In the call above: ”Homer Simpson” will be updated if he exist and created if not. ”Apu Nahasapeemapetilon” will be updated if the post exist, if not it will fail.

Custom fields

There are four types of custom fields:

  • Text field
  • Checkbox
  • Radiobutton
  • Date

A custom textbox is modified like the standard fields: 

&contacts[1][c__degree]=Ph.D Computer Science

A custom checkbox is modified by specifying true or false: 

&contacts[1][c__vegan]=true

A custom radiobutton is modified by the radiobutton label: 

&contacts[1][c__gender]=Male

A custom date field is modified by adding a date formated as YYYY-MM-DD (ISO 8601): 

&contacts[1][c__renewal_date]=2014-05-01

Delete Contacts

When deleting a contact or several contacts the same identifiers can be used as for upsert the only differences is that any other supplied data will be ignored and there is no particular hierarchy between the ids. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/delete_contacts/

&response_format=json
&contacts[0][email]=homer.j.simpson@emarketeer.com
&contacts[1][id]=554784
&contacts[2][external_id]=AK_34566

It is strongly recommended to not create contacts with identical e-mail address.

Sending SMS or E-mail

The send function takes two required variables besides the contact array.

  • component type (mail|sms)
  • component id 
https://app.emarketeer.com/api/API_ID_GOES_HERE/enqueue/

Example: Send a prepared SMS to two known contacts 

&type=sms
&id=4247
&contacts[0][id]=255724
&contacts[1][id]=254384
&contacts[2][email]=homer.j.simpson@emarketeer.com
&list=2578
&send_once=1

Copy Component (New)

Copy an E-mail, Webpage or SMS within a campaign. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/copy_component/

&response=xml
&campaign=210
&id=7836
&type=sms
&name=Webinar reminder

Update Content (New)

It is now possible to update E-mail or web page content for most block types. Updates are made one call per property. e.g. One call for new image url, one call to update the image width and one call to update the image hyperlink. examples will be added.

You specify which block in a component you want to update with the path parameter. The path consist of all block names from root to the target delimited with dots.
Example of path: root.main.article1.heading
Example of path using default names: root.column2.imageright180px1.image1

The property you want to update is specified with the property parameter.

Property list
Block Property mail webpage
Image url Yes Yes
clickurl Yes Yes
width Yes Yes
height Yes Yes
Container html Yes Yes
indexname Yes Yes
Link url Yes Yes
caption Yes Yes
Text text Yes Yes
Barcode code Yes Yes

Remember to URL encode your data. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/update_content/

&response=xml
&id=9822
&type=mail
&path=root.column2.imageright180px2.text1
&property=text
&text=Here goes the url encoded text that you want to add to the block

Update Component (New)

It is now possible to update some of the E-mail, Web page and SMS properties.

Property list
Property Example Email Webpage SMS Note
Title property=title, text=Welcome No Yes No
Subject property=subject, text=Welcome Yes No No
permalink property=permalink, text=Nicelink No Yes No
message property=message, text=Hi <% contact field="firstname" %>

Don't forget the seminar at The Exhibition And Congress Centre tomorrow at 12:00...

No No Yes URL encode data
Encoding property=encoding, text=1 No No Yes 1 = UCS-4BE (Unicode)
0 = ASCII (Plain text)
parts property=parts, text=8 No No Yes 6 parts are default,

Remember to URL encode your data. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/update_component/

&response=xml
&id=9822
&type=mail
&property=text
&text=Here goes the url encoded text that you want to add to the block

Create list

Organize users by adding them to lists (groups). Create a list with the create_list function and specify a name. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/create_list/

&response=xml
&name=Summer Expo 2010

Response: 

<?xml version="1.0" encoding="utf-8"?>
<rest>
	<status>
		<id>588</id>
		<name>Summer Expo 2010</name>
		<message>Created list successfully</message>
	</status>
</rest>

Delete list

Delete a list with the delete_list function. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/delete_list/

&response=xml
&list=588

Response: 

<?xml version="1.0" encoding="utf-8"?>
<rest>
	<status>
		<message>Deleted list 'Summer Expo 2010' successfully</message>
	</status>
</rest>

Add contacts to list

To add contacts use the add_to_list function and pass list as integer and a contacts array with the appropriate unique identifier 

https://app.emarketeer.com/api/API_ID_GOES_HERE/add_to_list/

&response=xml
&list=74
&contacts[0][id]=23234
&contacts[1][email]=noreply@duff.com

Truncate the list if you what to remove all contacts in the list before adding the new ones. 

&truncate=1

Response: 

<?xml version="1.0" encoding="utf-8"?>
<rest>
	<status>
		<id>23234</id>
		<message>Added Homer Simpson to list 'Duff'</message>
	</status>
	<status>
		<id>6679</id>
		<message>contact not found</message>
	</status>
</rest>

Remove contacts from list

Organize users by adding removing them from lists. 

https://app.emarketeer.com/api/API_ID_GOES_HERE/remove_from_list/

&response=xml
&list=74874
&contacts[0][id]=232344
&contacts[0][id]=626773

If you want to remove all contacts 

&response=xml
&list=74874
&truncate=1

Response: 

<?xml version="1.0" encoding="utf-8"?>
<rest>
	<status>
		<list>23234</list>
		<message>Removed Homer Simpson from list 'Duff'</message>
	</status>
</rest>

Unsubscribe contacts from campaign

Contacts can be flagged as unsubscribed per campaign or globally for all emails and SMSs 

https://app.emarketeer.com/api/API_ID_GOES_HERE/unsubscribe/

&campaign=1708
&contacts[0][id]=394548

Response: 

<?xml version="1.0" encoding="utf-8"?>
<rest>
	<status>
		<campaign>394548</campaign>	
		<message>Homer Simpson unsubscribed from campaign 1708</message>
	</status>
</rest>

Parameters

Contacts data is passed to the web service as an double dimensioned array.

Response

The REST service is not XML based as a SOAP Web Service but the default response from it is in XML format. An other response formats is the JSON format.

Note: the WADL file is not available in JSON.

JSON

JSON is a lightweight data-interchange format that is based on the object notation of the JavaScript language. Because of it's simple text format, JSON provides a good alternative to other data interchange formats such as our default response format XML. The response data is always UTF-8 encoded.

To get your response in JSON specify it in your call.
Call 

https://app.emarketeer.com/api/API_ID_GOES_HERE/delete_contacts/response=json

&response=json
&contacts[0][id]=3948
&contacts[1][id]=3949
&contacts[2][email]=address@emarketeer.com
&contacts[3][firstname]=Homer

Response: 

{"rest":[
{"id":"3948","message":"deleted"},
{"id":"3949","message":"not found"},
{"email":"address@emarketeer.com","message":"deleted"},
{"error":"No Unique identifier!"}]}

Note: the WADL document is not available in JSON.

XML

XML is the default response format of the REST Web Service.

Some characters in the XML response data will be encoded
'&' (ampersand) becomes '&amp;'
'<' (less than) becomes '&lt;'
'>' (greater than) becomes '&gt;'

Even dough the default response is XML it is good practice to specify the return format in your call. The obvious reason for that is to avoid unnecessary surprises if the default response format were to be changed in the future. 

&response=xml

A typical response from a GET query is a root node named "rest", child nodes named "status" containing a "message" element. Additional elements like "id", "email", "name" etc. might occur.
Call: 

delete_contacts
&response=xml
&contacts[0][id]=5040
&contacts[1][id]=4040
&contacts[2][email]=address@emarketeer.com
&contacts[3][firstname]=Homer

Response: 

<?xml version="1.0" encoding="utf-8"?>
<rest>
	<status>
		<id>5040</id>
		<message>deleted</message>
	</status>
	<status>
		<id>4040</id>
		<message>not found</message>
	</status>
	<status>
		<email>address@emarketeer.com</email>
		<message>not found</message>
	</status>
	<status>
		<error>No Unique identifier!</error>
	</status>
</rest>

Messages

The return message will inmost cases return status for each operation the service performs.
Warnings and errors might also contain a hint to what caused the event.

Status

The status message will in most cases return the status of operation object after it has been performed. If a set of contacts has been upserted the return message will return 'OK' for all successful updates. If anything has been deleted it will return 'deleted' and so on.

Warning

If something went wrong but there is a chance of completing the task, a warning will be issued.

Error

If the task is impossible to perform, an error will occur in the message.

Scenarios

Scenario 1

Let's assume that a company wants to send a confirmation/welcoming e-mail to new customers as they are entered into the company's CRM system. We also assume that an eMarketeer e-mail already is created and that we know its ID.

Two API calls is needs to perform the task:
1. Upsert Contact('s) to eMarketeer using the upsert_contacts function and retrieve the contact id('s) in the response from the server.
2. Address the message with the upserted contact id('s) by using the enqueue function.

Best practice:

  • locally store all new contacts and send the mail in one batch to minimize calls.
  • Verify e-mail addresses and mobile numbers before upsert to prevent failed deliveries.

Scenario 2

Your company has previously created forms, e-mails and web pages and uses automation to populate lists depending on answers and link clicks. The sales department can import the lists via the API using the contacts function and add the parameter $list.

Examples

The following examples do work but is not intended be used as is, due to lack of security (api_key exposed) or verification of input. (valid emails, URL-encoding etc.).

JavaScript

The following example shows how to populate a list by using AJAX from the Prototype JavaScript Framework. 

<script>
populate_list = function() {

	new Ajax.Request('https://emarketeer.com/api/YOURAPIKEY/campaigns/response=json',{
	method:'get',
	onSuccess: function(transport) {

		var html = '';
		var api = transport.responseText.evalJSON();
	
		for ( var i in api.rest.campaigns ) {		
			html += '<option value="' + i + '">' + 
				api.rest.campaigns[i].name + '</option>';
		}
		$('lists').update(html);
	},
	onFailure: function(){ alert('Something went wrong...') }
	});
}
</script>

C# .Net

This method posts the parameters to the URI via HTTP and returns the response as a string. 

        public string HttpPost(string uri, string parameters)
        {

            WebRequest theRequest = WebRequest.Create(uri);
            theRequest.ContentType = "application/x-www-form-urlencoded";

            theRequest.Method = "POST";
            byte[] byteArray = Encoding.UTF8.GetBytes(parameters); 
            Stream outStream = null;

            try
            {
                theRequest.ContentLength = byteArray.Length;
                outStream = theRequest.GetRequestStream();
                outStream.Write(byteArray, 0, byteArray.Length);
            }
            catch (WebException ex)
            {
                MessageBox.Show(ex.Message, "HttpPost: Request error",
                   MessageBoxButtons.OK, MessageBoxIcon.Error);
                return "";
            }
            finally
            {
                if (outStream != null)
                    outStream.Close();
            }

            try
            {
                WebResponse theResponse = theRequest.GetResponse();
                if (theResponse == null)
                { return "\n[No response object]"; }
                StreamReader inStream = new StreamReader(theResponse.GetResponseStream());
                return inStream.ReadToEnd().Trim();
            }
            catch (WebException ex)
            {
                MessageBox.Show(ex.Message, "HttpPost: Response error",
                   MessageBoxButtons.OK, MessageBoxIcon.Error);
            }
            return "[No response]";
        }

PHP

In thisPHP example the cURL object is set to get all campaigns, return them as a JSON string and last decode it into a PHP array.

cURL, HTTP GET Example

$api = curl_init();
curl_setopt($api, CURLOPT_URL,'https://emarketeer.com/api/YOURAPIKEY/campaigns/response=json');
curl_setopt($api, CURLOPT_RETURNTRANSFER, true);

$response_json = curl_exec ($api);
curl_close ($api);

$response_array = json_decode($response_json, true);

cURL, HTTP POST Example

$parameters = '&response=json&contacts[0][email]=homer.j.simpson@emarketeer.com
		&contacts[0][firstname]=Homer&contacts[0][lastname]=Simpson
		&contacts[0][company]=Burs Energy Inc.';
$api = curl_init();

curl_setopt($api, CURLOPT_URL,'https://app.emarketeer.com/api/YOURAPIKEY/upsert_contacts/');
curl_setopt($api, CURLOPT_RETURNTRANSFER, true);
curl_setopt($api, CURLOPT_POST, true);
curl_setopt($api, CURLOPT_POSTFIELDS, $parameters );

$response_json = curl_exec ($api);
curl_close ($api);

$response_array = json_decode($response_json, true);
Retrieved from "http://www.emarketeer.com/wiki/index.php?title=Web_Service_(REST)&oldid=1251"
Personal tools
Namespaces
Navigation
Toolbox