SpamWall Operations Manual

The SpamWall API

The SpamWall API is available on all systems with the exception of the base SpamWall Lite edition.

The API can be used for most regular management functions of the SpamWall system. This would include such things as adding and deleting domains and user accounts, managing whitelist/blacklist information and changing user account passwords.

Most functions available at both the Domain Admin and individual user account level such as control over whitelist and blacklist settings and Spam Scoring levels are also available via the API and so these functions can be integrated into various other applications and control panels at these levels to provide domain owner/admins and individual email account users with access to their settings on the SpamWall in their own usual email viewing and management environments.

The SpamWall API is web service based and should be "called" like any other URL with the initiating application or script appending the appropriate command and variables to the URL in standard HTTP GET and POST request format and the output/response would be received in XML format.

The URL for access to the API on your SpamWall system would be in the following format:

http://spamwall.yourdomain.com/api/api.php


This example script shows how to connect to the SpamWall system API via PHP and cURL and retrieve the XML response.

SpamWall API Operating Guide

Contents

1. Introduction
2. Responses
3. Response Codes
4. Commands
4.1 Domain Commands (Admin Only)
4.2 User Commands
4.3 White/Black list Commands
4.4 Trusted IP Commands (Admin Only)
4.5 Recipient Verification Commands (Admin Only)
4.6 Spam Scoring Commands

1. Introduction

The SpamWall system API is a RESTful interface, which accepts commands as GET parameters. Authentication details are sent via POST parameters named 'username' and 'password'.

2. Responses

Responses from the SpamWall system are in the form of XML documents following a set format, e.g:

<?xml version="1.0" encoding="UTF-8" ?>
<Result>
<Code>200</Code>
<Message></Message>
</Result>

The response is always contained in <Result> tags, with <Code> specifying
the response code (see section 3).

Most commands also contain <Message>, which gives more information regarding
the return code in context.

Commands not containing <Message> will instead contain a block, usually listing
items returned by the request. For the exact format for each command, see
section 4.

3. Response Codes

Response codes try to follow the HTTP status codes, with 6 currently being
implemented:

200: Success - Request was successfully received
400: Bad Request - Request was malformed
401: Unauthorized - Login details were invalid
403: Forbidden - Insufficient access to perform the request
406: Not Acceptable - Request was valid, but could not be performed
500: Internal Server Error - An error occurred while processing the request

Only the numeric part of the response code will be returned by <Code>, with
<Message> providing related information e.g why a certain error occurred.

4. Commands

Commands are passed via GET via the URL parameter named 'command'. Parameters for the command are passed via URL parameters corresponding to the parameter name.

If the specified command does not exist, a '400: Bad Request' error code is returned. Please note parameters are case sensitive.

4.1 Domain Commands (Admin Only)

list_domains

Description: Lists the domains

Response:

<Domains>
<Domain>
<Host></Host>
<Type></Type>
<IP></IP>
<Port></Port>
</Domain>
</Domains>

add_domain

Parameters: name, ip, port

Description: Adds a domain

Response: 200 - Domain added to domain list successfully

User Errors (406):

* Invalid domain name
* Invalid IP address
* Invalid port
* Domain '<name>' is already in domain list

change_domain

Parameters: name, ip, port

Description: Changes a current domain

Response: 200 - Domain updated successfully

User Errors (406):

* Invalid domain name
* Invalid IP address
* Invalid port
* Domain '<name>' is not in domain list

delete_domain

Parameters: name

Description: Deletes the named domain

Response: 200 - Domain removed from domain list successfully

User Errors (406):

* Invalid domain name
* Domain '<name>' is not in domain list

4.2 User Commands

list_users

Parameters: user

user is either 'all', or in name@domain.com format. If the user making the request is a domain admin, 'all' is restricted to their domain and the domain portion of user must be their domain.

Description: Lists email user accounts

Response:

<Users>
<User>
<Username></Username>
<Name></Name>
<Email></Email>
<Last_login></Last_login>
</User>
</Users>

User Errors (403):

* Insufficient access to specified domain

add_user

Parameters: username, password, email, full_name

Description: Adds a user account to the system

Response: 200 - User added successfully

User Errors (403/406):

* Insufficient access to specified domain (403)
* Invalid Email
* Username already in use

change_user

Parameters: user, username, email, full_name

user is the username of the account you want to modify, and username is the new account name. To keep the account the same, set username to be equal to user.

Description: Modifies a user account

Response: 200 - User updated successfully

User Errors (403/406):

* Insufficient access to specified username (403)
* Insufficient access to specified domain (403)
* Invalid Email
* Username already in use

change_user_password

Parameters: user, newpass

Description: Changes the password to a user account

Response: 200 - User updated successfully

User Errors (403):

* Insufficient access to specified user

delete_user

Parameters: user

Description: Deletes a user account

Response: 200 - User deleted successfully

User Errors (403):

* Insufficient access to specified user

4.3 White/Black list Commands

whitelist_add

Parameters: email

Description: Adds an email to the whitelist

Response: 200 - Email added to whitelist successfully

User Errors (406):

* Invalid Email
* Email already in whitelist

blacklist_add

Parameters: email

Description: Adds an email to the blacklist

Response: 200 - Email added to blacklist successfully

User Errors (406):

* Invalid Email
* Email already in blacklist

whitelist_del

Parameters: email

Description: Removes an email from the whitelist

Response: 200 - Email deleted from whitelist successfully

User Errors (406):

* Invalid Email
* Email not in whitelist

blacklist_del

Parameters: email

Description: Removes an email from the blacklist

Response: 200 - Email deleted from blacklist successfully

User Errors (406):

* Invalid Email
* Email not in blacklist

4.4 Trusted IP Commands (Admin Only)

add_spam_bypass

add_rbl_bypass

Parameters: ip, full

full determines whether or not the IP should be treated as a full or partial IP address

Description:

Adds the IP to either the Spam Bypass list or the RBL Bypass list.
These are collectively known as the Trusted IP list.

Response: 200 - IP added to Trusted IP list successfully

User Errors (406):

* Not a valid IP
* Entry already in [Spam/RBL] bypass list


del_spam_bypass

del_rbl_bypass

Parameters: ip

Description: Removes an IP from the Trusted IP list (Spam or RBL)

Response: 200 - IP removed from Trusted IP list successfully

User Errors (406):

* Entry not in [Spam/RBL] bypass list


4.5 Recipient Verification Commands (Admin Only)


verification_method

Description: Returns the current recipient verification method
Response: 200 - <Verification Method>

set_verification_method

Parameters: method

method can take one of the following numerical values:
1 - No Recipient Verification
2 - Dynamic Recipient Verification
3 - Specify Allowed Recipients

Description: Sets the recipient verification method

Response: 200 - Recipient Verification Method changed successfully

User Errors (406):

* Invalid Recipient Verification Method


recipient_add

Parameters: email

Description: Adds an email to the allowed recipients list

Response: 200 - Recipient added successfully

User Errors (406):
* Recipient already exists
* Invalid Email


recipient_del

Parameters: email

Description: Removes an email from the allowed recipients list

Response: 200 - Recipient deleted successfully

User Errors (406):

* Recipient does not exist


recipients_clear

Description: Clears all emails from the allowed recipients list

Response: 200 - Allowed recipients list successfully cleared


recipients_list

Description: Lists all the emails in the allowed recipients list

Response:

<Recipients>
<Recipient>
<id></id>
<address></address>
</Recipient>
</Recipients>


recipients_transport_sync

Description: Syncs the Recipients List with the IP/Domain Setup Configuration

Response: 200 - Recipients list successfully synced with transport file


4.6 Spam Scoring Commands


spam_tag_level

spam_tag2_level

spam_kill_level

Description: Returns a Spam Score level

Response: 200 - <corresponding Spam Score level>

set_spam_tag_level

set_spam_tag2_level

set_spam_kill_level

Parameters: value

Description: Sets a Spam Score level

Response: 200 - Spam Score saved successfully

User Errors (406):

* Invalid Value

 

If you require advice or assistance with the SpamWall API you can request support from service@spamwall.com or complete and submit our online contact form.