The Mimecast API uses a customized variant of the REST model of state transfer. The main distinguishing feature of the Mimecast API style, is greater uniformity in calls and responses.

post-REST

We use the POST verb for almost all requests, with the actual function of the request indicated in the URL and most endpoints expecting a JSON body containing details of the request.

Paths and namespaces

All URL paths begin with '/api/' followed by a namespace indicating the functional area of the resource and then a function, for example '/api/domain/create-domain.' URL paths never contain identifiers or data.

How to configure requests

Mimecast API function call paths contain no identifiers or data. Such data is instead delivered in the POST body. For example, rather than:

GET /api/domain?domain=mydomain.com‍‍‍‍‍‍‍

We use:

POST /api/domain/get-internal-domain
{
    "data":[
        {
            "domain":"mydomain.com"
        }
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The second term in the request URL path is a namespace representing an area of functionality. For example, in the above call, 'domain' indicates the functional area concerned with the management of domain names used in customer email addresses.

The last term in the path (in this case, get-internal-domain) indicates the specific action to be executed.

The request body

Most Mimecast API calls require a content body containing details of the request. This is to be provided as a JSON object containing a field named, 'data', whose value is a JSON array containing the data items and parameters to be used in the method call.

When multiple items are contained in the 'data' array, the result is equivalent to calling the same endpoint with each item individually. For example, we could request data for several internal domains as follows:

POST /api/domain/get-internal-domain
{
    "data":[
        {
            "domain":"mydomain.com"
        },
        {
            "domain":"myotherdomain.com"
        }
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

What to expect in responses

Return codes

HTTP response codes from the Mimecast API are strictly indicative of the HTTP call status and not the result of the function itself. A 404 means that the request URL does not exist. A 200 means that the HTTP call was successfully received and processed. That is, the function was found and executed correctly, however, this does not mean that the requested action was successful. Function-level success or failure is indicated in the response body content.

Please see the Mimecast Response Code Reference‌ guide for a complete list of expected response codes, sub-codes and their definitions.

The response body

All requests except where binary data is returned will return the same base JSON structure. The objects in the body will include the following:

• data - an array of objects which contain the data requested, if any has been found.
• meta - an object, which contains a status field that reflects the outcome of the call. It may also contain other call metadata such as:
• pagination - an object, which contains paging information for multi-paged data sets. (If no paging is present, this object may be omitted.)
• fail - an array of objects which, if not empty, indicates a call failure. This contains details of the failure, including a "key" field, which indicates the parameter associated with the failure. If no fail object is present, the call is considered a success.

For example, a call to /api/domain/get-internal-domain might return the following:

200 OK
{
    "meta": {
        "status": 200
    },
    "data": [
        {
            "id": "ItMlXSUUouLS7Jz00tSs5PSQWa6OziGmOzM9T",
            "domain": "valid.domain.com",
            "sendOnly": false,
            "local": false,
            "inboundType": "any"
        }
    ],
    "fail": []
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Or, in a failure case, it might return this:

200 OK
{
    "meta": {
        "status": 200
    },
    "data": [],
    "fail": [
        {
            "key": {
                "domain": "nonexistent.domain.com"
            },
            "errors": [
                {
                    "code": "err_domain_not_found",
                    "message": "Domain not found",
                    "retryable": false
                }
            ]
        }
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Pagination

When using an endpoint that returns lists of information, for example /api/audit/get-audit-events‌, responses will include a pagination object, with fields for next and previous pages where relevant. For example:

{
    "meta": {
        "status": 200,
        "pagination": {
            "pageSize": 25,
            "recordStart": 0,
            "next": "eNqrVipOTS4tSs.....",
            "previous": "eNqrVipOTS4tSs....."
            }
        },
    "data": [
                {
                    ...
                },..                
        ],
    "fail": [
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

NOTE: You will only receive a the 'next' field if there is more data to request.

Requesting the next / previous page

To request the next / previous page of data you need to take the token returned from the previous response and add it to the 'pageToken' key in the meta, pagination object of your request. For example,

{
    "meta": {
        "pagination": {
            "pageToken": "add token here"
        }
    },
   "data": [
       {
             ...
       }
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

NOTE: to request the previous page, substitute the 'next' key with 'previous' and use the 'previous' token from the last response.

Setting the page size

The page size relates to the number of results you would like back from the API for a given request. Page sizes can range between 1 and 100. To set the page size add the 'pageSize' key to the meta, pagination object, for example, to set a page size of 50:

{
    "meta": {
        "pagination": {
            "pageSize": 50,
            "pageToken": "add token here if applicable"
        }
    },
   "data": [
       {
             ...
       }
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Delegate Access

Delegate access relates to making API requests as a user from one Mimecast account for resources on another Mimecast account that the logged in user has permission to access, for example, an External Administrator.

To access an account you have delegated permission to access, add the 'accountCode' key to the 'meta' object in your request. For example,

{
    "meta": {
        "accountCode": "string"
    },
   "data": [
       {
             ...
       }
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

You will find the value of an account code for a Mimecast account in the Logon information section of the Administrator Console Dashboard‌.