Filtering is the way the request XML packet indicates the object (one or several mailing lists or sites) to which an operation will be applied. The request XML filters objects using a special <filter> section.

Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

MaillistFilterType

The MaillistFilterType filter is used in del-list, get-list, enable-list, disable-list operations to retrieve, remove, enable or disable mailing lists. For more information on the operations, refer to the Removing Mailing List, Retrieving Mailing Lists, Enabling Mailing List, Disabling Mailing List sections. Data type: MaillistFilterType (maillist.xsd). The graphical representation of the filter node is as follows:

image 36126

  • The id node is required. It specifies the mailing list ID in Plesk database. Data type: integer.
  • The name node is required. It specifies the mailing list name. Data type: string.
  • The site-id node is required. It specifies the site ID in Plesk database. Use this parameter to specify all mailing lists on the site (specified by ID). Data type: integer.
  • The site-name node is required. It specifies the site name. Use this parameter to specify all mailing lists on the site (specified by name). Data type: string.

You can match multiple mailing lists using this filter as in the following example:

<filter>
   <site-id>192</site-id>
   <site-id>19</site-id>
</filter>

Note: Use either id, name, site-id, or site-name parameters when creating a filtering rule. A packet containing a combination of id, site-id, name, and site-name parameters in a single filter node will be considered invalid by Plesk server.

MaillistSimpleFilterType

The MaillistSimpleFilterType filter is used in add-member, get-members, and del-member operations to add, retrieve, or remove mailing list subscribers. For more information on the operations, refer to the Adding Subscriber to Mailing List, Retrieving Subscribers’ Info, Removing Subscriber sections. Data type: MaillistSimpleFilterType (maillist.xsd). The graphical representation of the filter node is as follows:

image 36133

  • The list-id node is required. It specifies the mailing list ID in Plesk database. Data type: integer.
  • The list-name node is required. It specifies the mailing list name. Data type: string.

You can match multiple mailing lists using this filter as in the following example:

<filter>
   <list-id>1</list-id>
   <list-id>4</list-id>
</filter>

Note: Use either list-id, or list-name parameters when creating a filtering rule. A packet containing a combination of list-id and list-name parameters in a single filter node will be considered invalid by Plesk server.

MaillistToggleFilterType

The MaillistToggleFilterType filter is used in enable, disable, and get-status operations to activate, deactivate, or retrieve status of a mailing list service on a specified site. For more information on the operations, refer to the Activating Mailing Lists Service, Deactivating Mailing Lists Service, Retrieving Status of Mailing List Service sections. Data type: MaillistToggleFilterType (maillist.xsd). The graphical representation of the filter node is as follows:

image 36137

  • The site-id node is required. It specifies the site ID in Plesk database. Data type: integer.
  • The site-name node is required. It specifies the site name. Data type: string.

You can match multiple sites using this filter as in the following example:

<filter>
   <site-name>example.com</site-name>
   <site-name>mysite.com</site-name>
</filter>

Note: Use either site-id, or site-name parameters when creating a filtering rule. A packet containing a combination of site-id and site-name parameters in a single filter node will be considered invalid by Plesk server.

filter-id Node

image 34379

If an operation uses filters in a request packet, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet.

  • mailing list ID
  • mailing list name
  • site ID
  • site name

It is done to trace the request parameters in case of error. Data type: anySimpleType.

All operations except for the add-list possess the filter-id node in the response packet.