By default, Plesk for Linux supports two webmail clients: Horde and RoundCube. To add custom webmail clients, you need to set them up using the Plesk SDK.

You add custom webmail clients by integrating them as webmail modules with Plesk. Once you do so, a custom webmail client becomes available to you and Plesk users in all Plesk interfaces: in the GUI, via the CLI, and via the API.

PleskSDKHookWebmail Hook

To add a custom webmail client, use the Plesk\SDK\Hook\Webmail hook. You need to return an anonymous class that extends the hook and implements the getWebmails method.

The class must be located in the /usr/local/psa/admin/plib/modules/custom-webmail/hooks/ directory.

Example

/usr/local/psa/admin/plib/modules/custom-webmail/hooks/Webmail.php

<?php

return new class extends \Plesk\SDK\Hook\Webmail
{
    public function getWebmails(): array
    {
        return [
            (new \Plesk\SDK\Webmail('custommail', 'Custom Webmail 1.2.5'))
                ->setLoginLinkTemplate('://webmail./?user=')
                ->setIsVisibleForDomainCallback(fn (\pm_Domain $domain): bool => $domain->hasPermission('custommail')),
        ];
    }
}

Setting The Login Link Template

Using \Plesk\SDK\Webmail classes, you can define the login link template. Users will log in to webmail using the link, which opens webmail in a separate browser window. If a custom webmail is chosen in Mail Settings of a domain, the link will be shown to the right of an email account in Websites & Domains > domain > the “Mail” tab > Mail Accounts.

The login link template ('://webmail./?user=')) is based on the Mustache template system and has the following structure:

• protocol: http or https
• domainName: the domain name in ASCII characters. It will be automatically converted to Punycode whenever necessary.
• mailName: the local part of the email address (before the “@” character)
• fullMailName: the URL encoded full email address (both the local and domain parts with the “@” character)

The template automatically substitutes its parts with actual values to create the login link. For example, the login link for john_doe@example.com when HTTPS is enabled for the example.com domain will look as follows:

https://webmail.example.com/?user=john_doe%40example.com

Hiding Custom Webmail

You can also restrict access to custom webmail based on permissions of a subscription or hosting plan. It means that a custom webmail client will not be displayed in the GUI, CLI, and API for all domains that belong to that subscription or hosting plan.

To hide custom webmail:

1. Define a permission using the pm_Hook_Permissions hook:

   class Modules_CustomMail_Permissions extends pm_Hook_Permissions
   {
       public function getPermissions(): array
       {
           return [
               'access_to_custommail' => [
                   'default' => true,
                   'place' => self::PLACE_ADDITIONAL,
                   'name' => 'Custom Webmail',
                   'description' => 'Grants access to Custom Webmail.',
               ],
           ];
       }
   }
   

2. Use the \Plesk\SDK\Webmail classes to pass a callback that takes \pm_Domain as a parameter and returns a boolean value to the setIsVisibleForDomainCallback method:

   <?php
   
   return new class extends \Plesk\SDK\Hook\Webmail
   {
       public function getWebmails(): array
       {
           return [
               (new \Plesk\SDK\Webmail('custommail', 'Custom Webmail 1.2.5'))
                   ->setLoginLinkTemplate('://webmail./?user=')
                   ->setIsVisibleForDomainCallback(fn (\pm_Domain $domain): bool => $domain->hasPermission('access_to_custommail')),
           ];
       }
   }
   

3. Hide custom webmail for all domains that belong to a particular subscription or hosting plan:

   • (Subscription) Go to Subscriptions > subscription > click “Customize” in the right sidebar > the “Permissions” tab and then deny the “Custom Webmail” permission.
   • (Hosting plan) Go to Service plans > hosting plan > the “Permissions” tab and then deny the “Custom Webmail” permission.

Generating Webmail Configuration

To work correctly, all webmail clients need some web server configuration. To configure webmail, use the getWebmailApacheConfig and getWebmailNginxConfig methods of the pm_Hook_WebServer class. See this topic for details.

The getWebmailApacheConfig and getWebmailNginxConfig methods will receive the \pm_Domain object as the first parameter and a string webmail type as the second parameter. You can generate configuration based on the provided webmail type. For example, when it matches the webmail type you have registered using the \Plesk\SDK\Hook\Webmail hook:

class Modules_CustomMail_WebServer extends \pm_Hook_WebServer
{
    private Configuration $generator;

    <...>

    public function getWebmailApacheConfig(pm_Domain $domain, string $type): string
    {
        if ($type === 'custommail') {
            return $this->generator->getApacheConfiguration();
        }

        return '';
    }

    public function getWebmailNginxConfig(pm_Domain $domain, string $type): string
    {
        if ($type === 'custommail') {
            return $this->generator->getNginxConfiguration();
        }

        return '';
    }
}