Spam Experts Help

Integrating with your own Software

We offer several pre-built implementations ready to install and integrate Spam Experts with various control panels. If you'd like to implement our solution into your own/proprietary application, control panel or any automation on your end you can use the following guidelines and implement it in a correct way.

Step 1: Determine the target audience

It's important to decide what the application should do. Should it create resellers, admins, domains, email users or something else? We offer two APIs with common but also different functionalities:

Software API

  • Available to: Software API users, Super Administrators [Only on Local Cloud]
  • Provides: All low/high level API calls with the exception of Control Panel specific functionality
  • Usage: via HTTP GET
  • Returns: Plaintext

Actions done may take a few minutes to show up in the web interface due to caching

This API offers most control, however it's only recommended for one-time actions as for general automation the Control API is recommended.

Control Panel API

  • Available to: Super Administrator, Administrator, Domain and Email users [Both Local- and Hosted Cloud]
  • Provides: Most-used functionality and Administrator functions
  • Usage: via HTTP GET
  • Returns: Plain-text or JSON (append /format/json/ to call)

Since this API integrates directly into the frontend, cache will be cleared automatically when required.

In our own integrations we make use of the Control Panel API since we need to have it functional on the Hosted Cloud as well and it needs to be able to work under a Administrator-level user.

If you do not require special API calls and if the Control Panel API is sufficient, it's recommended to use it instead.

Mixing calls is possible but not recommended.

Step 2: Familiarize yourself with the API

Both API's work slightly different and have their own documentation available.

The documentation always contains a (short) description of the functionality of the API call and an example link.

A public demo server is available to test your integration:

Step 3: Decide what to implement

Once you have familiarized yourself with the APIs and determined which one you'd like to use, it's time to decide which API calls are required.

For normal domain-automation and integration purposes we'll show you some examples on how it works.

In our example we'll be adding domain "example.com" as a real domain and "example.net" as an alias.

Adding a domain

Control Panel API:

/api/domain/add/domain/example.com/destinations/%5B%22mail.example.com%22%5D

Software API:

/cgi-bin/api?call=api_add_incoming_domain&domain=example.com&destination=mail.example.co

Removing a domain

Control Panel API:

/api/domain/remove/domain/example.com/

Software API:

/cgi-bin/api?call=api_remove_domain&domain=example.co

Adding a domain alias

Control Panel API:

api/domainalias/add/domain/example.com/alias/example.net

Software API:

cgi-bin/api?call=api_add_domain_alias&domain=example.com&alias=example.net

Removing a domain alias

Control Panel API:

api/domainalias/remove/domain/example.com/alias/example.net

Software API:

cgi-bin/api?call=api_remove_domain_alias&domain=example.com&alias=example.net

One-click login / SSO

If the request was done successfully you'll get a 40-character hash you can append to the URL of the control panel (antispam.hostname/?authticket=CODEHERE).

Sample SSO PHP script:

<?php
// ========== Parameters section ==========
// This is a sample sso.php script, please ensure to only use this in a secured environment
// This script can be called via url:
// https://antispam.webserver.hostname/some/secured/folder/sso.php?u=admin_domain_or_email_here
// The GET variable 'u' in the URL should contain the (sub-)admin, domain, or email for which you want
// to create an one-click-login link.
// API documentation is available at https://antispam.webserver.hostname
$cfg = array(
    'panel_host' => 'antispam.hostname',           // Please set the webinterface hostname.
    'admin_user' => 'admin_username',              // Please set your admin username.
    'admin_pass' => 'admin_password',              // Please set your admin password.
    'identifier' => 'custom_identifier',           // This is a custom field allowing to set an identifier for auditing, as all activity will be logged using this variable
    'new_window' => 0,                             // In case of 'output' parameter = 'link' this parameter tells where to open login link - in the same window (0) or in the new window (1)
    );
    $createAuthTicketURL =
        'https://' . $cfg['admin_user'] . ':' . $cfg['admin_pass'] . '@' . rtrim($cfg['panel_host'], '/')
        . '/api/authticket/create/username/' . (!empty($_REQUEST['u']) ? rawurlencode($_REQUEST['u']) : '');
$authTicket = trim(file_get_contents($createAuthTicketURL));
$url = 'https://' . rtrim($cfg['panel_host'], '/') . '/?authticket=' . $authTicket . '&identifier= ' . $identifier;
echo $url;
?>

Step 4: Configuration

To allow your application to communicate with the API. the following settings are required:

  • API / Control Panel URL
  • Username
  • Password

If you also want to automate DNS (MX) changes you also need:

  • Primary MX Record
  • Secondary MX Record (optional)
  • Tertiary MX Record (optional)

Making API Calls

You can make API calls with any HTTP-aware library/scripting language or application. It does not matter whether this is something as simple as wget or more complex such as PHP or Python.

The latter two are better since they are also able to parse the output/JSON and determine whether the call succeeded.

For PHP you can make use of the file_get_contents call:

$result = json_decode(file_get_contents( "https://api.example.com/api/domain/add/domain/example.com/destinations/%5B%22mail.example.com%22%5D/format/json/" ));

The $result parameter will then contain the array of the resulting content which can be further parsed/processed.

Flows / Procedures

Some actions require changes on both sides: local (the hosting server) and remote (Spam Experts).

Adding a domain

  1. Add the domain to the system using one of the API's
  2. Parse the output, verify that it was successfully added
  3. Execute any required additional changes (for example: setting owner email address)
  4. Change the MX records for the domain to the configured primary/secondary/tertiary MX records

If you allow the customer to add/remove domains themselves, you must ensure that the input is validated and verify that they have access to their respective domain(s).

Removing a domain

  1. Revert the MX records to the local server (IP/hostname), mail.example.com or the domain name
  2. Remove the domain through the API

If you allow the customer to add/remove domains themselves, you must ensure that the input is validated and verify that they have access to their respective domain(s).