Skip to content

07 — Email Relay (msmtp + Gmail)

msmtp is a small SMTP client used as a sendmail replacement. It lets the Z2 send outbound email through Gmail's SMTP servers — used by smartd for drive health alerts and any other service that needs to send mail.

Why route through Gmail

Major mail providers block messages from residential IPs to fight spam. Sending email directly from a home server to recipients almost always lands in junk folders or gets rejected. Routing through Gmail's SMTP relay (with proper authentication) bypasses this — Gmail trusts itself.

Prerequisites

Before configuring msmtp, you need:

  1. A Gmail account with 2-Factor Authentication enabled
  2. An app password generated for SMTP access

To generate an app password:

  1. Go to https://myaccount.google.com/apppasswords
  2. Create a new app password named "Z2 Mini smartd" (or similar)
  3. Copy the 16-character password — you only see it once

Installation

sudo apt install -y msmtp msmtp-mta mailutils

What each provides:

  • msmtp — the SMTP client
  • msmtp-mta — symlinks /usr/sbin/sendmail to msmtp, so other programs (smartd, cron) use it transparently
  • mailutils — provides the mail command for testing

When prompted whether to enable AppArmor support, say Yes. (Important — see "AppArmor configuration" below.)

Configuration file

File: /etc/msmtprc

defaults
auth           on
tls            on
tls_starttls   on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile        /var/log/msmtp.log

account        gmail
host           smtp.gmail.com
port           587
from           gabrielgabrie99@gmail.com
user           gabrielgabrie99@gmail.com
password       <16-character-app-password>

account default : gmail

Lock down permissions (the file contains your password):

sudo chmod 600 /etc/msmtprc
sudo chown root:root /etc/msmtprc

AppArmor configuration

Ubuntu's AppArmor security framework restricts what msmtp is allowed to do, even when running as root. The default profile doesn't allow writing to /var/log/msmtp.log, so we need a local override.

File: /etc/apparmor.d/local/usr.bin.msmtp

/var/log/msmtp.log rwk,

The rwk permissions are: read, write, lock. All three are needed for msmtp to write logs.

Reload the profile after creating/editing:

sudo apparmor_parser -r /etc/apparmor.d/usr.bin.msmtp

Create the log file

sudo touch /var/log/msmtp.log
sudo chown root:root /var/log/msmtp.log
sudo chmod 644 /var/log/msmtp.log

Log rotation

File: /etc/logrotate.d/msmtp

/var/log/msmtp.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
    create 0644 root root
}

Keeps 4 weeks of compressed history.

Testing

Send a test email through msmtp directly:

echo "test" | sudo msmtp gabrielgabrie99@gmail.com

Should arrive in your Gmail inbox within a few seconds. Check the log:

sudo cat /var/log/msmtp.log

You should see a successful entry showing the SMTP transaction.

To test from mail (which is what smartd uses internally via sendmail):

echo "test from mail command" | sudo mail -s "test subject" gabrielgabrie99@gmail.com

Note: when running as your normal user, msmtp can't read /etc/msmtprc (root-owned). Always test with sudo.

Troubleshooting

"cannot log to /var/log/msmtp.log: Permission denied"

AppArmor is blocking the write. Verify the profile:

sudo dmesg | grep -i "apparmor.*msmtp" | tail -10

Look for "DENIED" entries. Make sure /etc/apparmor.d/local/usr.bin.msmtp exists with rwk permissions and the profile has been reloaded.

"cannot lock (tried for 10 seconds): Permission denied"

You have rw but not k (lock) in your AppArmor override. Should be rwk, not rw,.

"authentication failed"

The Gmail app password is wrong, or the account isn't using 2FA. Generate a fresh app password and update /etc/msmtprc.

Connection timeouts

Network blocking outbound port 587. Verify with:

nc -zv smtp.gmail.com 587

If this fails, the network is the problem (rare on student housing, but possible). Tailscale doesn't help here — outbound SMTP needs to reach Gmail directly.

Verbose debug output:

echo "test" | sudo msmtp --debug gabrielgabrie99@gmail.com

Shows the entire SMTP conversation, including TLS handshake and any error responses from Gmail.

Password rotation

App passwords should be rotated periodically, especially if the password has been seen in logs, screenshots, or chat histories.

  1. Go to https://myaccount.google.com/apppasswords
  2. Revoke the existing one
  3. Generate a new one
  4. Update /etc/msmtprc with the new password
  5. Test: 
    echo "rotation test" | sudo msmtp gabrielgabrie99@gmail.com

Files and locations

Purpose Path
Main config /etc/msmtprc
AppArmor override /etc/apparmor.d/local/usr.bin.msmtp
Log /var/log/msmtp.log
Log rotation config /etc/logrotate.d/msmtp
sendmail symlink /usr/sbin/sendmail → /usr/bin/msmtp