Skip to main content

SalesAutopilot API

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:

POST

http://restapi.emesz.com/subscribe/<nl_id>/form/<ns_id>

Parameters:

nl_id

The ID of the list to which the subscriber should be added.

ns_id

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:

PUT

http://restapi.emesz.com/update/<nl_id>/form/<ns_id>/record/<id>

Parameters:

nl_id

The ID of the list of which the subscriber should be updated.

ns_id

ID of the signup form of the list

id

ID of subscriber whose data should be updated

Request by a certain field:

PUT

http://restapi.emesz.com/update/<nl_id>/form/<ns_id>/field/<field_name>/value/<field_value>

Parameters:

nl_id

The ID of the list of which the subscriber should be updated.

ns_id

ID of the signup form of the list

field_name

Name of the field that is used to identify the updated subscribers.

field_value

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:

GET

http://restapi.emesz.com/list/<nl_id>

Parameters:

nl_id

The ID of the subscriber list to which the subscribers belong.

Get a subscriber's details by the ID:

GET

http://restapi.emesz.com/list/<nl_id>/record/<id>

Parameters:

nl_id

The ID of the subscriber list to which the subscribers belong.

id

The ID of the subscriber whose details should be retrieved.

Retrieves subscribers who match to a certain condition:

GET

http://restapi.emesz.com/list/<nl_id>/field/<field_name>/value/<field_value>

Parameters:

nl_id

The ID of the subscriber list to which the subscribers belong.

field_name

Name of the field that is used to identify the retrieved subscribers.

field_value

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:

GET

http://restapi.emesz.com/unsubscribe/<nl_id>/record/<id>

Parameters:

nl_id

The ID of the subscriber list to which the subscriber belongs.

id

The ID of the subscriber who should be unsubscribed.

Request:

GET

http://restapi.emesz.com/unsubscribe/<nl_id>/email/<email>

Parameters:

nl_id

The ID of the subscriber list to which the subscriber belongs.

email

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:

DELETE

http://restapi.emesz.com/delete/<nl_id>/record/<id>

Parameters:

nl_id

The ID of the subscriber list to which the subscriber belongs.

id

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:

POST

http://restapi.emesz.com/saveOrder/<nl_id>/form/<ns_id>

Parameters:

nl_id

The ID of the order list to which the order should be added.

id

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:

POST

http://restapi.emesz.com/createproduct

The 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:

prod_name

Name of the added product.

prod_price

Price of the added product in the defined currency.

prod_vat_percent

The value added tax in percent.

prod_currency

Currency of the added product. Allowed currencies are: EUR, USD, HUF

prod_sku

Stock keeping unit number of the added product.

prodcat_ids

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:

POST

http://restapi.emesz.com/modifyproduct/<prod_id>

Parameters:

prod_id

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:

prod_name

Name of the added product.

prod_price

Price of the added product in the defined currency.

prod_vat_percent

The value added tax in percent.

prod_currency

Currency of the added product. Allowed currencies are: EUR, USD, HUF

prod_sku

Stock keeping unit number of the added product.

prodcat_ids

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:

DELETE

http://restapi.emesz.com/deleteproduct/<prod_id>

Parameters:

prod_id

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:

GET

http://restapi.emesz.com/getproduct/<prod_id>

Parameters:

prod_id

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:

GET

http://restapi.emesz.com/listproducts

Response

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:

POST

http://restapi.emesz.com/createglobalvar

Request Body:

{"name" : "product_promo",
"html" : "

My eBook
Show description. Call to action

",
"text" : ""}

Parameters:

name

Name of the global variable. It should contain the character of English alphabet, numbers and underscrore ( _ ) only.

html

Value of the global variable which will be merged into HTML contents (HTML email, landing pages, confirm pages).

text

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:

POST

http://restapi.emesz.com/updateglobalvar

Request Body:

{"name" : "product_promo",
"html" : "

My eBook
Show description. Call to action

",
"text" : ""}

Parameters:

name

Name of the global variable which should be modified. It should contain the character of English alphabet, numbers and underscrore ( _ ) only.

html

New value of the global variable which will be merged into HTML contents (HTML email, landing pages, confirm pages).

text

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:

GET

http://restapi.emesz.com/getglobalvar/name/<name>

Parameters:

name

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:

PUT

http://restapi.emesz.com/vccupdaterecord/<mmsyncid>/project/<projectid>/record/<recordid>

Parameters:

mmsyncid

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.

projectid

The ID of the VCC project. This value has to be defined as a variable in VCC.

recordid

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:

mssys_vccrecordid

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.

Did this answer your question?