Quick Guide: Setting Up msmtp for Sending Mail from the Command Linemsmtp is a lightweight SMTP client that forwards mail from the command line or an MUA (mail user agent) to an SMTP server. It’s commonly used as a send-only SMTP relay for tools like Mutt, Neomutt, mailx, and automated scripts. This guide covers installation, basic configuration, authentication methods (including OAuth2), TLS handling, integration with MUAs and scripts, common troubleshooting steps, and security recommendations.
What msmtp does and when to use it
msmtp acts like a simplified send-only SMTP client. Instead of running a full MTA (mail transfer agent) such as Postfix or Exim on a host, msmtp hands outgoing mail to an external SMTP server (for example, Gmail, Outlook, or a company SMTP relay). Use msmtp when you want:
- Simple outgoing mail from scripts or cron jobs.
- A lightweight relay for desktop MUAs (Mutt/Neomutt).
- To avoid running a full MTA on a developer machine, container, or server.
Installing msmtp
On popular Linux distributions and macOS you can install msmtp from package managers:
- Debian/Ubuntu:
sudo apt update sudo apt install msmtp msmtp-mta - Fedora:
sudo dnf install msmtp - Arch Linux:
sudo pacman -S msmtp - macOS (Homebrew):
brew install msmtp
msmtp-mta provides a symlinked sendmail-compatible binary (msmtpq or msmtp depending on package) so programs expecting /usr/sbin/sendmail can work without changes. Confirm which binary your system uses and adjust MTA settings if needed.
Basic configuration file layout
msmtp reads configuration from the following locations, in order (later files override earlier ones): system-wide /etc/msmtprc, user-specific ~/.msmtprc, and files specified via –file. A minimal user config file (chmod 600 ~/.msmtprc) looks like:
# ~/.msmtprc — minimal example defaults auth on tls on tls_trust_file /etc/ssl/certs/ca-certificates.crt account default host smtp.example.com port 587 from [email protected] user [email protected] passwordeval "pass show smtp/example.com" # avoid plaintext passwords Key settings:
- defaults: applies default options to all accounts.
- account NAME: defines an account block.
- host, port: SMTP server and port (587 for STARTTLS, 465 for implicit TLS, 25 for plain).
- auth: on/off for authentication.
- tls: enable STARTTLS/implicit TLS depending on port and tls_starttls setting.
- from: envelope sender (From header should be set in the message or by the MUA).
- user/password/passwordeval: credentials; prefer passwordeval to read from secure helpers or scripts.
Make sure ~/.msmtprc is readable only by you:
chmod 600 ~/.msmtprc Authentication methods
-
Plain password (not recommended)
password "mypassword" -
passwordeval (recommended)
- Use a secrets manager or password store (pass, gopass, 1Password CLI). Example with pass:
passwordeval "pass show email/smtp"
- OAuth2 (recommended for Gmail/Google Workspace)
- msmtp supports the OAuth2 “XOAUTH2” mechanism via the passwordeval option. You must obtain an OAuth2 access token (and refresh it) using a helper script or utility. Example flow:
- Use a script to request tokens from Google using client_id/client_secret and refresh token.
- Configure msmtp:
auth oauthbearer user [email protected] passwordeval "/usr/local/bin/get_gmail_oauth2_token.sh" - The helper should print an access token (not the refresh token) and msmtp will use it as the OAuth bearer token. Several community scripts exist; choose one maintained and audited.
- Client certificates (less common)
- For some SMTP servers you can use client certificates; msmtp supports sslcertificate and sslkey options.
TLS and certificate validation
- For STARTTLS on port 587: tls on tls_starttls on
- For implicit TLS on port 465: tls on tls_starttls off
- To specify CA certificates: tls_trust_file /path/to/ca-bundle.crt
Avoid disabling certificate checks (tls_certcheck off) in production. If you must for testing, do so temporarily and be aware of the security risk.
Using msmtp from the command line
Send a simple message:
echo -e "Subject: Test This is a test" | msmtp -a default [email protected] From a file:
msmtp -a default [email protected] < message.txt Send with a custom From header:
sendmail_from="Sender Name <[email protected]>" printf "From: %s Subject: %s %s " "$sendmail_from" "Hello" "Body" | msmtp -a default [email protected] Check verbose output:
msmtp -v -a default [email protected] < message.txt Integrating msmtp with MUAs
Mutt/Neomutt configuration example (~/.muttrc):
set sendmail="/usr/bin/msmtp" set use_from=yes set realname="Your Name" set [email protected] If msmtp-mta provides a sendmail-compatible wrapper, you can leave sendmail at /usr/sbin/sendmail.
For mail clients that expect a sendmail interface, ensure msmtp is symlinked or aliased accordingly:
sudo ln -s /usr/bin/msmtp /usr/sbin/sendmail (Replace paths as appropriate and be cautious system-wide.)
Automated scripts and cron jobs
When run from cron, the environment is minimal. Always specify full paths to msmtp and any helpers (passwordeval scripts). Example cron-safe call:
/usr/bin/msmtp -a default [email protected] < /home/user/mail/message.txt Ensure ~/.msmtprc is accessible to the user running the cron job and that permissions are secure.
Logging and debugging
Enable verbose and log options in ~/.msmtprc for persistent logs:
logfile ~/.msmtp.log debug on Or use -v on the command line for one-off debugging. msmtp will show SMTP dialogue, which helps diagnose authentication, TLS, and server response errors.
Common errors and fixes
- “Authentication unsuccessful” — check credentials, auth method, and whether the server requires OAuth2 (e.g., Gmail).
- “TLS handshake failed” — ensure correct tls_trust_file and that system CA bundle is up to date.
- “Relay access denied” — server refuses to relay; authenticate or use correct SMTP relay for your domain.
- Permission denied reading ~/.msmtprc — ensure chmod 600 and owned by the user running msmtp.
- “Invalid response to AUTH” with OAuth2 — ensure helper outputs only the access token and correct auth type is configured.
Security best practices
- Never store plaintext passwords in ~/.msmtprc; use passwordeval, system keyring, or OS credential stores.
- Restrict config file permissions: chmod 600 ~/.msmtprc.
- Use STARTTLS or implicit TLS; avoid plaintext on port 25 unless within a secured network.
- Use OAuth2 for providers that support it (Google, Microsoft).
- Keep msmtp and system CA bundles updated.
Example: Gmail (OAuth2) — high-level steps
- Register an OAuth app in Google Cloud Console; obtain client_id and client_secret.
- Get an OAuth2 refresh token for the account (one-time interactive flow).
- Create a helper script that exchanges the refresh token for an access token and prints it.
- Configure ~/.msmtprc:
account gmail host smtp.gmail.com port 587 auth oauthbearer user [email protected] passwordeval "/usr/local/bin/gmail_oauth_token.sh" tls on tls_starttls on - Test with: “` echo -e “Subject: Test
Hello” | msmtp -a gmail [email protected] “`
Further reading and resources
- msmtp manual: man msmtp
- Example OAuth2 helper scripts on GitHub (search for maintained repositories)
- Mutt/Neomutt integration docs
If you want, I can:
- Provide a ready-to-use ~/.msmtprc for a specific provider (Gmail, Outlook, or custom SMTP) with secure password helper examples.
- Generate a small OAuth2 helper script for Gmail (you’ll still need to register credentials).
Leave a Reply