msmtp

Related articles
Mail server
msmtp
is a very simple and easy to use SMTP client with fairly complete
sendmail
compatibility.
Installation
Install
the
msmtp
package. Additionally,
install
msmtp-mta
, which creates a sendmail alias to msmtp.
Basic setup
Since msmtp version 1.8.6 you can place your user configuration either at
~/.msmtprc
or
$XDG_CONFIG_HOME/msmtp/config
. The following is an example of a msmtp configuration (the file is based on the per-user example file located at
/usr/share/doc/msmtp/msmtprc-user.example
; the system configuration file belongs at
/etc/msmtprc
and its corresponding example file is located at
/usr/share/doc/msmtp/msmtprc-system.example
).
Tip
If using Gmail you will need to either:
Use OAuth, via
#OAuth2 Setup
.
If you use two factor authentication:
create an app password
.
~/.msmtprc
# Set default values for all following accounts.
defaults
auth           on
tls            on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile        ~/.msmtp.log

# Gmail
account        gmail
host           smtp.gmail.com
port           465
tls_starttls   off
from
username
@gmail.com
user
username
password
plain-text-password
# A freemail service
account        freemail
host           smtp.freemail.example
from           joe_smith@freemail.example
...

# Accounts can inherit info from another account
account        postmasterfreemail : freemail
from           postmaster*@freemail.example

# Set a default account
account default: gmail
Note
If you are using SSL/TLS and receive a "Server sent empty reply" error message, see
#Server sent empty reply
.
The
user
configuration file must be explicitly readable/writeable by its owner or msmtp will fail:
$ chmod 600 ~/.msmtprc
To avoid saving the password in plain text in the configuration file, use
passwordeval
to launch an external program, or see the
#Password management
section below.  This example using Gnu PG is commonly used to perform decryption of a password:
echo -e "password\n" | gpg --encrypt -o .msmtp-gmail.gpg # enter id (email...)
Warning
Most shells save command history(e.g. .bash_history .zhistory). To avoid this, use gpg with shell stdin:
gpg --encrypt -o .msmtp-gmail.gpg -r <email> -
. The ending dash is not a typo, rather it causes gpg to use stdin. After running that snippet of code, type in your password, press enter, and press Control-d so gpg can encrypt your password.
~/.msmtprc
passwordeval    "gpg --quiet --for-your-eyes-only --no-tty --decrypt ~/.msmtp-gmail.gpg"
OAuth2 Setup
OAuth2
can be used to securely authenticate msmtp when basic username/password authentication is unsupported by the site configuration or otherwise undesirable.
Note
this post
explains the now extremely limited functionality permitted for Gmail.
oama
msmtp alone lacks the ability to renew or authorize OAuth2 credentials. A comprehensive solution is using the
oama
utility which provides IMAP/SMTP clients with renewal capabilities and authorization of OAuth2 credentials.
To use oama,
install
oama-bin
AUR
and configure msmtp to use it:
# account at Google with oauth2 access                                    
   account YOUR_EMAIL_NAME@gmail.com
   from YOUR_EMAIL_NAME@gmail.com
   user YOUR_EMAIL_NAME@gmail.com
   auth oauthbearer
   passwordeval oama access YOUR_EMAIL_NAME@gmail.com
   host smtp.gmail.com
   port 587
   tls on
   tls_trust_file /etc/ssl/certs/ca-certificates.crt
Access token renewal happens automatically in the background transparent to the user.
Using the mail command
To send mails using the
mail
command you must install the package
s-nail
, which also provides the
mailx
command. You will also need to provide a
sendmail
-compatible MTA, either by installing
msmtp-mta
(which symlinks
sendmail
to
msmtp
) or by editing
/etc/mail.rc
to set the sendmail path:
/etc/mail.rc
set mta=/usr/bin/msmtp
A
.msmtprc
file will need to be in the home of every user who wants to send mail or alternatively the system wide
/etc/msmtprc
can be used.
msmtp also understands aliases. Add the following line to the defaults section of msmtprc or your local configuration file:
/etc/msmtprc
aliases               /etc/aliases
and create an aliases file in
/etc
/etc/aliases
# Example aliases file

# Send root to Joe and Jane
root: joe_smith@example.com, jane_chang@example.com

# Send everything else to admin
default: admin@domain.example
Test functionality
The account option (
--account=,-a
) tells which account to use as sender:
$ echo "hello there username." | msmtp -a default
username
@domain.com
Or, send both a subject and a body:
$ printf "Subject: Test\n\nhello there username." | msmtp -a default
username
@domain.com
Or, with the addresses in a file:
To:
username
@domain.com
From:
username
@gmail.com
Subject: A test

Hello there.
$ cat test.mail | msmtp -a default <username>@domain.com
Tip
You can use
--read-envelope-from
instead of
-a default
to automatically choose account by the
From:
field in a message you are going to send. You can also use
--read-recipients,-t
to read recipient addresses from the To, Cc, and Bcc headers of the mail in addition to the recipients given on the command line.
Cronie default email client
This article or section is out of date.
Reason:
Arch uses
systemd/Timers
instead of cronie (Discuss in
Talk:Msmtp
)
To make
Cronie
use msmtp rather than sendmail, make sure
msmtp-mta
is installed, or edit the
cronie.service
systemd unit:
/etc/systemd/system/cronie.service.d/msmtp.conf
[Service]
ExecStart=
ExecStart=/usr/bin/crond -n -m '/usr/bin/msmtp -t'
Then you must tell cronie or msmtp what your email address is. One way to accomplish this is by adding it to the msmtp configuration:
Add to
/etc/msmtprc
:
aliases /etc/aliases
Create
/etc/aliases
:
your_username: email@address.com
Alternatively, you can add it directly to the crontab:
Add a
MAILTO
line to the crontab:
MAILTO=email@address.com
Add a
MAILFROM
line to the crontab:
MAILFROM=email@address-from-msmtp.com
The last part is necessary to prevent this error:
sendmail: server message: 550 5.7.1 Rejected due to unmatching envelope and header sender.
Password management
Passwords for msmtp
can be stored
in plaintext, encrypted files, or a keyring.
GNOME Keyring
Storing passwords in
GNOME Keyring
is supported natively in msmtp. Setup the keyring as described on the linked wiki page and install
libsecret
. Then, store a password by running:
secret-tool store --label=msmtp host
smtp.your.domain
service smtp user
yourusername
msmtp
should now find the password automatically.
GnuPG
The
password
directive may be omitted. In that case, if the account in question has
auth
set to a legitimate value other than
off
, invoking msmtp from an interactive shell will ask for the password before sending mail. msmtp will not prompt if it has been called by another type of application, such as
Mutt
. For such cases, the
--passwordeval
parameter
can be used to call an external keyring tool like
GnuPG
.
To do this, set up
GnuPG
, including
gpg-agent
to avoid having to enter the password every time. Then, create an encrypted password file for msmtp, as follows. Create a secure directory with
700
permissions located on a
tmpfs
to avoid writing the unencrypted password to the disk. In that directory create a plain text file with the mail account password. Then, encrypt the file with your private key:
$ gpg --default-recipient-self -e
/path/to/plain/password
Remove the plain text file and move the encrypted file to the final location, e.g.
~/.mail/.msmtp-credentials.gpg
. In
~/.msmtprc
add:
~/.msmtprc
passwordeval  "gpg --quiet --for-your-eyes-only --no-tty --decrypt ~/.mail/.msmtp-credentials.gpg"
Normally this is sufficient for a GUI password prompt to appear when, for example, sending a message from
Mutt
. If gpg prompt for the passphrase cannot be issued, then start the
gpg-agent
before. A simple hack to start the agent is to execute a external command in your muttrc using the backtick
`
command
`
syntax. For example, you can put something like the following in your muttrc:
muttrc
set my_msmtp_pass=`gpg -d mypwfile.gpg`
Mutt will execute this when it starts, gpg-agent will cache your password, msmtp will be happy and you can send mail.
Note
If you do this, you will have to restart mutt after gpg-agent clears the password to start sending emails again.
An alternative is to place passwords in
~/.netrc
, a file that can act as a common pool for msmtp,
OfflineIMAP
, and associated tools.
pass
You may store your credentials inside of the
pass
password manager.
If you are using your main password (which is customarily stored in the first line of your pass file) to login into your SMTP server, you can add the following to your
.msmptrc
:
~/.msmtprc
passwordeval   "pass your_email_password_entry | head -n1"
If you are using
Gmail
, and have set up an
app password
, the following configuration will suit you better.
Save your app password inside your
pass
password file, but with a
msmtp:
prefix:
your_email_password_entry
your_main_password

login: your_username
url: the_url_of_your_email
msmtp: your_msmtp_app_password
Then add the following to your
.msmptrc
:
~/.msmtprc
passwordeval   "pass your_email_password_entry | awk '/^msmtp:/ { print $2; }'"
In either case, trying to send an email with msmtp will trigger
pass
, which may ask you for your
pass
master password if you have not entered it recently.
Miscellaneous
Using msmtp offline
Although msmtp is great, it requires that you be online to use it. This is not ideal for people on laptops with intermittent connections to the Internet or dialup users. Several scripts have been written to remedy this fact, collectively called msmtpqueue.
The scripts are installed under
/usr/share/doc/msmtp/msmtpqueue
. You might want to copy the scripts to a convenient location on your computer, (
/usr/local/bin
is a good choice).
Finally, change your MUA to use msmtp-enqueue.sh instead of msmtp when sending e-mail. By default, queued messages will be stored in
~/.msmtpqueue
. To change this location, change the
QUEUEDIR=$HOME/.msmtpqueue
line in the scripts (or delete the line, and export the QUEUEDIR variable in
.bash_profile
like so:
export QUEUEDIR="$XDG_DATA_HOME/msmtpqueue"
).
When you want to send any mail that you have created and queued up run:
$ /usr/local/bin/msmtp-runqueue.sh
Adding
/usr/local/bin
to your PATH can save you some keystrokes if you are doing it manually. The README file that comes with the scripts has some handy information, reading it is recommended.
Vim syntax highlighting
The msmtp source distribution includes an
msmtprc
syntax-highlighting script for
Vim
, which is available at
/usr/share/vim/vimfiles/syntax/msmtp.vim
. The filetype is not detected automatically. The easiest way to enable it is by adding a
modeline
at the top or bottom of the file(s), i.e.:
# vim:filetype=msmtp
Send mail with PHP using msmtp
Look for
sendmail_path
option in your
php.ini
and edit like this:
sendmail_path = "/usr/bin/msmtp -C /path/to/your/config -t"
Note that you
can not
use a user configuration file (ie: one under ~/) if you plan on using msmtp as a sendmail replacement with php or something similar.
In that case just create /etc/msmtprc, and remove your user configuration (or not if you plan on using it for something else). Also make sure it is readable by whatever you are using it with (php, django, etc...).
From the msmtp manual:
Accounts defined in the user configuration file override accounts from the system configuration file. The user configuration file must have no more permissions than user read/write
So it is impossible to have a conf file under ~/ and have it still be readable by the php user.
To test it place this file in your php enabled server or using php-cli.
<?php
mail("your@email.com", "Test email from PHP", "msmtp as sendmail for PHP");
?>
php-fpm
will fail to send mails and logs the warning:
PHP Warning:  mail(mail.log): failed to open stream
unless you set the permissions of your /etc/msmtprc to user read/write (600).
Troubleshooting
Issues with TLS
If you see one of the following messages:
msmtp: TLS certificate verification failed: the certificate hasn't got a known issuer
msmtp: TLS certificate verification failed: The certificate is NOT trusted. The certificate issuer is unknown.
It probably means your
tls_trust_file
parameter of the configuration file is not right.
Just follow the
fine manual
. It explains you how to find out the server certificate issuer of a given smtp server. Then you can explore the
/usr/share/ca-certificates/
directory to find out if by any chance, the certificate you need is there. If not, you will have to get the certificate on your own. If you are using your own certificate, you can make msmtp trust it by adding the following to your
~/.msmtprc
:
tls_fingerprint <SHA1 (recommended) or MD5 fingerprint of the certificate>
If the user have the certificate used by the server in a
PEM
file, he can find the fingerprint of the certificate stored  using
openssl
:
openssl x509 -in
CERT.pem
-inform PEM -fingerprint
If you are trying to send mail through Gmail and are receiving this error, have a look at
this
thread or just use the second Gmail example above.
If you are completely desperate, but are 100% sure you are communicating with the right server, you can always temporarily disable the cert check:
$ msmtp --tls-certcheck off
If you see the following message:
msmtp: TLS handshake failed: the operation timed out
You may be affected by this
bug
. Recompile with
--with-ssl=openssl
(msmtp is compiled with GnuTLS by default).
Server sent empty reply
If you get a "server sent empty reply" error, this probably means the mail server does not support STARTTLS over port 587, but requires TLS over port 465.
To let msmtp use TLS over port 465, add the following line to
~/.msmtprc
:
tls_starttls off
Zoho SMTP server
It can also happen on Zoho SMTP servers when the mail has no
blank line between mail headers and mail body (see Debian bug
#917260
). The solution to this is to add an extra space in between:
"test-header\n\ntest-body"
Issues with GSSAPI
If you get the following error
GNU SASL: GSSAPI error in client while negotiating security context in gss_init_sec_context() in SASL library.  This is most likely due insufficient credentials or malicious interactions.
Try changing your auth setting to plain, instead of gssapi in your .msmtprc file
[1]
:
auth plain
Envelope not accepted
In the case of
msmtp: envelope from address mail@server not accepted by the server
msmtp: server message: 530 5.5.1 Authentication Required.
msmtp: could not send mail (account default from /etc/msmtprc)
Try enabling authentication with
auth on
or any other method.