Retrieving Available Spam Filtering Preferences

Use the get-allowed-preferences operation to retrieve Spam Filtering preferences available for a specified user (mailbox owner or Administrator). For information on Spam Filtering preferences available for a specified user, refer to the Spam Filtering Preferences section.

Request Packet Structure

A request XML packet retrieving available Spam Filtering preferences includes the get-allowed-preferences operation node:

<packet version="1.4.2.0">
<spamfilter>
<get-allowed-preferences>
...  
</get-allowed-preferences>
</spamfilter>
</packet>

The get-allowed-preferences node is presented by the SpamFilterGetAllowedPreferencesInputType type (spamfilter.xsd), and its graphical representation is as follows:

• The filter node is required. It specifies the filtering rule. Data type: SpamassassinFilterType (spamfilter.xsd).

Remarks

You can retrieve info on users specified by SpamAssassin ID, and users specified by e-mail address in a single packet. Add ID's of users specified by SpamAssassin ID to the filter node of the first get-allowed-preferences operation, and e-mail addresses of users specified by e-mail address (or 'admin' string) to the filter node of the second get-allowed-preferences operation.

<get-allowed-preferences>
<filter>
... 
</filter>
</get-allowed-preferences>
 
<get-allowed-preferences>
<filter>
... 
</filter>
</get-allowed-preferences>

Response Packet Structure

The get-allowed-preferences node of the output XML packet is presented by type SpamFilterGetAllowedPreferencesOutputType (spamfilter.xsd) and structured as follows:

• The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd).
• The status node is required. It specifies the execution status of the get-allowed-preferences operation. Data type: string. Allowed values: ok | error.
• The errcode node is optional. Is returns the error code if the get-allowed-preferences operation fails. Data type: integer.
• The errtext node is optional. It returns the error message if the get-allowed-preferences operation fails. Data type: string.
• The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Available Filters section. Data type: anySimpleType.
• The id node is optional. It does not return any data for this operation. Data type: integer.
• The preference node is optional. It holds Spam Filtering preferences available for the specified SpamAssassin user. Data type: string.

Note: preferences are separated by the <preference> tag.

Samples

Retrieving Spam Filtering preferences available for a single user

This request packet retrieves Spam Filtering service preferences available for Administrator.

<packet>
<spamfilter>
   <get-allowed-preferences>
      <filter>
         <username>admin</username>
      </filter>
   </get-allowed-preferences>
</spamfilter>
</packet>

Response:

<packet>
<spamfilter>
   <get-allowed-preferences>
   <result>
      <status>ok</status>
      <filter-id>admin</filter-id>
      <preference>personal</preference>
      <preference>max-children-process</preference>
      <preference>required-score</preference>
      <preference>rewrite-header</preference>
   </result>
   </get-allowed-preferences>
</spamfilter>
</packet>

If the SpamAssassin service is restricted by Plesk licence key, or a user does not have access to SpamAssassin management, the response is as follows:

<packet>
<spamfilter>
<get-allowed-preferences>
   <result>
      <status>error</status>
      <errcode>1006</errcode>
      <errtext>Permission denied.</errtext>
      <filter-id>admin</filter-id>
   </result>
</get-allowed-preferences>
</spamfilter>
</packet> 

Retrieving Spam Filtering preferences available for a mailbox and a SpamAssissin user

This request packet retrieves Spam Filtering preferences available for mailbox mybox@site.com, and SpamAssassin user with ID 7.

<packet>
<spamfilter>
 
   <get-allowed-preferences>
      <filter>
         <username>mybox@site.com</username>
      </filter>
   </get-allowed-preferences>
 
   <get-allowed-preferences>
      <filter>
         <spamfilter-id>7</spamfilter-id>
      </filter>
   </get-allowed-preferences>
 
</spamfilter>
</packet>

Response:

<packet>
<spamfilter>
   <get-allowed-preferences>
   <result>
      <status>ok</status>
      <filter-id>mybox@site.com</filter-id>
      <preference>personal</preference>
      <preference>max-children-process</preference>
      <preference>required-score</preference>
      <preference>rewrite-header</preference>
   </result>
   </get-allowed-preferences>
 
   <get-allowed-preferences>
   <result>
      <status>ok</status>
      <filter-id>7</filter-id>
      <preference>reject-spam</preference>
      <preference>required-score</preference>
      <preference>rewrite-header</preference>
   </result>
   </get-allowed-preferences>
</spamfilter>
</packet>

Retrieving Spam Filtering preferences available for multiple mailboxes

This request packet retrieves Spam Filtering preferences available for mailboxes mybox@site.com and my@site.com.

<packet>
<spamfilter>
   <get-allowed-preferences>
      <filter>
         <username>mybox@site.com</username>
         <username>my@site.com</username>
      </filter>
   </get-allowed-preferences>
</spamfilter>
</packet>

Response:

<packet>
<spamfilter>
   <get-allowed-preferences>
   <result>
      <status>ok</status>
      <filter-id>mybox@site.com</filter-id>
      <preference>personal</preference>
      <preference>max-children-process</preference>
      <preference>required-score</preference>
      <preference>rewrite-header</preference>
   </result>
   <result>
      <status>ok</status>
      <filter-id>my@site.com</filter-id>
      <preference>reject-spam</preference>
      <preference>required-score</preference>
      <preference>rewrite-header</preference>
   </result>
   </get-allowed-preferences>
</spamfilter>
</packet>