Setting up mail in OpenBSD

2026-08-13T00:45:36Z

Being able to send email from your terminal is important if you plan to join the OpenBSD community. One of the first things you'll see after an install is a message saying that you've got mail, and inside will be a handy message about how to setup your machine. At the end you'll see the following:

If you wish to ensure that OpenBSD runs better on your machines, please do us a favor (after you have your mail system configured!) and type something like:

# (dmesg; sysctl hw.sensors) | \
   mail -s "Your System Description" dmesg@openbsd.org

so that we can see what kinds of configurations people are running.

But how do we get that pesky mail system configured? Reading the man pages for smtpd(8) and mail(1) will get you there, but here is a condensed version. Note that this only configures outgoing mail, which is all you really need. This allows you to send output from dmesg(8), terminal output when asking about problems, or even send patches you've built straight through email!

First, get your smtp credentials from your email provider. Once you have that, use su to become the root user. Create the file /etc/mail/secrets and add the following:

identifier my@email.com:MySecretKey

Change identifier to whatever you want, this will be your secret's identifier name. Adjust the email address and your smtp auth key in place of MySecretKey

This secrets file needs specific permissions, so let's do a little chown/chmod magic

$ chown root:_smtpd /etc/mail/secrets
$ chmod 640 /etc/mail/secrets

Next, configure smtpd(8) for outbound mail. You'll start by modifying /etc/mail/smtpd.conf to look something similar to the following:

table aliases file:/etc/mail/aliases
table secrets file:/etc/mail/secrets

listen on socket
listen on lo0

action "local_mail" mbox alias <aliases>
action "relay" relay host smtp+tls://identifier@smtp.email.com:587 auth <secrets>

match from local for local action "local_mail"
match from local for any action "relay"

The important parts here are adding the line table secrets file:/etc/mail/secrets at the top to import our secrets table and replacing the pre-defined outbound configuration with a relay to our email provider's smtp server. The smtp address will need to match the identifier name you set in /etc/mail/secrets, so if your secrets file said something like iambob bob@gmail.com:12345, then your smtp address would look something like smtp+tls://iambob@smtp.gmail.com:587 auth <secrets>.

The standard port for smtp is 587, so odds are your email provider is using that. Doublecheck to be safe.

Now you can check that your config is correct and get things started up

# Checks your config for errors
$ smtpd -n

# Restart smtpd
$ rcctl restart smtpd

One last step before we're done: A quick Ctrl+D to drop back to your regular user account, and open up ~/.mailrc using your text editor of choice. Add the following line at the bottom of the file. This will set the FROM header of your emails properly, without it mail(1) will put your username and hostname as the
sender, which will break smtp authentication.

set from="my@email.com"

You should be good to go at this point. Test it out by sending yourself a quick test email.

echo foo | mail -s bar my@email.com

Even better, send your system info to the OpenBSD developer team! Be sure to set the email's subject line to some information about your computer. Here's the invocation I used on my latest workstation build

(dmesg; sysctl hw.sensors) | mail -s "Gigabyte B650M K, Ryzen 7 7700X, RX 6750XT. Had to disable Re-Size BAR Support for amdgpu to init" dmesg@openbsd.org

If you run into any issues, look at /var/log/maillog. The entire flow of your mail getting sent out will be logged there, and you should be able to discern what is wrong.

burkey.co blog

Setting up mail in OpenBSD