We offer several pre-built implementations ready to install and integrate SpamExperts 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 Admins [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 Admin and Admin users [Both Local Cloud and Hosted Cloud]
- Provides - Most-used functionality and Admin 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
Take a look into the Control Panel API documentation to familiarize yourself with it.
The API documentation contains all API calls that are available to use.
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 "demo-domain.invalid" as a real domain and "domain-alias.invalid" as an alias.
Adding a domain
Control Panel API:
/api/domain/add/domain/demo-domain.invalid/destinations/%5B%22mail.demo-domain.invalid%22%5D
Software API:
/cgi-bin/api?call=api_add_incoming_domain&domain=demo-domain.invalid&destination=mail.demo-domain.invalid
Removing a domain
Control Panel API:
/api/domain/remove/domain/demo-domain.invalid/
Software API:
/cgi-bin/api?call=api_remove_domain&domain=demo-domain.invalid
Adding a domain alias
Control Panel API:
api/domainalias/add/domain/demo-domain.invalid/alias/domain-alias.invalid
Software API:
cgi-bin/api?call=api_add_domain_alias&domain=demo-domain.invalid&alias=domain-alias.invalid
Removing a domain alias
Control Panel API:
api/domainalias/remove/domain/demo-domain.invalid/alias/domain-alias.invalid
Software API:
cgi-bin/api?call=api_remove_domain_alias&domain=demo-domain.invalid&alias=domain-alias.invalid
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.demo-domain.invalid/api/domain/add/domain/demo-domain.invalid/destinations/%5B%22mail.demo-domain.invalid%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 (SpamExperts).
Adding a domain
- Add the domain to the system using one of the API's
- Parse the output, verify that it was successfully added
- Execute any required additional changes (for example: setting owner email address)
- 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
- Revert the MX records to the local server (IP/hostname), mail.demo-domain.invalid or the domain name
- 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).
Disclaimer: This documentation may contain references to third party software or websites. N-able has no control over third party software or content and is not responsible for the availability, security, or operation, of any third-party software. If you decide to utilize a release involving third-party software, you do so entirely at your own risk and subject to the applicable third party’s terms and conditions of the use of such software. No information obtained by you from N-able or this documentation shall create any warranty for such software.