1MSMTP(1) General Commands Manual MSMTP(1)
2
6 msmtp - An SMTP client
7
9 Sendmail mode (default):
10 msmtp [option...] [--] recipient...
11 msmtp [option...] -t [--] [recipient...]
12 Server information mode:
14 msmtp [option...] --serverinfo
15 Remote Message Queue Starting mode:
17 msmtp [option...] --rmqs=host|@domain|#queue
18
20 In the default sendmail mode, msmtp reads a mail from standard input
21 and sends it to an SMTP server for delivery.
22 In server information mode, msmtp prints information about an SMTP
23 server.
24 In Remote Message Queue Starting mode, msmtp sends a Remote Message
25 Queue Starting request for a host, domain, or queue to an SMTP server.
26
28 The standard sendmail exit status codes are used, as defined in sysex‐
29 its.h.
30
32 Options override configuration file settings.
33 They are compatible with sendmail where appropriate.
34 General options
36 --version
38 Print version information. This includes information
39 about the library used for TLS/SSL support (if any), the
40 library used for authentication, the authentication mech‐
41 anisms supported by this library, and the default loca‐
42 tions of the system and user configuration files.
43 --help Print help.
45 -P, --pretend
47 Print the configuration settings that would be used, but
48 do not take further action. An asterisk ('*') will be
49 printed instead of your password.
50 -d, --debug
52 Print lots of debugging information, including the whole
53 conversation with the SMTP server. Be careful with this
54 option: the (potentially dangerous) output will not be
55 sanitized, and your password may get printed in an easily
56 decodable format!
57 Changing the mode of operation
59 -S, --serverinfo
61 Print information about the SMTP server and exit. This
62 includes information about supported features (mail size
63 limit, authentication, TLS, DSN, ...) and about the TLS
64 certificate (if TLS is active).
65 --rmqs=(host|@domain|#queue)
67 Send a Remote Message Queue Starting request for the
68 given host, domain, or queue to the SMTP server and exit.
69 Configuration options
71 -C, --file=filename
73 Use the given file instead of ~/.msmtprc as the user con‐
74 figuration file.
75 -a, --account=account_name
77 Use the given account instead of the account named
78 "default". The settings of this account may be changed
79 with command line options. This option cannot be used
80 together with the --host option.
81 --host=hostname
83 Use this SMTP server with settings from the command line;
84 do not use any configuration file data. This option can‐
85 not be used together with the --account option.
86 --port=number
88 Set the port number to connect to. See the port command
89 below.
90 --timeout=(off|seconds)
92 Set a network timeout. See the timeout command below. For
93 compatibility with older versions, --connect-timeout is
94 accepted as an alias for this option.
95 --protocol=(smtp|lmtp)
97 Set the protocol to use. See the protocol command below.
98 --auth[=(on|off|method)]
100 Enable or disable authentication. You can optionally
101 choose the method. See the auth command below.
102 --user=[username]
104 Set or unset the user name for authentication. See the
105 user command below.
106 --tls[=(on|off)]
108 Enable or disable TLS/SSL encryption. See the tls command
109 below.
110 --tls-starttls[=(on|off)]
112 Enable or disable STARTTLS for TLS encryption. See the
113 tls_starttls command below.
114 --tls-trust-file=[file]
116 Set or unset a trust file for TLS encryption. See the
117 tls_trust_file command below.
118 --tls-key-file=[file]
120 Set or unset a key file for TLS encryption. See the
121 tls_key_file command below.
122 --tls-cert-file=[file]
124 Set or unset a cert file for TLS encryption. See the
125 tls_cert_file command below.
126 --tls-certcheck[=(on|off)]
128 Enable or disable server certificate checks for TLS
129 encryption. See the tls_certcheck command below.
130 --tls-force-sslv3[=(on|off)]
132 Force TLS/SSL version SSLv3. See the tls_force_sslv3 com‐
133 mand below.
134 --domain=[string]
136 Set the argument of the SMTP EHLO (or LMTP LHLO) command.
137 See the domain command below.
138 Options specific to sendmail mode
140 --auto-from[=(on|off)]
142 Enable or disable automatic envelope-from addresses. The
143 default is off. See the auto_from command below.
144 -f, --from=address
146 Set the envelope-from address. It is only used when
147 auto_from is off.
148 If no account was chosen yet (with --account or --host),
149 this option will choose the first account that has the
150 given envelope-from address (set with the from command).
151 If no such account is found, "default" is used.
152 --maildomain=[domain]
154 Set the domain part for generated envelope-from
155 addresses. It is only used when auto_from is on. See the
156 maildomain command below.
157 -N, --dsn-notify=(off|cond)
159 Set or unset DSN notification conditions. See the
160 dsn_notify command below.
161 -R, --dsn-return=(off|ret)
163 Set or unset the DSN notification amount. See the
164 dsn_return command below. Note that hdrs is accepted as
165 an alias for headers to be compatible with sendmail.
166 --keepbcc[=(on|off)]
168 Enable or disable the preservation of the Bcc header. See
169 the keepbcc command below.
170 -X, --logfile=[file]
172 Set or unset the log file. See the logfile command below.
173 --syslog[=(on|off|facility)]
175 Enable or disable syslog logging. See the syslog command
176 below.
177 -t, --read-recipients
179 Read recipient addresses from the To, Cc, and Bcc headers
180 of the mail in addition to the recipients given on the
181 command line.
182 -- This marks the end of options. All following arguments
184 will be treated as recipient addresses, even if they
185 start with a '-'.
186 The following options are accepted but ignored for sendmail compatibil‐
188 ity:
189 -Btype, -bm, -Fname, -G, -hN, -i, -L tag, -m, -n, -O option=value, -ox
190 value, -v
191
193 Normally, a system wide configuration file and/or a user configuration
194 file contain information about which SMTP server to use (and how to use
195 it), but almost all settings can also be configured on the command
196 line.
197 Information about SMTP servers is organized in accounts. Each account
199 describes one SMTP server: host name, authentication settings, TLS set‐
200 tings, and so on. Each configuration file can define multiple
201 accounts.
202 In sendmail mode, an envelope-from address is necessary to send mail.
204 This is the mail address that will be presented to the SMTP server as
205 the originator of the mail. Envelope-from addresses can be generated
206 automatically (when auto_from is enabled) or set explicitly with the
207 from command or --from option. When auto_from is enabled, an envelope-
208 from address of the form user@domain will be generated. The local part
209 will be set to $USER or, if that fails, to $LOGNAME or, if that fails,
210 to the login name of the current user. The domain part can be set with
211 the maildomain command. If the maildomain is empty, the envelope-from
212 address will only consist of the user name and not have a domain part.
213 The user can choose which account to use in one of three ways:
215 --account=id
217 Use the given account. Command line settings override configura‐
218 tion file settings.
219 --host=hostname
221 Use only the settings from the command line; do not use any con‐
222 figuration file data.
223 --from=address
225 Choose the first account from the system or user configuration
226 file that has a matching envelope-from address as specified by a
227 from command. This works only when neither --account nor --host
228 is used.
229 If none of the above options is used (or if --from is used but no
231 account has a matching from command), then the account "default" is
232 used.
233 Skip to the EXAMPLES section for a quick start.
235
237 If it exists and is readable, a system wide configuration file
238 SYSCONFDIR/msmtprc will be loaded, where SYSCONFDIR depends on your
239 platform. Use --version to find out which directory is used.
240 If it exists and is readable, a user configuration file will be loaded
241 (~/.msmtprc by default). Accounts defined in the user configuration
242 file override accounts from the system configuration file. The user
243 configuration file must have no more permissions than user read/write.
244 Configuration data from either file can be changed by command line
245 options.
246 A configuration file is a simple text file. Empty lines and comment
248 lines (whose first non-blank character is '#') are ignored.
249 Every other line must contain a command and may contain an argument to
250 that command.
251 The argument may be enclosed in double quotes ("), for example if its
252 first or last character is a blank.
253 If the first character of a filename is the tilde (~), this tilde will
254 be replaced by $HOME. If a command accepts the argument on, it also
255 accepts an empty argument and treats that as if it was on.
256 Commands form groups. Each group begins with the account command and
257 defines the settings for one SMTP server.
258 Skip to the EXAMPLES section for a quick start.
260 Commands are as follows:
262 defaults
264 Set defaults. The following configuration commands will set
265 default values for all following account definitions in the cur‐
266 rent configuration file.
267 account name [:account[,...]]
269 Start a new account definition with the given name. The current
270 default values are filled in.
271 If a colon and a list of previously defined accounts is given
272 after the account name, the new account, with the filled in
273 default values, will inherit all settings from the accounts in
274 the list.
275 host hostname
277 The SMTP server to send the mail to. The argument may be a host
278 name or a network address. Every account definition must con‐
279 tain this command.
280 port number
282 The port that the SMTP server listens on. The default port will
283 be acquired from your operating system's service database: for
284 SMTP, the service is "smtp" (default port 25), unless TLS with‐
285 out STARTTLS is used, in which case it is "ssmtp" (465). For
286 LMTP, it is "lmtp".
287 timeout (off|seconds)
289 Set or unset a network timeout, in seconds. The argument off
290 means that no timeout will be set, which means that the operat‐
291 ing system default will be used.
292 For compatibility with older versions, connect_timeout is
293 accepted as an alias for this command.
294 protocol (smtp|lmtp)
296 Set the protocol to use. Currently only SMTP and LMTP are sup‐
297 ported. SMTP is the default. See the port command above for
298 default ports.
299 auto_from [(on|off)]
301 Enable or disable automatic envelope-from addresses. The default
302 is off. When enabled, an envelope-from address of the form
303 user@domain will be generated. The local part will be set to
304 $USER or, if that fails, to $LOGNAME or, if that fails, to the
305 login name of the current user. The domain part can be set with
306 the maildomain command. If the maildomain is empty, the enve‐
307 lope-from address will only consist of the user name and not
308 have a domain part. When auto_from is disabled, the envelope-
309 from address must be set explicitly.
310 from envelope_from
312 Set the envelope-from address. This address will only be used
313 when auto_from is off.
314 maildomain [domain]
316 Set a domain part for the generation of an envelope-from
317 address. This is only used when auto_from is on. The domain may
318 be empty.
319 auth [(on|off|method)]
321 This command enables or disables SMTP authentication. You should
322 not need to set the method yourself; with the argument on, msmtp
323 will choose the best one available for you (see below).
324 You probably need to set a username (with user) and password
325 (with password). If no password is set but one is needed during
326 authentication, msmtp will try to find it in ~/.netrc, and if
327 that fails, msmtp will prompt you for it.
328 Available methods are plain, cram-md5, digest-md5, gssapi,
329 external, login, and ntlm. Note that one or more of these meth‐
330 ods may be unavailable due to lack of support in the underlying
331 authentication library. Use the --version option to find out
332 which methods are supported.
333 The plain and login methods send your authentication data in
334 cleartext over the net, and the ntlm method may be vulnerable to
335 attacks. These methods should therefore only be used together
336 with the tls command.
337 If you don't choose the method yourself, msmtp chooses the best
338 secure method that the SMTP server supports. Secure means that
339 your authentication data will not be sent in cleartext over the
340 net. For TLS encrypted connections, every authentication method
341 is secure in this sense. If TLS is not active, only gssapi,
342 digest-md5, and cram-md5 are secure in this sense.
343 The external is special: the actual authentication happens out‐
344 side of the SMTP protocol, typically by sending a TLS client
345 certificate (see the tls_cert_file command). The external method
346 merely confirms that this authentication succeeded for the given
347 user (or, if no user name is given, confirms that authentication
348 succeeded). This authentication method is not chosen automati‐
349 cally; you have to request it manually.
350 user [username]
352 Set your user name for SMTP authentication. An empty argument
353 unsets the user name. Authentication must be activated with the
354 auth command.
355 password [secret]
357 Set your password for SMTP authentication. An empty argument
358 unsets the password. Authentication must be activated with the
359 auth command. If no password is set but one is needed during
360 authentication, msmtp will try to find it in ~/.netrc, and if
361 that fails, msmtp will prompt you for it.
362 ntlmdomain [domain]
364 Set a domain for the ntlm authentication method. The default is
365 to use no domain (equivalent to an empty argument), but some
366 servers seem to require one, even if it is an arbitrary string.
367 tls [(on|off)]
369 This command enables or disables TLS (also known as SSL)
370 encrypted connections to the SMTP server. Not every server sup‐
371 ports TLS.
372 With TLS/SSL, the connection with the SMTP server will be pro‐
373 tected against eavesdroppers and man-in-the-middle attacks. To
374 use TLS/SSL, it is required to either use the tls_trust_file
375 command (highly recommended) or to disable tls_certcheck.
376 tls_starttls [(on|off)]
378 By default, TLS encryption is activated using the STARTTLS SMTP
379 command. By disabling this, TLS encryption is immediately
380 started instead (this is known as SMTP tunneled through
381 TLS/SSL). The default port is set to 465 for this mode of opera‐
382 tion.
383 For compatibility with older versions, tls_nostarttls is
384 accepted as an alias for tls_starttls off.
385 tls_trust_file [file]
387 This command activates strict server certificate verification.
388 The filename must be the absolute path name of a file in PEM
389 format containing one or more certificates of trusted Certifica‐
390 tion Authorities (CAs).
391 On Debian based systems, you can install the ca-certificates
392 package and use the file /etc/ssl/certs/ca-certificates.crt.
393 tls_key_file [file]
395 This command (together with the tls_cert_file command) enables
396 msmtp to send a client certificate to the SMTP server if
397 requested. The file must contain the private key of a certifi‐
398 cate in PEM format. An empty argument disables this feature.
399 tls_cert_file [file]
401 This command (together with the tls_key_file command) enables
402 msmtp to send a client certificate to the SMTP server if
403 requested. The file must contain a certificate in PEM format.
404 An empty argument disables this feature.
405 tls_certcheck [(on|off)]
407 This command enables or disables checks for the server certifi‐
408 cate.
409 WARNING: When the checks are disabled, TLS/SSL sessions will be
410 vulnerable to man-in-the-middle attacks!
411 For compatibility with older versions, tls_nocertcheck is
412 accepted as an alias for tls_certcheck off.
413 tls_force_sslv3 [(on|off)]
415 Force TLS/SSL version SSLv3. This might be needed to use SSL
416 with some old and broken servers. Do not use this unless you
417 have to.
418 dsn_notify (off|condition)
420 This command sets the condition(s) under which the mail system
421 should send DSN (Delivery Status Notification) messages. The
422 argument off disables explicit DSN requests, which means the
423 mail decides when to send DSN messages. This is the default.
424 The condition must be never, to never request notification, or a
425 comma separated list (no spaces!) of one or more of the follow‐
426 ing: failure, to request notification on transmission failure,
427 delay, to be notified of message delays, success, to be notified
428 of successful transmission. The SMTP server must support the DSN
429 extension.
430 dsn_return (off|amount)
432 This command controls how much of a mail should be returned in
433 DSN (Delivery Status Notification) messages. The argument off
434 disables explicit DSN requests, which means the mail system
435 decides how much of a mail it returns in DSN messages. This is
436 the default. The amount must be headers, to just return the
437 message headers, or full, to return the full mail. The SMTP
438 server must support the DSN extension.
439 domain argument
441 Use this command to set the argument of the SMTP EHLO (or LMTP
442 LHLO) command. The default is localhost (stupid, but working).
443 Possible choices are the domain part of your mail address
444 (provider.example for joe@provider.example) or the fully quali‐
445 fied domain name of your host (if available).
446 keepbcc [(on|off)]
448 This command controls whether to remove or keep the Bcc header
449 when sending a mail. The default is to remove it.
450 logfile [file]
452 An empty argument disables logging (this is the default).
453 When logging is enabled by choosing a log file, msmtp will
454 append one line to the log file for each mail it tries to send
455 via the account that this log file was chosen for.
456 The line will include the following information: date and time,
457 host name of the SMTP server, whether TLS was used, whether
458 authentication was used, authentication user name (only if
459 authentication is used), envelope-from address, recipient
460 addresses, size of the mail as transferred to the server (only
461 if the delivery succeeded), SMTP status code and SMTP error mes‐
462 sage (only in case of failure and only if available), error mes‐
463 sage (only in case of failure and only if available), exit code
464 (from sysexits.h; EX_OK indicates success).
465 If the filename is a dash (-), msmtp prints the log line to the
466 standard output.
467 syslog [(on|off|facility)]
469 Enable or disable syslog logging. The facility can be one of
470 LOG_USER, LOG_MAIL, LOG_LOCAL0, ..., LOG_LOCAL7. The default is
471 LOG_USER.
472 Each time msmtp tries to send a mail via the account that con‐
473 tains this syslog command, it will log one entry to the syslog
474 service with the chosen facility.
475 The line will include the following information: host name of
476 the SMTP server, whether TLS was used, whether authentication
477 was used, envelope-from address, recipient addresses, size of
478 the mail as transferred to the server (only if the delivery suc‐
479 ceeded), SMTP status code and SMTP error message (only in case
480 of failure and only if available), error message (only in case
481 of failure and only if available), exit code (from sysexits.h;
482 EX_OK indicates success).
483
485 Configuration file
486 # Set default values for all following accounts.
488 defaults
489 tls on
490 tls_trust_file /etc/ssl/certs/ca-certificates.crt
491 logfile ~/.msmtp.log
492 # A freemail service
494 account freemail
495 host smtp.freemail.example
496 from joe_smith@freemail.example
497 auth on
498 user joe.smith
499 password secret
500 # A second mail address at the same freemail service
502 account freemail2 : freemail
503 from joey@freemail.example
504 # The SMTP server of the provider.
506 account provider
507 host mail.provider.example
508 from smithjoe@provider.example
509 auth on
510 user 123456789
511 password my_password
512 # Set a default account
514 account default : provider
515 Manually finding the right CA certificate for tls_trust_file
518 The following example works as of 2007-04-18.
520 For the Gmail SMTP server, you first issue the following command:
521 msmtp --serverinfo --host=smtp.gmail.com --tls=on --port=587 --tls-
522 certcheck=off
523 The option --port=587 is specific to Gmail and should not be used with
524 other servers. The option --tls-certcheck=off allows msmtp to accept
525 any certificate, so that it can print some information about it.
526 According to the output of this command, the common name of the server
527 certificate issuer is "Thawte Premium Server CA". This means that you
528 have to trust the Thawte CA to use full TLS security. You can download
529 the Thawte CA certificate bundle from http://thawte.com/roots. You get
530 a ZIP file with different certificates. The one you need for the
531 tls_trust_file command is Thawte Server Roots/ThawtePremium‐
532 ServerCA_b64.txt.
533 The following command should now succeed:
534 msmtp --serverinfo --host=smtp.gmail.com --tls=on --port=587 --tls-
535 trust-file="Thawte Server Roots/ThawtePremiumServerCA_b64.txt"
536 Using msmtp with Mutt
539 Create a configuration file for msmtp and add the following lines to
541 your Mutt configuration file:
542 set sendmail="/path/to/msmtp"
543 set use_from=yes
544 set realname="Your Name"
545 set from=you@example.com
546 set envelope_from=yes
547 The envelope_from=yes option lets Mutt use the -f option of msmtp.
548 Therefore msmtp chooses the first account that matches the from address
549 you@example.com.
550 Alternatively, you can use the -a option:
551 set sendmail="/path/to/msmtp -a my-account"
552 Or set everything from the command line:
553 set sendmail="/path/to/msmtp --host=mailhub -f me@example.com --tls"
554 If you have multiple mail accounts in your msmtp configuration file and
556 let Mutt use the -f option to choose the right one, you can easily
557 switch accounts in Mutt with the following Mutt configuration lines:
558 macro generic "<esc>1" ":set from=you@example.com"
559 macro generic "<esc>2" ":set from=you@your-employer.example"
560 macro generic "<esc>3" ":set from=you@some-other-provider.example"
561 Using msmtp with mail
564 Define a default account, and put the following in your ~/.mailrc:
566 set sendmail="/path/to/msmtp"
567
569 SYSCONFDIR/msmtprc
570 System configuration file. Use --version to find out what
571 SYSCONFDIR is on your platform.
572 ~/.msmtprc
574 User configuration file.
575 ~/.netrc
577 The .netrc file contains login information. If a password is not
578 found in the configuration file, msmtp will search it in .netrc
579 before prompting the user for it. The syntax of .netrc is
580 described in netrc(5) or ftp(1).
581 $USER, $LOGNAME
583 These variables override the user's login name when constructing
584 an envelope-from address. $LOGNAME is only used if $USER is
585 unset.
586 $TMPDIR
588 Directory to create temporary files in. If this is unset, a sys‐
589 tem specific default directory is used.
590 A temporary file is only created when the -t/--read-recipients
591 option is used. The file is then used to buffer the headers of
592 the mail (but not the body, so the file won't get very large).
593
595 msmtp was written by Martin Lambers <marlam@marlam.de>.
596 Other authors are listed in the AUTHORS file in the source distribu‐
597 tion.
598
600 mutt(1), mail(1), sendmail(8), netrc(5) or ftp(1)
601 2007-08 MSMTP(1)