Use the set_prefs operation to retrieve mail service settings set for the specified sites.

Request Packet Structure

A request XML packet that asks for mail service settings for a certain site should include the get_prefs operation node:

<packet>
<mail>
 <get_prefs>
  ...
 </get_prefs>
</mail>
</packet>

The get_prefs node does not have a separate type, it is nested within the MailTypeRequest type (mail_input.xsd). The get_prefs node has the following graphics representation:

image 34545

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 holds a list of sites which mail service settings are requested. Data type: none.
  • The site-id node is optional. It specifies an identifier of the site which mail service settings are requested. Data type: integer.

Note: When creating request packets, put nodes and elements in the order they follow in the packet structure. Otherwise you may get the error “Parse error. … This element is not expected.”

Response Packet Structure

The get_prefs node of the response packet is structured as follows:

image 34548

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 optional. It wraps the result of the requested get_prefs operation. It can be missing if some error occurs before the validation starts. Data type: resultType (common.xsd).
  • The status node is required. Returns the execution status of the get_prefs operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. Returns an error code when the get_prefs operation fails. Data type: unsignedInt.
  • The errtext node is optional. Returns an error message if the get_prefs operation fails. Data type: string.
  • The site-id node is optional. Returns the identifier of the site which mail service settings are retrieved. Data type: integer.
  • The prefs node is optional. Returns a collection of mail service preferences set for the specified site. Data type: MailPreferences (plesk_mail.xsd). The structure of the node is described in the Mail Service Settings section.

Samples

Getting Mail Service Preferences under Plesk Administrator

Plesk Administrator can get mail service preferences for all sites registered in Plesk.

Getting mail service preferences for particular sites

The following packet demonstrates how Plesk Administrator requests for mail service settings of three sites:

To get the mail service settings set for particular sites, use the following packet:

<packet>
<mail>
<get_prefs>
   <filter>
      <site-id>1</site-id>
      <site-id>2</site-id>
      <site-id>3</site-id>
   </filter>
</get_prefs>
</mail>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <mail>
    <get_prefs>
      <result>
        <status>ok</status>
        <site-id>1</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>2</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>false</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>3</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
    </get_prefs>
  </mail>
</packet>

To request these settings for all sites registered in Plesk, the following packet must be used:

<packet>
<mail>
<get_prefs>
   <filter/>
</get_prefs>
</mail>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <mail>
    <get_prefs>
      <result>
        <status>ok</status>
        <site-id>1</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>2</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>false</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>3</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>4</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
    </get_prefs>
  </mail>
</packet>

Getting Email Service Settings under customer

All the use cases of the get_prefs operation for customers are similar to those for Plesk Administrator, described above. The only difference is that an empty filter means that the specified settings will be retrieved from all sites belonging to Plesk customer sending the packet:

<packet>
<mail>
<get_prefs>
   <filter/>
</get_prefs>
</mail>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <mail>
    <get_prefs>
      <result>
        <status>ok</status>
        <site-id>1</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>2</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>false</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>3</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
      <result>
        <status>ok</status>
        <site-id>4</site-id>
        <prefs>
          <nonexistent-user>
            <reject/>
          </nonexistent-user>
          <webmail>none</webmail>
          <spam-protect-sign>false</spam-protect-sign>
          <mailservice>true</mailservice>
        </prefs>
      </result>
    </get_prefs>
  </mail>
</packet>