SpamPort API

Basic information

All your requests to the API must be made by POSTing information to https://www.spamport.com/api. With every request, you need to provide at least your SpamPort username and password. Every request also requires other information, please look up the specific requirements for each function on this page.

For every request, SpamPort will provide a JSON encoded result. You can parse the data we return. The data will contain a result in case the request was made successfully, or error in case something went wrong. The rest of the data will explain the error. At the end of this page you will find a list of possible errors.

If you use PHP, there is a PHP class available: SpamPort PHP class on Github

If you use HostFact, there is a PHP HostFact plugin for SpamPort available: SpamPort HostFact plugin on Github

Actions

With the SpamPort API, you can perform the following actions:

Add a domain
Delete a domain
Get a login URL
Get domain info
Get list of domains
Generate new password for domain
Set outgoing mailserver for domain
Set e-mail address for daily report
Turn spamfilter on or off for domain
Set spamfilter strictness
Turn greylisting on or off for domain
Possible errors

The API is made very basic, so it is easy to build it into your own system. If you use PHP, you can download our API file (coming soon) to include and we will provide example code.

Note about version number: Because the API might change in functionality, we supply a version number. This should help keep backwards compatibility.

API functions

Add a domain

The Add domain function will add a new domain to SpamPort, which means we will begin accepting and filtering messages for the domain immediately. After adding the domain, you will have to change the MX records of the domain so mail will be delivered to SpamPort.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	add
domain	The domain name you wish to add to SpamPort
transport	The destination mailserver (like: mail.yourdomain.com, or an IPv4/IPv6 address). This is the place where you want your filtered email to go.
transport_type	"hostname" if you provide a hostname (like: mail.yourdomain.com) or "ip" if you provide an IP address (ipv4/ipv6)
archive	The number of days you wish to archive your mail for. Can be 14 or 365; in case of 365 you also need to have a "mail archiving" license
report_to	If you wish to set up an address for the daily reports to go to, please provide an email address (like: info@yourdomain.com). This is optional and can be left empty.
weekly	Set weekly to 1 to make it a weekly report, otherwise it will be a daily report.
noscan	Set to 1 if you want to disable the spamfilter on this domain. Default is 0, can be left empty
spamscore	Set to veryhigh, high, normal, low, verylow. Default is "normal", can be left empty. Very high has the biggest chance of false positives (blocking legitimate mails), very low means some spam might come through.
greylist	Set to 1 to enable greylisting, set to 0 to disable greylisting

Success response: {"message":"Domain added successfully","status":"success"}

Delete a domain

The Delete domain function will remove a domain (including all archived mails) from SpamPort. This cannot be undone.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	remove
domain	The domain name you wish to remove from SpamPort

Success response: {"message":"Domain deleted successfully","status":"success"}

Get a login URL

The Login function will retrieve a login URL, which you use to directly login to SpamPort without having to provide a password. This URL is only valid for a maximum of 1 minute. You can redirect your customer to this URL so your customer can manage their mail settings.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	login
domain	The domain name you wish to get an URL for.

Success response: {"message":"<code>","status":"success"}

Redirect your client to: https://www.spamport.com/login/<domain>/<code> for direct login.

Get domain info

The Get domain info function will show the settings of a domain in SpamPort. The "transport" (destination mailserver for this domain), added date, and current report address are shown as a JSON encoded array.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	info
domain	The domain name you wish to see the information of

Success response: {"message":{"domain":"spamport.com","transport":"smtp:mail.spamport.com","added":"2016-10-05","report_to":"","spamscore":"normal","noscan":"0","greylist":"0"},"status":"success"}

Get list of domains

The Get list of domains function will retrieve a list of all your domains in SpamPort, returned as a JSON encoded array.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	get_domains

Success response: {"message":[{"domain":"spamport1.com","transport":"smtp:mail.spamport1.com","added":"2016-09-27","report_to":""},{"domain":"spamport2.com","transport":"smtp:mail.spamport2.com","added":"2016-09-28","report_to":"info@spamport2.com"}],"status":"success"}

Generate new password for domain

Update the password of a domain in SpamPort. A newly generated password will be returned.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	new_password
domain	The domain name you wish to update the password of

Success response: {"message":"<new password>","status":"success"}

Set outgoing mailserver for domain

Update the mail delivery server of a domain in SpamPort.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	set_outgoing
domain	The domain name you wish to change the outgoing mailserver of
outgoing	The hostname or IP of the server that should receive all "clean" mails for this domain
transport	Type of outgoing. Can be "hostname", or "ip" for an IP adress (ipv4/ipv6)

Success response: {"message":"Domain updated","status":"success"}

Set e-mail address for report

Update the "Report" mail address of a domain in SpamPort.

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	set_report_to
domain	The domain name you wish to change the report email address of
report_to	The email address that you wish to receive the report on. Can be empty to disable reports.
weekly	Set weekly to 1 to make it a weekly report, otherwise it will be a daily report.

Success response: {"message":"Domain updated","status":"success"}

Turn spamfilter on or off for domain

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	set_filter
domain	The domain name you wish to change the spamfilter setting of
noscan	Set to 1 to disable spamfilter, set to 0 to enable spamfilter

Success response: {"message":"Domain updated","status":"success"}

Set spamfilter strictness

Change the spamfilter strictness. You can set this to "veryhigh" with the risk of blocking legitimate mails, high, normal (recommended), low, or very low (some spam might come through).

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	set_spamscore
domain	The domain name you wish to change the filter strictness of
spamscore	Can be 'veryhigh' (might block legitimate mails), 'high', 'normal', 'low', 'verylow' (some spam might come through)

Success response: {"message":"Domain updated","status":"success"}

Turn greylisting on or off for domain

The following details need to be provided to the function:

Variable name	Value
username	The username you use to login to SpamPort
password	The password you use to login to SpamPort
version	1.8
function	set_greylist
domain	The domain name you wish to change the greylisting setting of
greylist	Set to 1 to enable greylisting, set to 0 to disable greylisting

Success response: {"message":"Domain updated","status":"success"}

Possible errors

This is a list of all possible errors.

Error	Description
{"message":"No username supplied","status":"failure"}	Username is mandatory
{"message":"No password supplied","status":"failure"}	Password is mandatory
{"message":"Login blocked","status":"failure"}	Too many verification errors from your IP, so your IP is blocked. Contact info@spamport.com
{"message":"No domain supplied","status":"failure"}	Domain is mandatory
{"message":"Outdated version of Spamport_API. Please upgrade via https://github.com/jordenc/SpamPort","status":"failure"}	The version of the Spamport_API you are using is outdated and no longer supported. Go to https://github.com/jordenc/SpamPort to download the latest version.
{"message":"Invalid domain name supplied","status":"failure"}	Invalid domain name supplied. Domain must look like 'yourdomain.ext'
{"message":"Domain not found","status":"failure"}	Supplied domain was not found in your account
{"message":"License fully used","status":"failure"}	Trying to add a new domain to filter but failing because it exceeds your license
{"message":"Archive license fully used","status":"failure"}	Trying to add a new domain to archive mail but failing because it exceeds your archiving license
{"message":"transport_type can be either 'hostname' or 'ip'","status":"failure"}	Invalid transport_type supplied
{"message":"Invalid domain: <domain>","status":"failure"}	Invalid domain name supplied
{"message":"Invalid transport: <destination>","status":"failure"}	Invalid destination mailserver supplied
{"message":"Domain already exists: <domain>","status":"failure"}	Trying to add a domain that already exists on the server
{"message":"Invalid data for archiving (must be 14 or 365): <archive>","status":"failure"}	The 'archive' amount must be 14 or 365 days, invalid amount supplied
{"message":"Invalid reporting mail address supplied: <report_to>","status":"failure"}	The 'report_to' must be a valid mail address in the form of 'info@yourdomain.ext'
{"message":"No domains found","status":"failure"}	There are no domains in your account
{"message":"Unknown error","status":"failure"}	An unknown error happened
{"message":"Unknown action","status":"failure"}	The action must be one of these values: add/remove/login/info/get_domains