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 in a similar fashion to the example below:

var basicAuth = base64Encode(clientId + ':' + clientSecret);
header("Authorization: Basic $basicAuth");

The API explorer in this guide allows the API credentials to be set, to test the available API methods and provide working examples to copy.

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("clientId:clientSecret"));

📘
Before September 2025
Prior to the Maxemail release in September 2025, API authentication used a username & password combination sent using Basic Auth. This is now deprecated and will be withdrawn in Q2 2026. See the changelog.

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:

Use the name defined against each method in this documentation, eg: emailAddress, data. This is the simplest way to achieve individual requests.
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: Bearer abc123def456
 
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: Bearer abc123def456
 
method=findByEmailAddress&emailAddress=recipient%40example.com

curl --request POST \
  --url https://mxm.xtremepush.com/api/json/recipient \
  --header 'Authorization: Bearer abc123def456' \
  --data-urlencode "method=findByEmailAddress" \
  --data-urlencode "emailAddress=recipient@example.com"

$api = new \Maxemail\Api\Client([
    'token' => 'abc123def456',
]);
$recipientId = $api->recipient->findByEmailAddress('recipient@example.com');

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

// $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: Bearer abc123def456
 
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 \
  --header 'Authorization: Bearer abc123def456' \
  --data-urlencode "method=insert" \
  --data-urlencode 'arg0={"folder_id":1,"name":"test email","subject_line":"test subject","from_address":"from@example.com","from_address_alias":"From Address"}'

$api = new \Maxemail\Api\Client([
    'token' => 'abc123def456',
]);
$email = $api->email_campaign->insert([
    'folder_id' => 1,
    'name' => 'test email',
    'subject_line' => 'test subject',
    'from_address' => 'from@example.com',
    '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":"from@example.com","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":"from@example.com","from_address_alias":"From Address","template_id":null}

{"email_id":340,"campaign_id":"298","subject_line":"test subject","message_type":"both","from_address":"from@example.com","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' => 'from@example.com',
    'from_address_alias' => 'From Address',
    'template_id' => null,
];