Modifying Mail Account Settings

Mail account settings can be modified either by Plesk Administrator or by Plesk customer. These settings are as follows:

  • Mail user access to his account through Plesk GUI
  • Mail box size
  • Mail box alias
  • Mail user permissions
  • Antivirus protection
  • Mail group members (if an account acts as a mail group)
  • Mail groups in which the mail account has membership
  • Files stored in the account repository
  • Automatic response messages
  • Mail addresses to which all incoming correspondence will be redirected automatically

The update operation is presented by three sub-operations: add, remove, and set. All these sub-operations were designed for working with the lists of objects kept in mail accounts.

  • The add sub-operation is a typical update operation. It means that all the setting specified in the packet will be added to a mail account, and the settings already existing will be kept unchanged. This sub-operation can be applied to any setting.
  • The remove sub-operation is a typical delete operation. It means that all the setting specified in the packet will be removed from a mail account. The settings not mentioned in the packet will be kept unchanged.
  • The set sub-operation is a hybrid (delete + update) operation. It means that all settings specified in the packet will replace all the settings already existing for the mail account.

Request Packet Structure

A request XML packet updating mail account settings includes the update operation node:

<packet>
 <mail>
  <update>
   ...
  </update>
 </mail>
</packet>

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

image-34507.png

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 update operation breaks into three types of update:

  • The add node is required. If specified, it adds the passed in settings to the mail account (all previously set settings are kept unchanged). Data type: none.
  • The remove node is required. If specified, it removes the passed in settings from the specified mail account. Data type: none.
  • The set node is required. If specified, it removes all previously set settings from the mail user account and sets the passed in settings anew. Data type: none.
  • The filter node is required. It specifies the site which mail accounts will be modified, and the settings of each account as well. Data type: mailnameFilterType (mail_input.xsd). See the structure of this node in the Available Filters section.

Note

When creating request packets, put nodes and elements in the order they follow in the packet structure.

Response Packet Structure

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

image-34511.png

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 add node is required. It returns the result of the add sub-operation (the passed-in settings are added to the mail account, all previously set settings are kept unchanged). Data type: none.
  • The remove node is required. It returns the result of the remove sub-operation (the passed-in settings are removed from the mail account, other settings are kept unchanged). Data type: none.
  • The set node is required. It returns the result of the set sub-operation (all previously set settings are removed, after which the passed-in settings are applied to the mail account). Data type: none.
  • The result node is required. It wraps the result of the update operation. Data type: operationresultType (mail_output.xsd).
  • The status node is required. It returns the execution status of the update operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. It returns an error code when the update operation fails. Data type: unsignedInt.
  • The errtext node is optional. It returns an error message if the update operation fails. Data type: string.
  • The mailname node is optional. It is required if the update operation succeeds. Returns a list of updated mail accounts. Data type: complex (mail_output.xsd).
  • The name node is optional. It contains a mail account name. Data type: string.

Samples

Adding new mail account settings

The following packet updates a mail account as follows: New email addresses are added to receive webmaster correspondence.

<packet>
<mail>
<update>
   <add>
      <filter>
          <site-id>1</site-id>
          <mailname>
              <name>admin11</name>
              <forwarding>
                 <address>bob@advent.co.uk</address>
                 <address>ann@advent.co.uk</address>
                 <address>nick@advent.co.uk</address>
              </forwarding>
          </mailname>
      </filter>
   </add>
</update>
</mail>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <mail>
    <update>
      <add>
        <result>
          <status>ok</status>
          <mailname>
            <name>admin11</name>
          </mailname>
        </result>
      </add>
    </update>
  </mail>
</packet>

Removing mail account settings

The following packet removes several email forwarding addresses:

<packet>
<mail>
<update>
   <remove>
      <filter>
          <site-id>12</site-id>
          <mailname>
              <name>webmaster</name>
              <forwarding>
                 <address>bob@advent.co.uk</address>
                 <address>ann@advent.co.uk</address>
                 <address>nick@advent.co.uk</address>
              </forwarding>
          </mailname>
      </filter>
   </remove>
</update>
</mail>
</packet>

Setting new mail account settings

The following packet changes password to the admin mail account and saves it in a hashed form:

<packet>
<mail>
<update>
   <set>
      <filter>
          <site-id>1</site-id>
          <mailname>
              <name>contact</name>
<password>
   <value>pass123456</value>
   <type>crypt</type>
</password>
          </mailname>
      </filter>
   </set>
</update>
</mail>
</packet>

Note

This request works on Linux only, as the ‘crypt’ password type is not supported on Windows.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.8.0">
  <mail>
    <update>
      <set>
        <result>
          <status>ok</status>
          <mailname>
            <name>contact</name>
          </mailname>
        </result>
      </set>
    </update>
  </mail>
</packet>