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.
