Using the Email Cloud REST API

Email Security - Cloud provides RESTful APIs for custom integration. The APIs are provided for Advanced Threats, Email Trace and Quarantine functionalities. To call the APIs, you must first configure the API keys or generate access tokens.

Important

There are two versions of IAM. If the domain you use to access the Trellix UI ends in fireeye.com, see Configuring API keys. If the domain you use to access the Trellix UI ends in trellix.com, see Generating an API access token.

Email Security — Cloud service regions

Use the URLs for the region that hosts your Email Security — Cloud service:

Access control

All the API requests follow the domain and domain group restrictions of the user. For example, if a user has access to only a few domains in their organization, the response to the APIs will be based on only those domains and domain groups.

REST API Concurrency

Email Security — Cloud REST APIs have a rate limit of 60 requests per minute per API route (/trace, /alert, and /quarantine) for every customer.

This means, in 1 minute, a customer can make:

Within the minute, the 61st request to any of these APIs would throw a rate limit exceeded error.

The rate limit applies to the customer as a whole. This means that if the customer has multiple admin users who have generated API Keys, the rate limit is applicable at the customer level and not per API key.

Response data size

The email trace API endpoints are configured to return a maximum of 300 records in the response for every request.

The alert and quarantine API endpoints are configured to return a maximum of 200 records in the response for every request.

Enhancing REST API performance when record set is huge

In some cases, the data set might be huge and the above-mentioned rate limit and response sizes might not be sufficient to retrieve all the desired records and be up to date. In such cases, requests could be run in parallel by making a more efficient use of the search filters supported by the APIs.

For example, if you have several domains for which you are trying to retrieve quarantine or trace records, the performance could be enhanced by splitting the request into multiple parallel requests having distinct sets of domains in each request. For example, domains 1-5 could be specified in the first request, domains 6-10 in the second request, and so on. This significantly enhances the response time per request, and thus more information could be returned within the rate limit window.

Quarantine example

Parallel requests split on domains—request 1:

curl -XPOST https://<APIURI>/quarantine/ -H 'x-fireeye-api-key: <APIKEY>' -d '
  {
    "attributes": {
      "domains": ["domain1.com", "domain2.com"]
    },
    "size": 200
  }'

Parallel requests split on domains—request 2:

curl -XPOST https://<APIURI>/quarantine/ -H 'x-fireeye-api-key: <APIKEY>' -d '
    {
        "attributes": {
            "domains": ["domain3.com", "domain4.com"]
        },
        "size": 200
    }
'

Trace example

Parallel requests split on domains—request 1:

curl -XPOST https://<APIURI>/messages/trace -H "Content-Type: application/json" -H "x-fireeye-api-key: <APIKEY>" -d '
{
  "attributes":  {
    "domains": { 
      "value": ["domain1.com", "domain2.com"]
    }
  },
  "size":300
}'

Parallel requests split on domains—request 2:

curl -k -XPOST https://<APIURI>/messages/trace -H "Content-Type: application/json" -H "x-fireeye-api-key: <APIKEY>" -d '
{
  "attributes": {
    "domains": { 
      "value": ["domain3.com", "domain4.com"]
    }
  },
  "size":300
}'