User GuideDeveloper Guide
Developer Guide
Maxemail statusxtremepush.com

API Communication Specification

Detail on how Maxemail expects to decode received API requests and how it will format responses

HTTP Request

HTTP Method

The HTTP request to the JSON API Service endpoint is usually made using HTTP POST. Although it is possible to also use HTTP GET, it is not usually recommended due to the character limitation imposed in GET, and that a HTTP GET is never used to affect a lasting change.

Authentication

As part of the request, it is a requirement to send an Authorization header. This should be using Basic Auth .

You will see in our example clients the header being added in a similar fashion to the example below:

var basicAuth = base64Encode(username + ':' + password);
header("Authorization: Basic $basicAuth");

Our .NET partners have informed us that when using the HttpWebRequest object, supplying a NetworkCredential object is not sufficient. This is because the request object won't apply the credentials unless the server responds with a 401 Unauthorized response to a non-authenticated request. It is therefore necessary to add the correct header directly to the request:

request.Headers.Add("Authorization", "Basic " + base64Encode("username:password"));

Content-type

Unusually, the API requires the Content-type (and therefore also the format of the request body) to be application/x-www-form-urlencoded. The exception to this is for file uploads, which must use multipart/form-data.

API Method

Upon receiving the request, the system will search the request parameters for a parameter named method, the value of which should be the string name of the method on the service. If this is valid, the system will then begin parsing the remaining parameters, in reflection to the method being called.

API Parameters

There are two accepted conventions for naming method parameters:

  1. Use the name defined against each method in this documentation, eg: emailAddress, data. This is the simplest way to achieve individual requests.
  2. Use incrementing numbers in the format argN, where N is the integer for the parameter number, starting at 0. This is useful for API clients which internally work using indexed parameters.

Parameter values are treated as simple strings. Where the documentation shows that a parameter is expected to be an array or object of key-value pairs, the value must be sent as a JSON string.

HTTP Response

Following a valid request, the system will return an HTTP 200 response with a JSON-encoded body.

Errors

Errors are handled in a similar way: the system will return an appropriate HTTP 4xx or 5xx status code, with a JSON-encoded body detailing the error message. We endeavour to make the system very verbose in its error messages, so hopefully the message itself should help solve any issues, however if you need to contact the Support Team it is extremely helpful to provide this information.

Request

POST /api/json/email_send HTTP/1.0
Host: server.example.com
Content-type: application/x-www-form-urlencoded
Content-length: 20
Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp5b3VUaG91Z2h0SVdvdWxkSW5jbHVkZVJlYWxDcmVkZW50aWFscz8=
 
method=triggerFolder

Response

{
  "success": false,
  "msg": "Invalid Method Call to triggerFolder. Requires 3, 0 given.",
  "code": 400
}

Deprecation warnings

Deprecated methods or usage patterns will return normal results, but include an HTTP Warning header. This follows the standard format using code 299 and so can be parsed by your API client to log as desired.

Following the agent string showing the current API version, the warning text will include :

  • the deprecated method name
  • the text "Deprecated:" and the version the deprecation was introduced
  • a reason or explanation of an alternative to use

Response headers

Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Date: Wed, 1 Jan 2020 00:00:00 GMT
Warning: 299 MxmApi/v123 "methodName Deprecated: 123 Reason or explanation of alternative"

Examples

The examples below aim to display the correct headers and body that you'd expect to see for a Maxemail API request.

Find a Recipient

A basic request using a simple named parameter, to recipient.findByEmailAddress.

Request

POST /api/json/recipient HTTP/1.0
Host: server.example.com
Content-type: application/x-www-form-urlencoded
Content-length: 214
Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp5b3VUaG91Z2h0SVdvdWxkSW5jbHVkZVJlYWxDcmVkZW50aWFscz8=
 
method=findByEmailAddress&emailAddress=recipient%40example.com

curl --request POST \
  --url https://mxm.xtremepush.com/api/json/recipient \
  --basic --user [email protected]:password123 \
  --data-urlencode "method=findByEmailAddress" \
  --data-urlencode "[email protected]"

$api = new \Maxemail\Api\Client([
    'username' => '[email protected]',
    'password' => 'password123',
]);
$recipientId = $api->recipient->findByEmailAddress('[email protected]');

Response

HTTP/1.1 200 OK
Cache-Control: max-age=1
Vary: Accept-Encoding
Content-Length: 5
Connection: close
Content-Type: application/json; charset=utf-8
 
12345

12345

// $recipientId
12345

Insert a new Email Campaign

This more complex request to email_campaign.insert still has a single parameter, but that parameter is an array of key-value pairs. The parameter is also named using the argN format.

Request

POST /api/json/email_campaign HTTP/1.0
Host: server.example.com
Content-type: application/x-www-form-urlencoded
Content-length: 214
Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp5b3VUaG91Z2h0SVdvdWxkSW5jbHVkZVJlYWxDcmVkZW50aWFscz8=
 
method=insert&arg0=%7B%22folder_id%22%3A1%2C%22name%22%3A%22test+email%22%2C%22subject_line%22%3A%22test+subject%22%2C%22from_address%22%3A%22from%40example.com%22%2C%22from_address_alias%22%3A%22From+Address%22%7D

curl --request POST \
  --url https://mxm.xtremepush.com/api/json/email_campaign \
  --basic --user [email protected]:password123 \
  --data-urlencode "method=insert" \
  --data-urlencode 'arg0={"folder_id":1,"name":"test email","subject_line":"test subject","from_address":"[email protected]","from_address_alias":"From Address"}'

$api = new \Maxemail\Api\Client([
    'username' => '[email protected]',
    'password' => 'password123',
]);
$email = $api->email_campaign->insert([
    'folder_id' => 1,
    'name' => 'test email',
    'subject_line' => 'test subject',
    'from_address' => '[email protected]',
    'from_address_alias' => 'From Address',
]);

The request parameters have been URL encoded; below is the body before it was URL encoded:

method=insert&arg0={"folder_id":1,"name":"test email","subject_line":"test subject","from_address":"[email protected]","from_address_alias":"From Address"}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=1
Vary: Accept-Encoding
Content-Length: 177
Connection: close
Content-Type: application/json; charset=utf-8
 
{"email_id":340,"campaign_id":"298","subject_line":"test subject","message_type":"both","from_address":"[email protected]","from_address_alias":"From Address","template_id":null}

{"email_id":340,"campaign_id":"298","subject_line":"test subject","message_type":"both","from_address":"[email protected]","from_address_alias":"From Address","template_id":null}

// $email
[
    'email_id' => 340,
    'campaign_id' => 298,
    'name' => 'test email',
    'subject_line' => 'test subject',
    'message_type' => 'both',
    'from_address' => '[email protected]',
    'from_address_alias' => 'From Address',
    'template_id' => null,
];