Skip to main content
xorlab API allows sending emails to xorlab Security Platform and receiving results of their analysis over HTTP instead of SMTP. This could be particularly useful when xorlab Security Platform is in monitoring mode—doesn’t take any action on emails, just analyzes them and gives verdicts.
Before you startPlease contact our support for the latest changes in xorlab API setup before you start configuring the API.

Configuration

  1. First, activate the API as the source for receiving emails by xorlab Security Platform. Open the activeguard/core/active_guard.yml file in Expert Editor and add the following line to scanSources:
  2. Add these two lines and set their values to the same value as mainWorkerCount. If mainWorkerCount is not set, use the default value of 20:
  3. Now, you can configure xorlab API itself in Expert Editor by navigating to the abby/abby/abby.yml file. When you open it, the following content appears:
  4. Under hosts, adjust the addresses of the xorlab MTAs such that they match your deployment:
  5. Under staticApiTokens, enter the name of your bearer authentication token and its value. For SaaS instances, the token will be preconfigured and provided by xorlab; for on-prem instances, we recommend using the openssl rand -hex 32 command to generate the token (32 bytes or 64 hex digits). In the following example, we generated the token with the value of c51bfe0df36d88823b9fe903a310f36e24b417e427309842605644dcc22a74ac:
  6. Click PUBLISH to apply changes.

API reference

Request

Requests are served by two endpoints:
  • /v1/messageQueue/submitEmail
  • /v1/admin/status
In order to process a message, our API requires the following arguments: The parameters argument accepts only one parameter, borderMtaData, which includes the following key:value pairs:
Maximum payloadThe maximum accepted payload size is 50 MiB. Payloads above this will result in a 413 error code.

Response

In response to your API request, you will receive either a message analysis result or an error. In the former case, the response will contain the following parameters:

Examples

cURL

This is a sample cURL command for sending an email to XSP for analysis:
where
  • <path to your eml file> is the path to the .eml file you wish to send, e.g., fileName.eml
  • <auth token> is the bearer auth token (see step #5 in the Configuration section above)
  • <your XSP instance> is the domain of your XSP instance, e.g., for xyz.activeguard.cloud, the full link would read https://xyz.activeguard.cloud:9081/v1/messageQueue/submitEmail

Python

The following Python script makes use of the cURL command described above:
The placeholders here—<auth token> and <your XSP instance>—are the same as for the cURL example.

Full API specifications