IMPORTANT NOTE: This article may contain outdated information. For the most up-to-date information related to this topic, please refer to the Hungarian version of this page.
In case you do not speak Hungarian, you can always translate the page with Google Translate.
Introduction
The purpose of the SalesAutopilot API (in the following referred to as API) is to make it possible to integrate SalesAutopilot (in the following referred to as SA) with external systems.
REST interface
API uses REST protocol interface and JSON data format. The API methods use HTTP GET, POST, PUT and DELETE methods.
AUTHENTICATION
Every API calling requests username and password. API uses HTTP Basic (for example from cURL) and Digest (for example from .NET) for authentication. You can choose which one you want to use.
For example if you use HTTP Basic Authentication you can place the username and the password in the header or in the request URL.
HTTP Basic Authentication in the request URL:
http://<username>:<password>@restapi.emesz.com/subscribe/<nl_id>/form/<ns_id>HTTP Basic Authentication in the header (with cURL):
curl_setopt($ch,CURLOPT_USERPWD,"username:letk4yewt52dszh8odkke3c5");
INPUT AND OUTPUT DATA FORMAT
Currently the JSON data format is supported both for input and output. Make sure your JSON is formed according to the standard and that it's properly encoded. Any input provided in the query string of any request should be url-encoded.
CHARACTER ENCODING
The API uses UTF-8 character encoding for both input and output.
RESPONSE STATUS CODES
The response includes the HTTP status code that represents the status of the request.
200 : the resource is successfully retrieved
401: authentication failed, wrong username or password
404 : unknown resource
405 : invalid method
406 : wrong parameters
500 : unhandled error occurred, contact our support
Handling subscribers
ADDING NEW SUBSCRIBERS
Adds a subscriber to an existing subscriber list. Create a signup form to the list or use and existing one. You can set a value for every field in the list. If the subscriber (email address) already exists in the list the request won't add the subscriber to the list since the email address is a unique identifier.
If there is an active "Subscriber" type of delivery schedule linked to the list it will send emails to the added subscriber. If the form has been set as double opt-in, the verification email will also be sent, if the proper delivery schedule is set and active.
Request:
http://restapi.emesz.com/subscribe/<nl_id>/form/<ns_id>Parameters:
The ID of the list to which the subscriber should be added.
ID of the signup form of the list
The body should contain the field-value pairs of the subscriber's data in JSON format. If the email is required field the JSON data should contain the email field and value.
Request Body:
{"email" : "test@mailmasterplus.com",
"mssys_firstname" : "John",
"mssys_lastname" : "Doe",
"mssys_company" : "XYZ Ltd."}
Response
Contains the ID of the added subscriber.
Expected response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 3
Error responses:
-1: if the email address has to be unique in the list and the email is already existing in the list.
-2: email address syntax error.
0: unknown error.
UPDATING A SUBSCRIBER
Updates any field of an existing subscriber record in the given list. The missing fields will remain unchanged. You will need a profile update form, and use its ID in the API request.
A subscriber can be identified by its ID or any field value pair. If the id is a field-value pair it's possible that more than one subscriber matches the condition. In that case all the matching subscribers data will be updated.
Request by ID:
http://restapi.emesz.com/update/<nl_id>/form/<ns_id>/record/<id>Parameters:
The ID of the list of which the subscriber should be updated.
ID of the signup form of the list
ID of subscriber whose data should be updated
Request by a certain field:
http://restapi.emesz.com/update/<nl_id>/form/<ns_id>/field/<field_name>/value/<field_value>Parameters:
The ID of the list of which the subscriber should be updated.
ID of the signup form of the list
Name of the field that is used to identify the updated subscribers.
Value of the field that is used to identify the updated subscribers.
The body should contain the field-value pairs of the subscriber's updated data in JSON format.
Request Body:
{"email" : "info@mailmasterplus.com",
"mssys_company" : "Top Ltd."}
Response
Contains the number of the updated subscribers.
Expected response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 1
If there is an error during update the response body will be empty.
GETTING SUBSRIBER'S DETAILS
Retrieves a subscriber's details including all fields in the list even system fields for example status, last activity date. If there is more than one subscriber that matches the request parameters all will be included in the response. Subscribers can be acquired by using one of the following methods.
Get all subscribers details from a list:
http://restapi.emesz.com/list/<nl_id>Parameters:
The ID of the subscriber list to which the subscribers belong.
Get a subscriber's details by the ID:
http://restapi.emesz.com/list/<nl_id>/record/<id>Parameters:
The ID of the subscriber list to which the subscribers belong.
The ID of the subscriber whose details should be retrieved.
Retrieves subscribers who match to a certain condition:
http://restapi.emesz.com/list/<nl_id>/field/<field_name>/value/<field_value>Parameters:
The ID of the subscriber list to which the subscribers belong.
Name of the field that is used to identify the retrieved subscribers.
Value of the field that is used to identify the retrieved subscribers.
Response
Contains the retrieved subscribers data in JSON format.
Expected response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"id" : "1"
"subdate" : "2012-03-12 09:30:23",
"active" : "1",
"mssys_last_activity_date" : "2012-03-29 11:11:22",
"email" : "test@mailmasterplus.com",
"mssys_firstname" : "John",
"mssys_lastname" : "Doe",
"mssys_company" : "XYZ Ltd."},
{"id" : "5"
"subdate" : "2012-03-12 10:01:20",
"active" : "1",
"mssys_last_activity_date" : "2012-03-29 11:12:01",
"email" : "info@mailmasterplus.com",
"mssys_firstname" : "George",
"mssys_lastname" : "Doe",
"mssys_company" : "Test Ltd."}]
If there is an error during update the response body will be empty.
UNSUBSCRIBING A SUBSCRIBER
Changes the status of an active subscriber to an unsubscribed subscriber who will no longer receive emails sent to the subscriber list to which they belong.
You can identify the subscriber by ID or email address.
Request:
http://restapi.emesz.com/unsubscribe/<nl_id>/record/<id>Parameters:
The ID of the subscriber list to which the subscriber belongs.
The ID of the subscriber who should be unsubscribed.
Request:
http://restapi.emesz.com/unsubscribe/<nl_id>/email/<email>Parameters:
The ID of the subscriber list to which the subscriber belongs.
The email address of the subscriber who should be unsubscribed.
Response
Expected response:
HTTP/1.1 200 OK 1
Error response:
The unsubscribe request hasn't been executed because of an error. For example the ID or email address is not in the list or it is unsubscribed already.
HTTP/1.1 200 OK -1
DELETING A SUBSCRIBER
Permanently deletes subscriber from the subscriber list to which they belong.
Request:
http://restapi.emesz.com/delete/<nl_id>/record/<id>Parameters:
The ID of the subscriber list to which the subscriber belongs.
The ID of the subscriber who should be deleted.
Response
Expected response:
HTTP/1.1 200 OK 1
Error response:
The delete request hasn't been executed because of an error. For example the ID or email address is not in the list or it is deleted already.
HTTP/1.1 200 OK -1
eCommerce handling
ADDING A NEW ORDER
Add a new order to an existing order list. The API request is working through an order form. If there is none, create one.
Request:
http://restapi.emesz.com/saveOrder/<nl_id>/form/<ns_id>Parameters:
The ID of the order list to which the order should be added.
The ID of the order form which is used to add the order.
The body should contain the field-value pairs of the order's data in JSON format. If the form is a multiple product order form the body should look like this:
Request Body:
{"email" : "test@mailmasterplus.com",
"mssys_firstname" : "John",
"mssys_lastname" : "Doe",
"mssys_company" : "XYZ Ltd.",
"shipping_method" : "2",
"products" : [{
"prod_id" : "23",
"qty" : "1"
},{
"prod_id" : "25",
"qty" : "2"
}
]}
You have to define the ordered product id (prod_id) and the ordered product quantity (qty) inside the products element.
If the form is a one product order form the request body should look like this:
Request Body:
{"email" : "test@mailmasterplus.com",
"mssys_firstname" : "John",
"mssys_lastname" : "Doe",
"mssys_company" : "XYZ Ltd.",
"shipping_method" : "2",
"prod_id" : "23"}
You have to define the ordered product id only (prod_id).
The shipping_method parameter is mandatory. This is the ID of the previously defined shipping method. You can find the ID in the first column in the Settings / eCommerce / Payment & Shipping methods screen in the first column.
Response
Contains the ID of the order.
Expected response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 3
Error response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 0
ADD PRODUCT TO THE PRODUCT LIST
Add a new product to the product list. Only the products in the list can be used in an order.
Request:
http://restapi.emesz.com/createproductThe body should contain the field-value pairs of the new product.
Request Body:
{"prod_name" : "Email automation eBook",
"prod_price" : "50",
"prod_vat_percent" : "19",
"prod_currency" : "EUR",
"prod_sku" : "EAE012",
"prodcat_ids" : {12}}
Parameters:
Name of the added product.
Price of the added product in the defined currency.
The value added tax in percent.
Currency of the added product. Allowed currencies are: EUR, USD, HUF
Stock keeping unit number of the added product.
Product category ids as a subarray.
Response
Expected response:
Contains the ID of the added product.
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 32
Error response:
If the product cannot be added the response body will be empty.
HTTP/1.1 200 OK
MODIFY A PRODUCT IN THE PRODUCT LIST
Modify an existing product in the product list.
Request:
http://restapi.emesz.com/modifyproduct/<prod_id>Parameters:
The ID of the product that should be modified.
The body should contain the field-value pairs of the modified data of the product.
Request Body:
{"prod_name" : "Email automation eBook",
"prod_price" : "55",
"prod_vat_percent" : "19",
"prod_currency" : "EUR",
"prod_sku" : "EAE012",
"prodcat_ids" : {12}}
Parameters:
Name of the added product.
Price of the added product in the defined currency.
The value added tax in percent.
Currency of the added product. Allowed currencies are: EUR, USD, HUF
Stock keeping unit number of the added product.
Product category ids as a subarray.
Response
Expected response:
If modification was successful the response body is "1".
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 1
Error response:
If the product cannot be modified the response body will be empty.
HTTP/1.1 200 OK
DELETE PRODUCT
Delete a product from the product list. The deletion has no effect on previous orders from this product.
Kérés:
http://restapi.emesz.com/deleteproduct/<prod_id>Parameters:
Id of the product that you want to delete.
Response
Expected response:
HTTP/1.1 200 OK 1
Error response:
The response will be -1 if there is an error. For example if the product id does not belong to the authenticated client.
HTTP/1.1 200 OK -1
GET A SPECIFIC PRODUCT DETAILS
Get a specific product's from the inventory by its ID.
Request:
http://restapi.emesz.com/getproduct/<prod_id>Parameters:
ID of the product.
You can find the ID of a specific product on the Product handling screen (left menu Settings / eCommerce ). Move the cursor over the name of the product and the product ID will be displayed.
Response
Expected response:
{"prod_id" : "4401",
"prod_name" : "Product name #1",
"prod_price" : "319.99",
"prod_vat_percent" : "12",
"prod_currency" : "EUR",
"prod_sku" : "PNM01",
"prodcat_name" : "Category #1"}
Error response:
Empty body.
HTTP/1.1 200 OK
LIST ALL PRODUCTS
List all products from the inventory.
Request:
http://restapi.emesz.com/listproductsResponse
Expected response:
A JSON array, in which each product is a subarray. The array keys are the product IDs.
{"4401":{"prod_id" : "4401",
"prod_name" : "Product name #1",
"prod_price" : "319.99",
"prod_vat_percent" : "27",
"prod_currency" : "EUR",
"prod_sku" : "PNM01",
"prodcat_name" : "Category #1"},
"4402":{"prod_id" : "4402",
"prod_name" : "Product name #2",
"prod_price" : "199.99",
"prod_vat_percent" : "12",
"prod_currency" : "EUR",
"prod_sku" : "PNM02",
"prodcat_name" : "Category #1"}
}
Error response:
Empty body.
HTTP/1.1 200 OK
Handling global variables
CREATING A GLOBAL VARIABLE
Creates a new global variable.
Request:
http://restapi.emesz.com/createglobalvarRequest Body:
Parameters:
Name of the global variable. It should contain the character of English alphabet, numbers and underscrore ( _ ) only.
Value of the global variable which will be merged into HTML contents (HTML email, landing pages, confirm pages).
Value of the global variable which will be merged into text emails only. Text value is optional.
Response
Expected response:
If global variable have been successfully created the response body will be "1".
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 1
Error response:
If the global variable cannot be created the response body will be empty.
HTTP/1.1 200 OK
MODIFY A GLOBAL VARIABLE
Modify an existing global variable.
Request:
http://restapi.emesz.com/updateglobalvarRequest Body:
Parameters:
Name of the global variable which should be modified. It should contain the character of English alphabet, numbers and underscrore ( _ ) only.
New value of the global variable which will be merged into HTML contents (HTML email, landing pages, confirm pages).
New value of the global variable which will be merged into text emails only. Text value is optional.
You can find the name of the global variables in the Settings / Global variables screen.
Response
Expected response:
If global variable have been successfully modified the response body will be "1".
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 1
Error response:
If the global variable cannot be modified the response body will be empty.
HTTP/1.1 200 OK
GETTING GLOBAL VARIABLE VALUES
Get the values of the global variable both HTML and text.
Request:
http://restapi.emesz.com/getglobalvar/name/<name>Parameters:
Name of the global variable to be retrieved.
Response
Expected response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"html" : "
Company Ltd.
Phone: 3222 22 22
info@mailmasterplus.com
", "text" : ">Company Ltd. Phone: 3222 22 222 info@mailmasterplus.com"}
Error response:
If the global variable cannot be retrieved the response body will be empty.
HTTP/1.1 200 OK
Virtual Call Center
DATA ECHANGE WITH VIRTUAL CALL ENTER (VCC)
This resource allows VCC to exchange data with SA. VCC sends data to SA, and SA updates subscriber's details with the received data. SA logs every the data exchange API calls.
Request:
http://restapi.emesz.com/vccupdaterecord/<mmsyncid>/project/<projectid>/record/<recordid>Parameters:
The ID of the VCC sync in SA. The ID is generated by SA, and you can find it int the URL what you should copy into VCC after creating a VCC sync.
The ID of the VCC project. This value has to be defined as a variable in VCC.
The ID of the VCC record. This value has to be defined as a variable in VCC.
The body should contain the field-value pairs of the subscriber's updated data in JSON format.
Request Body:
{"email" : "info@mailmasterplus.com",
"mssys_company" : "Top Ltd.",
"mssys_vccrecordid" : "10"}
Required parameters:
This is the ID of the record in the list that should be updated. If this value is empty SA will insert a new subscriber record into the list with data defined in the body.
Response
Expected response:
If the request has been successfully executed the result will be "1".
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 1
If there is an error during update the response body will be empty.
Comments
0 comments
Article is closed for comments.