Stalwart Email Setup

Stalwart1 is an all‑in‑one mail server built for JMAP2, the ultra‑modern email standard we should be using but the tech industry is cowardly and hella slow to move. Anyhoo! I recently setup a new mail server with Stalwart because updating my aging Mail‑in‑a‑Box3 instance was unappealing and I wanna use cool new things like JMAP. Running a mail server is never simple but you're not here for simplicity, you're here to experience the future and benefit from my learnings.

Let's jump in.

Prerequisites

super dope domain

radical web host that supports sending email

an email address you aren't worried taking offline for a bit

For me, I'm using pidge.email for my domain, Linode4 (you get $100 credit if you use my link) for my web hosting, and I used my chronver.org email for my first test. If you aren't switching mail servers, you've got it easy, just ignore that part.

Linode requires you to open a support ticket if you want to send email. No one wants to be labeled a spammy playground and they're no exception. Thankfully, I was approved the following morning.

In their welcome email, they suggest enabling rDNS (reverse DNS) to make deliverability easier. One of the mail server validators we'll use later in this post will check for this.

Installation

This part is actually pretty straightforward, just follow the tutorial5. There is actually a lot you could change for any reason: running on Windows or Docker, changing the backend database to SQLite or FoundationDB, whatever floats your boat.

After changing the password from the auto‑generated one, you need to reboot the server for it to take effect.

Setup

When I setup6 servers, Caddy7 is installed as part of that process so you'll need to install that if you haven't already. A major perk of it over nginx is the automated certs and minimal configuration. Here's my Caddyfile:

pidge.email {
root * /var/www/html
file_server
}

mta-sts.pidge.email, mail.pidge.email {
reverse_proxy 127.0.0.1:8080
}

A few notes here; the root path for your domain will be /usr/share/caddy by default (which'll show you Caddy's "it's working" screen with some tips on what to do next). The mta-sts subdomain is necessary for other mail servers to view you as legit and the mail subdomain is where the dashboard is (this is also what you'll input to your favorite mail app when you add accounts to it).

After running service caddy reload you won't need to add the 8080 port to your domain to access the Stalwart interface anymore, just use the domain. If you see an error, you'll need to run service caddy status and work through it.

Stalwart's docs have some tips on using8 Caddy but here's where it's lacking: it wants you to create cron jobs to copy the certs from Caddy to a directory within its scope but you need to do a few things first.

Create the certs folder the cron job expects to exist:

mkdir -p /opt/stalwart-mail/cert

MANUALLY copy Caddy's certificate to Stalwart and convert to PEM format (make sure you update mail.pidge.email to your own domain).

cat /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/mail.pidge.email/mail.pidge.email.crt > /opt/stalwart-mail/cert/mail.pidge.email.pem

Do the same for the private key to said certificate (again, making the necessary updates to your domain).

cat /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/mail.pidge.email/mail.pidge.email.key > /opt/stalwart-mail/cert/mail.pidge.email.priv.pem

Now we can setup those cron jobs!

# this command opens up the cron thingy
crontab -e

Paste these lines in (don't make me remind you about your domain again):

# caddy crt > pem
0 3 * * * cat /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/mail.pidge.email/mail.pidge.email.crt > /opt/stalwart-mail/cert/mail.pidge.email.pem

# caddy key > pem
0 3 * * * cat /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/mail.pidge.email/mail.pidge.email.key > /opt/stalwart-mail/cert/mail.pidge.email.priv.pem

These cron jobs will run at 3am every day.

Annoyances & Gotchas

Stalwart's sidebar is…confusing. Visually it's easy to get lost in it because there's no distinction of depth when you activate different sections, and trying to go back to another setting you saw before is an exercise in frustration.

Thankfully, there's a search box at the top of the page and you can generally get to where you wanna go quicker by using that instead.

I thought the "Fallback Administrator" was a different user account but it's the same user that you login as.

Whenever the sidebar trips you up and you just want to get back to the domain list, click the "Management" link at the bottom. If you don't see it, click "Maintenance" and then you'll see the "Management" link toggle into view.

There are a handful of features that are only available for the enterprise version, with no way to hide them. If I really wanted to, I could just compile a new binary without these features but this is a minor complaint. A dev's gotta eat!

Tips 'n Tricks

Stalwart wants you to add these TXT records to your mail server's DNS:

"v=spf1 a ra=postmaster -all" for mail.your.domain

"v=spf1 mx ra=postmaster -all" for your.domain`

According to MailHardener's SPF Validator9, you want to do "v=spf1 mx ~all" instead, for reasons10:

SPF 'hard' fail is no longer recommended. For domains using DMARC, SPF 'hard' fail does not offer any security benefits over softfail, but may cause deliverability issues, even with valid DKIM.

For domains I use my mail server for, I also add a TXT record for the www subdomain with "v=spf1 mx ~all". Note that I don't have an A record for www this just makes the validator happy and doesn't cost me anything, so why not?

Speaking of other domains, there's a CNAME record you'll want to change from what Stalwart recommends. Using my domains as examples, Stalwart wants mta-sts.inc.sh to be a CNAME pointing to mail.pidge.email when it should actually be an A record pointing to the IP address of inc.sh. Here's the relevant portion of my Caddyfile:

mta-sts.inc.sh, inc.sh {
root * /var/www/inc.sh
import common
}

Inside of /var/www/inc.sh is a .well-known directory containing a mta-sts.txt file.

But what if your site is a bit more fancy than regular degular HTML? Your Caddyfile needs a lil' bit more. Here's webb.page:

mta-sts.webb.page, webb.page {
handle_path /.well-known/* {
root * /var/www/html/.well-known
file_server
}

encode gzip
reverse_proxy localhost:6433
root * /var/www/html
}

My homepage is a fancy web app that handles it's own routing so the previous example wouldn't work. For my homepage, I handle the .well-known path first and then let the web app handle the rest of the routes.

Your MTA‑STS policy should be reachable and that's just not possible with a CNAME. Using a CNAME makes sense when the mail server and domain name are one and the same.

This MTA‑STS validator11 recommends a max_age of 28 days and the mode should be "enforce." By default, Stalwart's max_age is considerably less and the mode is "testing."

Here's the output when CURLing mta-sts.inc.sh:

curl -k https://mta-sts.inc.sh/.well-known/mta-sts.txt

# max_age: 2419200
# mode: enforce
# mx: mail.pidge.email
# version: STSv1

Changing Stalwart's defaults should work in the UI but I found better luck with modifying its config file at /opt/stalwart-mail/etc/config.toml. When you're done, you should run service stalwart-mail restart or reboot the server if the changes aren't sticking.

Speaking of which, might as well share my config (sans authentication):

certificate.default.cert = "%{file:/opt/stalwart-mail/cert/mail.pidge.email.pem}%"
certificate.default.default = true
certificate.default.private-key = "%{file:/opt/stalwart-mail/cert/mail.pidge.email.priv.pem}%"
directory.internal.store = "rocksdb"
directory.internal.type = "internal"
queue.outbound.tls.starttls = "require"
report.analysis.addresses = ["dmarc@*", "abuse@*"]
report.analysis.forward = true
report.analysis.store = "30d"
report.tls.aggregate.contact-info = "'postmaster@pidge.email'"
report.tls.aggregate.from-name = "'TLS Report'"
report.tls.aggregate.max-size = 26214400 # 25 mb
report.tls.aggregate.org-name = "'Pidge'"
report.tls.aggregate.send = "daily"
report.tls.aggregate.sign = "['rsa']"
server.hostname = "mail.pidge.email"
server.listener.http.bind = "[::]:8080"
server.listener.http.protocol = "http"
server.listener.https.bind = "[::]:443"
server.listener.https.protocol = "http"
server.listener.https.tls.implicit = true
server.listener.imap.bind = "[::]:143"
server.listener.imap.protocol = "imap"
server.listener.imaptls.bind = "[::]:993"
server.listener.imaptls.protocol = "imap"
server.listener.imaptls.tls.implicit = true
server.listener.pop3.bind = "[::]:110"
server.listener.pop3.protocol = "pop3"
server.listener.pop3s.bind = "[::]:995"
server.listener.pop3s.protocol = "pop3"
server.listener.pop3s.tls.implicit = true
server.listener.sieve.bind = "[::]:4190"
server.listener.sieve.protocol = "managesieve"
server.listener.smtp.bind = "[::]:25"
server.listener.smtp.protocol = "smtp"
server.listener.submission.bind = "[::]:587"
server.listener.submission.protocol = "smtp"
server.listener.submissions.bind = "[::]:465"
server.listener.submissions.protocol = "smtp"
server.listener.submissions.tls.implicit = true
server.max-connections = 8192
server.socket.backlog = 1024
server.socket.nodelay = true
server.socket.reuse-addr = true
server.socket.reuse-port = true
server.tls.certificate = "default"
session.mta-sts.max-age = "28d"
session.mta-sts.mode = "enforce"
storage.blob = "rocksdb"
storage.data = "rocksdb"
storage.directory = "internal"
storage.fts = "rocksdb"
storage.lookup = "rocksdb"
store.rocksdb.compression = "lz4"
store.rocksdb.path = "/opt/stalwart-mail/data"
store.rocksdb.type = "rocksdb"
tracer.log.ansi = false
tracer.log.enable = true
tracer.log.level = "info"
tracer.log.lossy = false
tracer.log.multiline = false
tracer.log.path = "/opt/stalwart-mail/logs"
tracer.log.prefix = "stalwart.log"
tracer.log.rotate = "daily"
tracer.log.type = "log"
webadmin.auto-update = true

Unfortunately, if you want your TOML to have headers/sections, they'll get inlined automatically when Stalwart reloads. Alas.

Bonus Points

If you check out the report.analysis.addresses part of the config, you'll see two email addresses you should setup for your mail server: dmarc@your.domain and abuse@your.domain. You should also setup postmaster@your.domain, and do the same for the rest of the domains you connect to your mail server. The final boss12 and final final boss13 of mail validators are tough.

Run your domains through these14 other15 validators16 too. The last one wants DNSSEC on your domains, which is a one‑click setup on Cloudflare. Thank goodness! In my previous life17 as a bright‑eyed domain registry operator, I dealt with DNSSEC a lot. It's a pain but more than wonderful when someone else makes it easy to be secure.

The neat thing about these postmaster@your.domain accounts is getting aggregate TLS and DMARC reports from your usual suspects (Amazon, Google, &c) but also from randos like me running their own mail servers (hello aperture-labs.org)!

Should this post reach Hacker News, ignore the grumps who last hosted an email server when Windows XP was the new hotness or think hosting your own email is a fruitless endeavor. I ran my previous email server for checks notes 10 YEARS?! Holy moly, where did the time go…this server upgrade needed to happen, haha!

FIN?

I hope this wasn't too rambly. When I self‑host things for the first time I keep an unsaved text file open for days and use it as a scratch pad of sorts, to make sense of later. This post is the result of that process.

One of my long‑standing backburner projects is a hosted email service called, "Pidge," (from one of my favorite Pokémon evolutions: Pidgey, Pigeotto, Pidgeot) and I registered pidge.email seven years ago. Might as well use it now!

Oh yeah, one last note; I use MailMate18 and when adding new accounts, you'll need to manually set "Mailbox Type" of your Trash folder to "Deleted Messages," otherwise when you delete things a new "Deleted Messages" folder will get created and that looks dumb.

Stalwart also gives you "Shared Folders"19 which is a neat feature of groups. Obviously this feature is suited for work/enterprise.

Much thanks to Maurus20 for spending years working on Stalwart, it's pretty sweet. I'll most likely be using this for another 10 years.

EDIT: Knew I'd remember something else as soon as I pushed this to my server! When creating new accounts in Stalwart, you should make "Login name" and "Email" be the same, it'll make things less confusing.

🕸️