mailssl
Get a free Let's Encrypt certificate for the server's mail hostname (SMTP and IMAP), renew it when 7 days or fewer remain, and rebuild the mail maps
- Command:
/go/mailssl - Category: Mail
- Required options: None
- Output: Progress messages, and an error message if the certificate can't be installed
- Log:
/var/log/go/mailssl.log - Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
Mail programs such as Outlook and Thunderbird connect to your server over an encrypted connection and check its SSL certificate. /go/mailssl makes sure the server's mail hostname has a valid certificate. It:
- creates a self-signed fallback certificate for Postfix in
/etc/postfix/ssl(every run) - checks the Let's Encrypt certificate for the server hostname, and removes it if 7 days or fewer remain so that a new one is issued
- requests a new Let's Encrypt certificate if none exists (or with
--force), covering the server hostname and, if it is different, the IMAP hostname - rebuilds the mail maps with
vmailwhen the server hosts any accounts
The server hostname must be a full name with at least two dots, such as mail.example.com. Otherwise no certificate is requested.
Certificates for your customers' own domains are handled by ssl and checkssl, not by this command.
Quick start
# Install the certificate, or renew it if it is close to expiry
/go/mailssl
# Replace the existing certificate now
/go/mailssl --force
Syntax
/go/mailssl [--force]
| Form | Behavior |
|---|---|
/go/mailssl |
Requests a certificate only if there is none, or if the existing one has 7 days or fewer left. |
/go/mailssl --force |
Deletes the existing certificate and requests a new one, even if the current one is valid. |
Options
| Option | Required | Notes |
|---|---|---|
--force |
No | Reissue the certificate regardless of how long the current one is valid. Let's Encrypt limits how many certificates can be issued for the same names in a week, so don't use it repeatedly. |
Any other argument is ignored.
Output
All certificate messages come from this command. The certificate tool itself runs quietly.
| Situation | Message |
|---|---|
| Server and IMAP hostname are the same | Installing SSL Certificates on SMTP/IMAP Server Hostname <hostname>... |
| Two different hostnames | Installing SSL Certificates on SMTP/IMAP Server Hostname (<hostname> and <imap-hostname>)... |
| It worked | SSL Certificate Installed Successfully for Hostname (<hostname> - 3 Months)... (or (<hostname> and <imap-hostname> - 3 Months)) |
| It failed | Error: Can not Install SSL Certificate for Hostname (<hostname>)... (or with both names) |
| Nothing to do | No output. |
After an attempt, a line of dashes is printed.
The exit status doesn't show whether the certificate was installed. Read the message instead.
Examples
# Install or renew the mail certificate
/go/mailssl
# Replace the certificate now
/go/mailssl --force
# Check the certificate that was issued
certbot certificates -d "$(cat /etc/hostname)"
# Check that the mail ports present a valid certificate
/go/checkmail
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Nothing is printed | The certificate exists and has more than 7 days left, or the hostname (or IMAP hostname) has fewer than two dots. | Check cat /etc/hostname. Set a full hostname with hostname. Use --force to reissue. |
Error: Can not Install SSL Certificate... |
Let's Encrypt couldn't verify the hostname. Common reasons: the hostname doesn't point to this server, port 80 is blocked, the web server isn't running, or a rate limit was reached. | Check DNS and the firewall with checkfirewall. Read /var/log/letsencrypt/letsencrypt.log. |
| After an error, no Let's Encrypt certificate exists any more | The old certificate is deleted before the new one is requested. See Known limitations. | Fix the cause, then run /go/mailssl again. |
| Mail programs warn about an untrusted certificate | The server is using the self-signed fallback because the Let's Encrypt certificate is missing. | Run /go/mailssl, then checkmail. |
[: =: unary operator expected appears at the start |
The imap. hostname has no DNS record yet. |
Harmless. Add the DNS record if you want a separate IMAP hostname. |
--force fails after a few runs |
Let's Encrypt's rate limit for the same names. | Wait before trying again. |
| Reissue fails right after the old certificate was removed | The hostname (and not the IMAP name) resolves to this server, but the IMAP name doesn't. | Fix the DNS record of the IMAP hostname, or remove /etc/imap. |
Details
Which hostnames are covered
| Item | How it is chosen |
|---|---|
| Server hostname | The contents of /etc/hostname. |
| IMAP hostname | The contents of /etc/imap if that file exists, otherwise the server hostname. |
/etc/imap is written automatically |
If the hostname starts with smtp., the command changes it to imap.. When the DNS record of that imap. name points to this server, it is saved in /etc/imap. Otherwise the server hostname is saved. |
If the two names are different, one certificate is issued for both, with the server hostname as the certificate name.
How it works
flowchart TD
A["mailssl [--force]"] --> B["Find IMAP hostname"]
B --> C["Create self-signed fallback certificate"]
C --> D{"Let's Encrypt certificate exists?"}
D -- "Yes" --> E{"7 days or fewer left?"}
E -- "Yes" --> F["Delete it"]
E -- "No" --> G{"--force?"}
D -- "No" --> H
F --> H{"Hostnames have 2+ dots?"}
G -- "Yes" --> H
G -- "No" --> L
H -- "No" --> L
H -- "Yes" --> I["Request certificate with certbot"]
I --> J{"Issued?"}
J -- "Yes" --> K["Print success, run go and reload"]
J -- "No" --> M["Print error"]
K --> L{"Any hosted accounts?"}
M --> L
L -- "Yes" --> N["Run vmail"]
L -- "No" --> O["Done"]
- Logs the call to
/var/log/go/mailssl.log. - Reads the web server type, finds this server's public IP, reads the hostname, and counts the hosted accounts.
- If the hostname starts with
smtp., decides whetherimap.<name>points to this server and writes/etc/imap. - Works out the IMAP hostname and counts the dots in both names.
- Creates the self-signed fallback certificate in
/etc/postfix/ssl. - Chooses the certbot plugin:
--nginxon Nginx servers,--apacheotherwise. - If a Let's Encrypt certificate for the hostname exists and has 7 days or fewer left, removes
/etc/letsencrypt/live/<hostname>(and the IMAP hostname's folder), then runs/go/go. - If the certificate is missing (or
--forcewas given), and both names have at least two dots: deletes any old certificate with that name, requests a new one, and checks that it was issued. - On success, runs
/go/goandreload. - If the server hosts any accounts, runs
vmail.
Files used
| File | Purpose |
|---|---|
/etc/hostname |
The server hostname. |
/etc/imap |
The IMAP hostname, if different. Written by this command for smtp. hostnames. |
/etc/letsencrypt/live/<hostname>/ |
The Let's Encrypt certificate. |
/etc/postfix/ssl/smtpd.key, smtpd.csr, smtpd.crt |
The self-signed fallback key, request, and certificate, valid for 365 days. |
/etc/postfix/ssl/cakey.pem, cacert.pem |
A self-signed certificate authority key and certificate, valid for 365 days. |
/usr/local/goadmio/linux/ws.db |
The web server type (Nginx or Apache). |
/var/log/go/mailssl.log |
A log of each call. |
The Let's Encrypt registration email is info@<hostname>. Expiry notices go there.
Requirements
- The hostname has at least two dots.
- The hostname, and the IMAP hostname if it is different, point to this server in DNS.
- The web server is running and reachable on port 80, so that Let's Encrypt can verify the name.
certbotis installed.
Known limitations
- The old certificate is deleted before the new one is requested. If the request fails, the server has no valid Let's Encrypt certificate until you fix the problem and run the command again. The self-signed fallback keeps mail working, but mail programs will show a warning.
- A 7-day renewal window. The certificate is replaced only when 7 days or fewer remain, and if the command isn't run in that window, the certificate can expire.
- The fallback certificate is weak. It is regenerated on every run, with a 1024-bit key, a fixed passphrase, and placeholder details (
My Company Name LTD., countryEG). - The certbot output is hidden, so the real reason for a failure isn't shown. Check
/var/log/letsencrypt/letsencrypt.log. - The wildcard in the
certbot deletefor old numbered certificates doesn't match anything that certbot understands, so numbered duplicates remain. - Unused code. The
ROOTDomainfunction and theOSandSSLExpiresOnvariables aren't used. /go/goisn't in the command index. It is an internal helper that runs after a certificate changes.- "3 Months" is a fixed message, not read from the certificate.
See also
| Command | Description |
|---|---|
checkmail |
Test whether outbound mail port 25 works, and whether the SMTP (465) and IMAP (993) SSL certificates are installed |
checkimap |
Check the IMAP hostname, its DNS record, and the SSL certificate on port 993, and repair the mail SSL setup |
doveconf |
Rebuild the Dovecot configuration, including SSL certificates for the hostname and each domain |
vmail |
Rebuild the Postfix/Dovecot vmail maps |
installmail |
Install and configure webmail services (Postfix and Dovecot) |
hostname |
Change the server hostname and set up GoAdmio, mail, and SSL for it |
ssl |
Install an SSL certificate for a domain in GoAdmio |
checkssl |
Audit SSL certificates for all hosted domains, renew those close to expiry, and send expiry alerts |