Retrieving Info on Spam Filtering service
Use the get operation to retrieve status of Spam Filtering service, and Spam Filtering preferences for a specified user (Administrator or mailbox owner).
Request Packet Structure
A request XML packet retrieving info on Spam Filtering service includes the get operation node:
<packet version="1.6.7.0">
<spamfilter>
<get>
...
</get>
</spamfilter>
</packet>
The get node is presented by the SpamFilterGetInputType type
(spamfilter.xsd
), and its graphical representation is as follows:
Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.
- 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 operation, and e-mail addresses of users specified by e-mail address (or string admin) to the filter node of the second get operation.
<get>
<filter>
...
</filter>
</get>
<get>
<filter>
...
</filter>
</get>
Response Packet Structure
The get node of the output XML packet is presented by type
SpamFilterGetOutputType (spamfilter.xsd
) and structured as
follows:
Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.
-
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 operation. Data type: string. Allowed values: ok | error.
-
The errcode node is optional. Is returns the error code if the get operation fails. Data type: integer.
-
The errtext node is optional. It returns the error message if the get 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 returns the ID of the Spamassassin user if the operation succeeds. Data type: integer.
The following nodes are nested in the response packet only if the operation succeeds:
-
The username node is optional. It holds the e-mail address of SpamAssassin user, or string ‘admin’. Data type: string.
-
The enabled node is optional. It specifies if the Spam Filtering service is enabled for a specified SpamAssassin user. For more information, refer to the Managing Spam Filtering section. Data type: none.
-
The disabled node is optional. It specifies if the Spam Filtering service is disabled for a specified SpamAssassin user. For more information, refer to the Managing Spam Filtering section. Data type: none.
-
The preferences node is optional. It specifies preferences of Spam Filtering service for a specified user. For information on preferences, refer to the Spam Filtering Preferences section. Data type: SpamassassinPreferencesType (
spamfilter.xsd
).
Samples
Retrieving info on a single user
This request packet retrieves configuration of Spam Filtering service for Administrator (server).
<packet>
<spamfilter>
<get>
<filter>
<username>admin</username>
</filter>
</get>
</spamfilter>
</packet>
Response:
<packet>
<spamfilter>
<get>
<result>
<status>ok</status>
<filter-id>admin</filter-id>
<id>1</id>
<username>admin</username>
<enabled/>
<preferences>
<personal>1</personal>
<max-children-process>5</max-children-process>
</preferences>
</result>
</get>
</spamfilter>
</packet>
If the SpamAssassin service was not found on the server, the response is as follows:
<packet>
<spamfilter>
<get>
<result>
<status>error</status>
<errcode>1026</errcode>
<errtext>Component is not installed.</errtext>
<filter-id>admin</filter-id>
</result>
</get>
</spamfilter>
</packet>
Retrieving info on multiple users
This request packet retrieves configuration of Spam Filtering service for mailboxes mybox@site.com and my@site.com.
<packet>
<spamfilter>
<get>
<filter>
<username>mybox@site.com</username>
<username>my@site.com</username>
</filter>
</get>
</spamfilter>
</packet>
Response:
<packet>
<spamfilter>
<get>
<result>
<status>ok</status>
<filter-id>mybox@site.com</filter-id>
<id>11</id>
<username>mybox@site.com</username>
<enabled/>
<preferences>
<rewrite-header>SPAM</rewrite-header>
</preferences>
</result>
<result>
<status>ok</status>
<filter-id>my@site.com</filter-id>
<id>12</id>
<username>my@site.com</username>
<disabled/>
<preferences>
<action>text</action>
</preferences>
</result>
</get>
</spamfilter>
</packet>