KoaPanel
IT Try it free
All manual sections

DocumentationMail

Mail

The panel includes an optional mail service: mailboxes on your sites' domains, forwarders, autoresponder, antispam, DKIM signing and a webmail opened from the panel with one click. Under the hood: Postfix (receives and sends), Dovecot (keeps the mailboxes, IMAP and POP3), Rspamd (antispam and DKIM signing, with a small private Redis) and two webmails: Roundcube (the default one) and SnappyMail.

Enabling mail

Only the administrator enables the service. While it is off, the Mail page says "Mail isn't enabled on this server": the administrator enables it with one click with Enable mail (using the suggested name), while users and resellers are told to ask their administrator. To choose the name and see the checks first, use Mail › Mail server (or "Settings and checks"). Before enabling it the panel runs a few checks and explains them plainly:

  • Outbound port 25: many cloud providers (Vultr, Hetzner, AWS, Google Cloud) block it. With the port closed the server receives mail but cannot deliver it to other servers: you need an SMTP relay (see below) or the provider to open it.
  • Reverse DNS (PTR) of the server address: it must return the mail server name (e.g. mail.yourdomain.com). If it is different, Gmail and Outlook treat your messages as suspicious.
  • Mail server name: it must point to the server address (A record).
  • Blacklists (Spamhaus, Barracuda, SpamCop): a listed address gets its outgoing messages refused. Spamhaus does not respond public DNS: the check then shows "cannot be checked", which is normal.
  • Memory: mail works on a 2 GB server, with Rspamd in lean mode (about 150-250 MB for all mail services).

Choose the mail server name (the panel suggests mail.<server name>), decide whether to enable POP3 too and press Enable mail. It takes a few minutes and does not touch the sites. The panel opens ports 25, 465, 587, 993 (and 995 with POP3) plus the webmail port, and enables fail2ban protection for mail and IMAP.

From the command line: sudo panel-agent setup mail -hostname mail.yourdomain.com. Panel upgrades refresh the configuration only when the service is active.

Outgoing mail: direct or relay

In Server › Mail › Outgoing mail choose how messages leave for other servers:

  • Direct delivery (port 25): the server delivers itself. The provider must not block outgoing port 25 and the reverse DNS (PTR) of the server address must equal the mail hostname. Run diagnostics tests port 25 to Gmail and Outlook, checks the PTR (IPv6 too) and that the name resolves back to the address, detects the provider and explains what to do. Send over IPv4 only avoids rejections when the IPv6 address has no PTR.
  • Relay (smarthost): messages go through a sending service. Pick the service (Brevo, Mailgun, Amazon SES, SMTP2GO, Postmark, SendGrid or another): server, port and SPF include are filled in, you enter the service's username and password. The connection is always encrypted and the password is readable only by root on the server. Some services also ask you to authenticate the domain in their dashboard.

The SPF record suggested for the domains follows the mode: with a relay it contains the service's include, with direct delivery the server address. If a mode change fails, the previous one comes back; after the change the queue restarts at once. The Mail page warns the administrator when sending has a problem.

Send test email sends a message with the mode in use and shows the answer of the recipient's server (or the relay): delivered, deferred or rejected, with the reason. With a relay, use a sender authorized in the service.

Mail forwarded to external addresses leaves with a rewritten sender (SRS), so it is not dropped because of the original sender's SPF.

Message queue

The message queue (administrators) shows the messages the server hasn't delivered yet, with every recipient and why they're waiting. Retry now resends them all at once, Delete waiting messages removes them.

You can also work on one message at a time:

  • search by sender, recipient or ID and filter by state (waiting to retry, being sent, on hold);
  • Headers shows the sender, the subject and the other headers of the message (never its text);
  • Retry now resends that message only; Hold keeps it in the queue without sending it (for example while you check an account that sends spam) and Release sends it again;
  • the bin icon deletes it: it isn't delivered and the sender gets no notice.

Select several messages with the boxes to do it on all of them together.

Delivery log

The delivery log tells what happened to each email: delivered, waiting (the server retries), bounced (the recipient's server refused it, for example because the mailbox doesn't exist), expired (returned to the sender after days of attempts) or refused on arrival (for example by a block list or the spam filter). Next to it are the server's answer and the server it was delivered to.

  • Whoever manages a domain finds it in the domain's Deliveries tab: they see only the emails sent and received by that domain.
  • Administrators also find it on the Mail page, for every domain on the server.

Search an address, filter by status and choose the period: from the last hour to the last 7 days.

Reverse DNS (PTR)

The PTR is set in the server provider's panel, not in the domain's DNS:

  • Vultr: instance › Settings › IPv4 › Reverse DNS. Port 25 is unblocked with a support ticket.
  • Hetzner: Cloud Console › server › Networking › Edit reverse DNS. Port 25 is unblocked after the first month, from Limits.
  • OVHcloud: customer area › Network › IP › Modify the reverse path.

On Vultr and Hetzner Cloud you can do it from the panel: paste the provider's API key in Set the reverse DNS with the API and the panel sets the PTR to the mail hostname and checks it. The key is kept (encrypted) only if you ask and is never shown.

Outgoing IP per domain

If the server has several IP addresses (IPv4 or IPv6), in Server › Mail › Outgoing IPs choose which ones mail may leave from, which one to use normally (Default) and, if you like, a HELO name per address (empty: the mail hostname). Then, in Mail › domain › Settings, each domain can use one of the allowed addresses. Administrators choose it.

  • Mail sent by the domain's mailboxes (SMTP, webmail) and by its PHP sites leaves from the domain's address: both with a sender of the domain and with the site's default sender.
  • Forwarded mail (rewritten by SRS in the server's name) and bounces leave from the default address. DKIM signing doesn't change.
  • An IPv4 address sends over IPv4 only; an IPv6 address sends over IPv6 and uses the default IPv4 towards servers without IPv6. With Send over IPv4 only IPv6 addresses can't be chosen.
  • With a relay all mail leaves through the relay: the addresses apply when you go back to direct delivery.
  • SPF: if the panel manages the domain's DNS, the address is added to the SPF record (its other mechanisms stay); otherwise the panel shows the record to set.
  • Reverse DNS: each address must have its HELO name as PTR, and that name must point to the address. The panel checks it and, if it is missing, tells you the exact value to ask your provider for (saving is never blocked).

When migrating from cPanel over SSH the panel reads /etc/mailips and /etc/mailhelo: a domain that left from an address this server also has keeps it; otherwise it uses the default and the report says so. The same applies to Move account between KoaPanel servers.

Certificate

Until the mail server name points to the server, mail uses a self-signed certificate: webmail works, mail apps show a warning. Once the name points here and port 80 is reachable, press Request a Let's Encrypt certificate: it renews by itself.

Mail on another server

The mail of an account can live on one of the linked servers instead of here, like cPanel's mail nodes: for example a server dedicated to the mail of every site. Both servers need panel 0.79 or later, and the mail server needs the mail installed.

  • Who decides: the administrator, in the account window (Accounts, click the name), under Mail server: This server or one of the linked servers, then Apply.
  • What happens on the mail server: the panel creates an account with the same name and the account's sites (empty: no files or database, they exist only for the mail, aliases included), and turns the mail on for the domains that already had it here. Sites created later get there automatically; sites deleted here are removed there too.
  • DNS: if the domains' DNS is on this panel, MX, SPF, DKIM and autoconfig are taken from the mail server and published automatically, with this server's addresses added to the SPF (the sites keep sending their own mail from here). Otherwise the account's Mail page shows them, to copy to the DNS provider. They are read again every 15 minutes, or right away with Refresh the records.
  • For the user: the Mail page says where the mail is, and Open the mail on … goes straight into the mail server, with no other password, in a section limited to the mail (mailboxes, forwarders, autoresponders, antispam, webmail).
  • Suspension and deletion: suspending the account here suspends it on the mail server too; deleting it also deletes the account and the mail kept there.
  • Limits: existing mailboxes are not moved. An account with mailboxes or forwarders here cannot move to another server (move them first, for example with a mail-only migration), and to bring the mail back here the mail server must have none left.

Enabling mail on a domain

In Mail press Enable mail on a domain and choose a site's domain (or one of its aliases). The panel creates the domain's DKIM key (2048 bits) right away and takes you to the DNS records to publish. Resellers manage their accounts' mail, users their own sites'.

Mailboxes

New mailbox: choose address, space and password: Generate a strong password (you see it only once, with a copy button) or I'll choose it. For each mailbox you see the space used and the number of messages, and you can:

  • change the password (open sessions in mail apps are closed);
  • change the space and set forwarding to other addresses, keeping a copy or not;
  • disable it: it keeps receiving mail but nobody can sign in;
  • add simple filters (move to a folder, forward, delete) by sender, recipient or subject;
  • delete it with all its messages.

A mailbox over 75% and 90% of its space gets a notice; when it is full, new messages are refused. Messages recognized as spam go to the Spam (Junk) folder.

Packages can limit mail domains, number of mailboxes, default and maximum space of a mailbox; resellers' quotas can limit the mailboxes of all their accounts.

Forwarders and aliases

In the Forwarders tab you create addresses without a mailbox that pass mail on to one or more addresses, external ones too (e.g. sales@ → mario@ and anna@). The target mailboxes can also send as the forwarder's address. The catch-all receives mail for the domain's non-existent addresses: it is off by default because it attracts a lot of spam.

Note: mail forwarded to external addresses leaves with a rewritten sender (SRS, see above), so it is not refused because of the original sender's SPF. The message's DKIM signature stays intact, so it passes DMARC checks too.

Autoresponder

Autoresponder on a mailbox: subject, text, optional start and end dates and how often to answer the same sender. It never answers automatic messages or mailing lists.

Antispam of the domain

In the Antispam tab of a mail domain, whoever manages it decides how incoming emails are filtered:

  • Strictness: off, low, normal (the server's value) or high. The higher it is, the more doubtful emails go to spam.
  • Spam folder: spam usually goes to the Spam folder; otherwise it stays in the inbox with "[SPAM]" in the subject.
  • Senders always accepted: addresses or domains (one per line) whose emails never end up in spam.
  • Senders always refused: addresses or domains whose emails are refused on arrival.

The settings apply to every mailbox of the domain, from the next incoming emails.

Mail DNS: MX, SPF, DKIM and DMARC

The Mail DNS tab shows the records to publish, with copy buttons, and checks what public DNS sees:

  • MX: the domain receives mail on this server;
  • SPF (v=spf1 mx a ip4:… ~all): this server may send for the domain;
  • DKIM (panel._domainkey): the public key that verifies the message signatures;
  • DMARC (_dmarc): starts in monitoring mode (p=none); once everything works you can move to quarantine or reject;
  • autoconfig and autodiscover (optional): automatic setup of Thunderbird and Outlook.

If the domain is on a connected Cloudflare or 1PrimeCDN account, Set up mail DNS shows the changes and then publishes them: an MX of another provider is replaced, an existing DMARC policy is never touched.

Webmail

Webmail next to a mailbox opens the mail in the browser without asking for the password: the link is valid 60 seconds and works once. The panel never uses the mailbox password nor a "master" password shared by all mailboxes: it creates a temporary access valid only for that mailbox, for a few hours.

Mailbox users can also log into the webmail on their own (address https://<server>:8445/) with the full address and password. The sign-in page shows the panel's name and colours. From Roundcube they can also change their own password (Settings › Password): the current one is required.

Two webmails are installed on the server: Roundcube (default: modern and complete) and SnappyMail (light). The administrator chooses the default one in Server › Mail › Webmail: it is the one the Webmail button and the address https://<server>:8445/ open. The other one stays at hand: from a mailbox's ··· menu, Open with SnappyMail (or Open with Roundcube). The direct addresses are https://<server>:8445/roundcube/ and https://<server>:8445/snappymail/.

Filters and autoresponder are set from the panel (the server applies them even with the webmail closed).

Mail apps

The Mail apps tab lists server, ports and security for Outlook, Thunderbird, Apple Mail and phones:

  • incoming IMAP port 993 SSL/TLS (and POP3 995 when enabled);
  • outgoing SMTP port 465 SSL/TLS or 587 STARTTLS, with authentication;
  • user name: the full address.

You can only send as your own addresses (and the forwarders that deliver to the mailbox), only after signing in and only over an encrypted connection; each mailbox has a messages-per-hour limit (Mail server › Settings) that stops hacked accounts.

Mail backup

Site backups also save the mailboxes of the site's domains, with messages, passwords, forwarders and settings. From the site's Backup tab you can restore all the mail or a single mailbox: missing messages come back without touching or duplicating the ones already there, and a deleted mailbox is created again with its old password.

Mailbox migration

The migration imports mailboxes too, when the mail service is active:

  • cPanel backups (and cPanel over SSH as root): mailboxes are created with all their messages and their original password (cPanel keeps SHA512-CRYPT or MD5-CRYPT hashes, which the server verifies as they are), keeping the space they had;
  • Plesk backups: mailboxes are created; when the password in the backup is encrypted with the old server's key, the panel generates a new one and shows it in the summary, only once.

If mail is off when you migrate, the analysis says so and the administrator can choose Enable mail and import the mailboxes: the service is installed during the import, before the mailboxes. If the mailboxes were already skipped (a migration done with mail off), enable mail, open the migration details in Migration and click Import skipped mailboxes: mailboxes and forwarders come from the same backup, without touching sites, files and databases. If the backup file is gone, or the migration was over SSH, run the migration again and choose Mailboxes only.

After the migration publish the domain's MX, SPF and DKIM records (Mail DNS tab) to receive mail here. A live migration from a generic Linux server does not copy mailboxes: recreate them and use a mail app to move the messages.