 |
SpamWall Online Operations
Manual
The SpamWall Spam Firewall 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.
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 or POST request format and the
output/response would be received in XML format.
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
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'.
This example
script shows how to connect to the SpamWall
system API via PHP and cURL and retrieve the XML response.
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
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.
SpamWall Operations Manual © 2009
SpamWall Systems - All
Rights Reserved.
|
|
|
