# Email hosting

URL: https://docs.vaultpanel.net/guides/dns-and-email/email-hosting

> Host email for your domains on your own servers with Postfix, Dovecot and OpenDKIM, with mailboxes, forwarders, DKIM signing and the DNS records receivers check.

VaultPanel can host email for your domains on your own servers: mailboxes people read in any mail app, forwarders, and DKIM-signed outgoing mail. It sets up three standard programs from the system's packages:

| Program | Role |
| --- | --- |
| **Postfix** | Receives mail from the internet and sends mail for signed-in mailboxes. |
| **Dovecot** | Keeps the mailboxes, readable over IMAP and POP3 (TLS only). |
| **OpenDKIM** | Signs outgoing mail, so receivers can check it came from your server. |

Find email under **Web > Email**. Only staff see this page.

## How it works

- Each server that hosts email has one mail server, with a host name such as `mail.example.com` that mail apps and other mail servers connect to.
- Mailboxes are virtual: they are not Linux accounts, and Linux accounts cannot sign in to email. Mail is stored in `/var/mail/vhosts/<domain>/<name>/Maildir`, owned by one `vmail` account.
- The panel keeps the domains, mailboxes and forwarders. Each change sends the server's whole set to the agent, with password hashes only, never passwords. The agent checks them again and rewrites Postfix's tables, Dovecot's user list and OpenDKIM's keys from them.
- Only signed-in mailboxes can send through the server, so it is not an open relay.

## Before you start

- **A host name for the mail server**, such as `mail.example.com`, with an `A` record pointing at the server. When VaultPanel runs that domain's DNS, it adds the address for you.
- **Port 25 open** at your hosting provider. Some providers block it on new servers; without it, mail neither arrives nor leaves.
- **Reverse DNS**: set the PTR record of the server's IP address to the mail host name in your hosting provider's control panel. Many receivers refuse mail from servers whose address does not point back at their name.
- **An up-to-date agent.** The panel refuses to set up email on a server whose agent is too old to host it.

## Set up a mail server

### Open the Mail servers card

Go to **Web > Email**. The **Mail servers** card lists your servers.

### Set up email

Click **Set up email** next to the server, enter the **Mail host name**, and confirm.

The agent installs Postfix, Dovecot and OpenDKIM. With the firewall on, it opens ports 25, 465, 587, 993 and 995. The server then shows **Running**.

**Check DNS** on the card shows whether the **Host name** points at the server and whether the server's address points back at it (**Reverse DNS**).

### The mail server's certificate

The mail server needs a certificate for its host name. The card shows which one it uses:

- **Let's Encrypt**: a Let's Encrypt certificate for the host name was found on the server under `/etc/letsencrypt/live/<host name>/`. The mail server reloads after Certbot renews it.
- **Own certificate**: none was found, so the agent made its own (valid 10 years). Mail apps warn about it once.

After a certificate for the host name is on the server, click **Set up again** to use it.

## Add a domain

Click **New domain** and fill in:

| Field | Notes |
| --- | --- |
| **Domain** | Such as `example.com`. |
| **Mail server** | One of your servers with email set up. |
| **Add its records to the DNS zone** | On by default. When VaultPanel runs the domain's DNS, it adds the MX, SPF, DKIM and DMARC records. They replace the domain's current MX and SPF records, so its mail comes here. Shown with the `dns.manage` permission. |

Click **Add domain**. The domain shows **Adding** until the server has made its DKIM signing key, then **Active**.

## Mailboxes

On the domain's **Mailboxes** tab, click **New mailbox**:

| Field | Notes |
| --- | --- |
| **Address** | The part before the `@`, such as `info` or `first.last`: lowercase letters, digits, dots, dashes, plus and underscores. |
| **Name** | For you; mail apps set the sender name themselves. |
| **Size limit (MB)** | Default 1,024 MB. `0` for no limit. |
| **Password** | At least 10 characters. Leave it empty to get a generated one. |

Click **Add mailbox**.

> **Important:**
A generated password is shown once: VaultPanel keeps only a hash of it. If it gets lost, set a new one from the mailbox's edit button.

Edit a mailbox to change its name, size limit or password. Untick **Mailbox is on** to stop it signing in: it still receives mail, but nobody can read it or send from it. **Check sizes** asks the server how much mail each mailbox holds.

When you delete a mailbox, mail sent to it afterwards is refused. Tick **Also delete the mail stored in it** to remove its folder from the server; otherwise the mail stays and comes back if you add the mailbox again.

## Forwarders

A forwarder is an address without a mailbox of its own, such as `hello@` for a team. On the **Forwarders** tab, click **New forwarder**, enter the address and, under **Send to**, up to 20 addresses (one per line), on this server or anywhere else.

> **Note:**
Some providers file forwarded mail as spam when it fails their checks. Forward to mailboxes on your own server where you can.

## DNS records

Other mail servers trust your mail only when the domain's DNS has the right records. The domain's **DNS records** tab lists them:

| Record | Name | Value |
| --- | --- | --- |
| MX | `@` | The mail host name, priority 10. Mail for the domain goes there. |
| SPF (`TXT`) | `@` | `v=spf1 mx ~all`, or `v=spf1 mx a:<host name> ~all` when the host name is outside the domain. Only your mail server may send for the domain. |
| DKIM (`TXT`) | `vaultpanel._domainkey` | `v=DKIM1; k=rsa; p=<public key>`. Shown once the server has made the domain's signing key. |
| DMARC (`TXT`) | `_dmarc` | `v=DMARC1; p=none`: receivers report mail that fails both checks, without rejecting it to start with. |

- **When VaultPanel runs the domain's DNS**, the tab links the zone, and **Add to the zone** adds any missing records. A new SPF, DKIM or DMARC record replaces the old one instead of being added next to it.
- **When the DNS is elsewhere**, copy the records to where the domain's DNS is hosted (often the registrar).

**Check public DNS** shows each record as **In place**, **Different**, **Missing** or **Add where your DNS is**. Changes can take up to the records' TTL to show.

## Connect a mail app

The domain's **Mail apps** tab has the settings for Outlook, Apple Mail, Thunderbird and phone mail apps. Choose IMAP and enter them by hand:

| | Protocol | Server | Port | Security |
| --- | --- | --- | --- | --- |
| Incoming | IMAP | The mail host name | 993 | SSL/TLS |
| Incoming | POP3 | The mail host name | 995 | SSL/TLS |
| Outgoing | SMTP | The mail host name | 587 | STARTTLS |
| Outgoing | SMTP | The mail host name | 465 | SSL/TLS |

The user name is the full email address and the password is the mailbox's password, for incoming and outgoing mail.

## Remove a domain

Removing a domain removes its mailboxes and forwarders, and the server refuses mail for it. Tick **Also delete all the mail stored for it** to delete the stored mail too. The domain's DNS records stay: change its MX record if its mail should go somewhere else.

## Troubleshooting

- **Mail from outside never arrives.** Check that port 25 is open at your provider and that the domain's MX record points at the mail host name. On the server, `ss -ltn` lists Postfix listening on port 25.
- **Gmail or Outlook refuse or flag your mail.** Check the DNS records with **Check public DNS** and set the server's reverse DNS to the mail host name.
- **Mail apps warn about the certificate.** The mail server uses its own certificate. See [The mail server's certificate](https://docs.vaultpanel.net/guides/dns-and-email/email-hosting#the-mail-servers-certificate).
- **The last change did not reach the mail server.** Click **Details** to read the operation log, then **Apply again** on the **Mail servers** card to send the server's settings again.

To test a mailbox from the server:

```bash
doveadm auth test info@example.com 'the password'
```

## Permissions

| Permission | Allows |
| --- | --- |
| `mail.read` | Seeing mail servers, domains, mailboxes and forwarders. |
| `mail.manage` | Setting up mail servers and changing domains, mailboxes and forwarders. |

Hosting customers do not see email hosting.
