This manual was last updated July 7, 2005 for version 1.4.2 of msmtp.
Copyright (C) 2005 Martin Lambers
This program, including this manual, is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.This program, including this manual, is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
msmtp is an SMTP client.
In its main mode of operation, it reads a mail from standard input and sends it to a predefined SMTP server that takes care of proper delivery. Command line options and exit codes are compatible to sendmail.
Supported SMTP features include:
The best way to start is probably to have a look at the Examples section. See Examples.
In addition to sendmail mode, there are two other modes of operation:
Normally, a system wide configuration file and/or a user configuration file contain information about which SMTP server to use and how to use it, but almost all settings can also be configured on the command line.
The information about SMTP servers is organized in accounts. Each account describes one SMTP server: host name, authentication settings, TLS settings, and so on. Each configuration file can define multiple accounts.
msmtp supports a system wide configuration file and a user configuration file. Both are optional and need not exist.
If it exists and is readable, a system wide configuration file
SYSCONFDIR/msmtprc will be loaded, where SYSCONFDIR depends on
your platform; the default is /usr/local/etc.
Use --version to find out which directory is used.
If it exists and is readable, a user configuration file will be loaded
($HOME/.msmtprc by default). 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.
Configuration data from either file can be changed by command line options.
A configuration file is a simple text file. Empty lines and comment lines (whose first non-blank character is '#') are ignored. Every other line must contain a command and may contain an argument to that command. The argument may be enclosed in double quotes (").
If the first character of a filename is the tilde (~), this tilde will be
replaced by $HOME. If a command accepts the argument on, it also
accepts an empty argument and treats that the same as on.
Commands form groups. Each group starts with the account command and defines the settings for one SMTP server.
See Examples.
provider.example for
joe@provider.example) or the fully qualified domain name of your host
(if available).
See Authentication.
~/.netrc, and if that fails, msmtp will prompt you for it.
See Authentication.
See Sendmail mode.
msmtp [option...] [--] recipient...msmtp [option...] -t [--] [recipient...]
msmtp [option...] --serverinfo
msmtp [option...]
--rmqs=(host|@domain|#queue)
Options override configuration file settings. They are compatible with sendmail where appropriate.
Most options in this category correspond to a configuration file command. Please refer to Configuration files for detailed information.
$HOME/.msmtprc as the user configuration
file.
The following options are accepted but ignored for sendmail compatibility: -Btype, -bm, -G, -hN, -i, -L tag, -m, -n, -O option=value, -ox value, -v
There are three ways to choose the account to use. It depends on the circumstances which method is the best.
The standard exit codes from sysexits.h are used.
SYSCONFDIR/msmtprcSYSCONFDIR is on your platform.
$HOME/.msmtprc$HOME/.netrc.netrc file contains login information. If a password is not found
in the configuration file, msmtp will search it in .netrc before
prompting the user for it. The syntax of .netrc is described in the
netrc(5) or ftp(1) manual page.
$USER, $LOGNAMELOGNAME is only used if USER is unset.
$TMPDIRQuoting from RFC2246, the TLS 1.0 protocol specification:
"The TLS protocol provides communications privacy over the Internet.
The protocol allows client/server applications to communicate in a way that
is designed to prevent eavesdropping, tampering, or message forgery."
SMTP servers can use TLS in one of two modes:
When TLS is started, the server sends a certificate to identify itself. This certificate contains information about the certificate owner, the certificate issuer, and the activation and expiration times of the certificate. This information can be displayed in server information mode. See Server information mode.
Some sanity checks are done with the server certificate. These include:
Note that the SMTP server cannot be fully trusted just because the certificate passes the sanity checks. To verify that the user can trust the SMTP server, it is necessary to use a (list of) certificates of Certification Authorities (CAs) that are trusted. If msmtp can verify that the server certificate was issued by one of these CAs, then the SMTP server is trusted. A file containing CA certificates can be set with tls_trust_file or --tls-trust-file (see tls_trust_file, –tls-trust-file).
If the server requests it, the client can send a certificate, too. This allows the server to verify the identity of the client. See the EXTERNAL mechanism in Authentication. The tls_key_file/tls_cert_file commands or the --tls-key-file/--tls-cert-file options can be used to set a client certificate. See tls_key_file/–tls-key-file, tls_cert_file/–tls-cert-file. Note that GnuTLS will only send a client certificate if it matches one of the CAs advertised by the server. If you set a client certificate but it is not send to the server, it probably does not match any CA that the server trusts.
Many SMTP servers require a client to authenticate itself before it is allowed to send mail.
Multiple authentication methods exist. Most SMTP servers support only some of them. Some methods send authentication data in plain text (or nearly plain text) to the server. These methods should only be used when TLS is active to prevent others from stealing the password. See Transport Layer Security.
msmtp supports a subset of the following authentication methods:
It depends on the underlying authentication library and its version whether a particular method is supported or not. Use the --version to find out which methods are supported by your version of msmtp.
Authentication data can be set with the user and password commands
or with the --user option. See user, password, –user.
If no password is set but one is needed during authentication, msmtp will try to
find it in ~/.netrc, and if that fails, msmtp will prompt you for it.
The authentication method can be chosen with the auth command or --auth option, but it is usually sufficient to just use the on argument to let msmtp choose the method itself. See auth, –auth.
If msmtp chooses the method itself, it will not choose a method that sends plain text authentication data when TLS is not active. This means that only CRAM-MD5, DIGEST-MD5, GSSAPI, and NTLM are available when TLS is inactive. PLAIN and LOGIN are only available when TLS is active. If you really want to send clear text authentication data, you have to force msmtp to do that by setting the authentication method to PLAIN or LOGIN when TLS is off.
In situations such as delivery failure or very long delivery delay, the mail system often generates a message for the sender of the mail in question, informing him about the difficulties.
Delivery Status Notification (DSN) requests, defined in RFC 3461, try to give the sender of the mail control about how and when these DSN messages are sent. The SMTP server must support the DSN extension. See Server information mode.
A first parameter controls when such messages should be generated: never, on delivery failure, on delivery delay, and/or on success. This can be set with dsn_notify/--dsn-notify, see dsn_notify/–dsn-notify.
A second parameter controls how much of the original mail should be contained in a DSN message: only the headers, or the full mail. This can be set with dsn_return/--dsn-return, see dsn_return/–dsn-return. Note that this parameter only applies to DSNs that indicate delivery failure for at least one recipient. If a DSN contains no indications of delivery failure, only the headers of the message are returned.
The SMTP server expects a sender mail address for each mail. This is the envelope from address. It is independent of the From header (because it is part of the mail envelope, not of the mail itself), but in most cases both addresses are the same.
The from command and the --from option can explicitly set an envelope from address. See from, –from.
If no envelope from address is set, msmtp will construct one: The local part
will be set to $USER or, if that fails, to $LOGNAME or, if that
fails, to the login name of the current user. If that fails, too, the local
part will be set to unknown.
Note that the envelope from address will lack a domain part in these cases.
If a mail domain is given with the maildomain command or the --maildomain option (see maildomain/–maildomain), it will become the domain part of the envelope from address.
Example: maildomain example.com and the user name joe will result
in the envelope from address joe@example.com.
Logging is enabled on a per account basis. If it is enabled, msmtp will generate one log line for each mail it tries to send via the account in question.
The line will include the following information:
host=hostname
tls=(on|off)
auth=(on|off)
user=name
from=address
recipients=addr1,addr2,...
mailsize=number
smtpstatus=number,
smtpmsg='message'. Multiline SMTP messages will be concatenated into one
line.
errormsg='message'
sysexits.h; EX_OK indicates
success): exitcode=EX_?
If a logfile is given with the logfile command or --logfile option, this log line will be prepended with the current date and time and appended to the specified file. See logfile, –logfile.
If syslog logging is enabled with the syslog command or --syslog option, the log line is passed to the syslog service with the specified facility. See syslog, –syslog.
The mail will be transmitted unaltered to the SMTP server, with one exception: the Bcc header(s) will be stripped from it before the transmission. This behavior can be changed with the keepbcc command and --keepbcc option, see keepbcc/–keepbcc.
In server information mode, msmtp prints as much information about the SMTP server as it can get and then exits.
The SMTP features that can be detected are:
If TLS is activated for server information mode, the following information will be printed about the SMTP server's TLS certificate (if available):
Remote Message Queue Starting (RMQS) is defined in RFC 1985. It is a way for a client to request that a server start the processing of its mail queues for messages that are waiting at the server for the client machine. If any messages are at the server for the client, then the server creates a new SMTP session and sends the messages at that time.
msmtp can send the request (using the ETRN SMTP command); a mail server on the client side should then accept the connection of the remote SMTP server to receive the mail.
Destinations defined in RFC 1985 are:
# A system wide configuration is optional.
# If it exists, it usually defines a default account.
# This allows msmtp to be used like /usr/sbin/sendmail.
account default
# The SMTP smarthost.
host mailhub.oursite.example
# Construct envelope from addresses of the form "user@oursite.example".
# Without this, envelope from addresses will just contain the user name,
# without a domain part.
#maildomain oursite.example
# Use TLS.
#tls on
#tls_trust_file /etc/ssl/certs/ca.pem
# Syslog logging with facility LOG_MAIL instead of the default LOG_USER.
syslog LOG_MAIL
# Set default values for all following accounts.
defaults
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile ~/.msmtp.log
# A freemail service
account freemail
host smtp.freemail.example
from joe_smith@freemail.example
auth on
user joe.smith
password secret
# A second mail address at the same freemail service
account freemail2 : freemail
from joey@freemail.example
# The SMTP server of the provider.
account provider
host mail.provider.example
from smithjoe@provider.example
auth on
user 123
password pwd
# Set a default account
account default : provider
Create a configuration file for msmtp and add the following lines to your Mutt configuration file:
set sendmail="/path/to/msmtp"
set use_from=yes
set realname="Your Name"
set from=you@example.com
set envelope_from=yes
The envelope_from=yes option lets Mutt use the -f option of msmtp. Therefore msmtp chooses the first account that matches the from address you@example.com. Alternatively, you can use the -a option:
set sendmail="/path/to/msmtp -a my_account"
See Choosing an account.
Or set everything from the command line:
set sendmail="/path/to/msmtp --host=mailhub -f me@example.com --tls"
If you have multiple mail accounts in your msmtp configuration file and let Mutt use the -f option to choose one, you can easily switch accounts in Mutt with the following Mutt configuration lines:
macro generic "<esc>1" ":set from=you@example.com"
macro generic "<esc>2" ":set from=you@your-employer.example"
macro generic "<esc>3" ":set from=you@some-other-provider.example"
Now you can use <esc>1, <esc>2, and <esc>3 to switch accounts.
The following example uses a different approach: it maps the single key
<tab> in Compose context for switching between the various account in a
handy visual way. In the same Compose context, = is mapped in order to
show the current msmtp account. This example was contributed by Thomas Baruchel.
# Define <tab> and = in order to switch or see the current msmtp account
# Don't forget to put the right path for msmtp binary
macro compose \Cx_ ":set sendmail"
macro compose \Cx| "\Cx_ = \"/usr/local/bin/msmtp"
macro compose \Cx& ":macro compose \\t \\Cx"
macro compose <tab> "\Cx0"
macro compose = "\Cx_\n"
# Put the account in the following lines (here three accounts)
# Don't forget to put the number of the account at the beginning
# of the line, and the number of the next account after the '&'
macro compose \Cx0 "\Cx|\"\n\Cx&1\n\Cx_\n" # default and switch to 1
macro compose \Cx1 "\Cx| -a example_account\"\n\Cx&2\n\Cx_\n" # switch to 2
macro compose \Cx2 "\Cx| -a gmail\"\n\Cx&0\n\Cx_\n" # switch to 0
# End of the accounts
Define a default account, and put the following into your ~/.mailrc:
set sendmail="/path/to/msmtp"
You need to define a default account, because mail does not allow extra options to the msmtp command line.
The homepage of msmtp is http://msmtp.sourceforge.net/; the SourceForge project page is http://sourceforge.net/projects/msmtp/.
The mailing list msmtp-users can be accessed from the project page.
Please send any questions, suggestions, and bug reports either to the mailing
list or to Martin Lambers (marlam@marlam.de, OpenPGP key:
http://www.marlam.de/key.txt).
If you send a bug report, please include the output of msmtp --version.