 |
SpamWall Online Operations
Manual
| SpamWall ISP/Webhost System API |
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
4.4 Recipient Verification Commands (Admin Only)
1. Introduction
The Email 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 server 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 occured 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 nam
* 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 Recipient Verification Commands (Admin Only)
verification_method
Description: Returns the current recipient
verification mehtod
Response: 200 - <Verification Method>
set_verification_method
Parameters: method
method can take one of the following numerical
values:
1 - No Recpient 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>
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.
|
|
|
