man/smtpmail.texi

   1 \input texinfo  @c -*-texinfo-*-
   2 @setfilename ../info/smtpmail
   3 @settitle Emacs SMTP Library
   4 @syncodeindex vr fn
   5 @copying
   6 Copyright @copyright{} 2003, 2004 Free Software Foundation, Inc.
   7
   8 @quotation
   9 Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.1 or
  11 any later version published by the Free Software Foundation; with no
  12 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
  13 and with the Back-Cover Texts as in (a) below.  A copy of the license
  14 is included in the section entitled ``GNU Free Documentation License''
  15 in the Emacs manual.
  16
  17 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  18 this GNU Manual, like GNU software.  Copies published by the Free
  19 Software Foundation raise funds for GNU development.''
  20
  21 This document is part of a collection distributed under the GNU Free
  22 Documentation License.  If you want to distribute this document
  23 separately from the collection, you can do so by adding a copy of the
  24 license to the document, as described in section 6 of the license.
  25 @end quotation
  26 @end copying
  27
  28 @dircategory Emacs
  29 @direntry
  30 * SMTP: (smtpmail). Emacs library for sending mail via SMTP.
  31 @end direntry
  32
  33 @titlepage
  34 @title{Emacs SMTP Library}
  35 @subtitle{An Emacs package for sending mail via SMTP}
  36 @author{Simon Josefsson, Alex Schroeder}
  37 @page
  38 @vskip 0pt plus 1filll
  39 @insertcopying
  40 @end titlepage
  41
  42 @contents
  43
  44 @ifnottex
  45 @node Top
  46 @top Emacs SMTP Library
  47
  48 @insertcopying
  49 @end ifnottex
  50
  51 @menu
  52 * How Mail Works::      Brief introduction to mail concepts.
  53 * Emacs Speaks SMTP::   How to use the SMTP library in Emacs.
  54 * Authentication::      Authenticating yourself to the server.
  55 * Queued delivery::     Sending mail without an internet connection.
  56 * Server workarounds::  Mail servers with special requirements.
  57 * Debugging::           Tracking down problems.
  58
  59 Indices
  60
  61 * Index::               Index over variables and functions.
  62 @end menu
  63
  64 @node How Mail Works
  65 @chapter How Mail Works
  66
  67 @cindex SMTP
  68 @cindex MTA
  69    On the internet, mail is sent from mail host to mail host using the
  70 simple mail transfer protocol (SMTP).  To send and receive mail, you
  71 must get it from and send it to a mail host.  Every mail host runs a
  72 mail transfer agent (MTA) such as Exim that accepts mails and passes
  73 them on.  The communication between a mail host and other clients does
  74 not necessarily involve SMTP, however.  Here is short overview of what
  75 is involved.
  76
  77 @cindex MUA
  78    The mail program --- also called a mail user agent (MUA) ---
  79 usually sends outgoing mail to a mail host.  When your computer is
  80 permanently connected to the internet, it might even be a mail host
  81 itself.  In this case, the MUA will pipe mail to the
  82 @file{/usr/lib/sendmail} application.  It will take care of your mail
  83 and pass it on to the next mail host.
  84
  85 @cindex ISP
  86    When you are only connected to the internet from time to time, your
  87 internet service provider (ISP) has probably told you which mail host
  88 to use.  You must configure your MUA to use that mail host.  Since you
  89 are reading this manual, you probably want to configure Emacs to use
  90 SMTP to send mail to that mail host.  More on that in the next
  91 section.
  92
  93 @cindex MDA
  94    Things are different when reading mail.  The mail host responsible
  95 for your mail keeps it in a file somewhere.  The messages get into the
  96 file by way of a mail delivery agent (MDA) such as procmail.  These
  97 delivery agents often allow you to filter and munge your mails before
  98 you get to see it.  When your computer is that mail host, this file is
  99 called a spool, and sometimes located in the directory
 100 @file{/var/spool/mail/}.  All your MUA has to do is read mail from the
 101 spool, then.
 102
 103 @cindex POP3
 104 @cindex IMAP
 105    When your computer is not always connected to the internet, you
 106 must get the mail from the remote mail host using a protocol such as
 107 POP3 or IMAP.  POP3 essentially downloads all your mail from the mail
 108 host to your computer.  The mail is stored in some file on your
 109 computer, and again, all your MUA has to do is read mail from the
 110 spool.
 111
 112    When you read mail from various machines, downloading mail from the
 113 mail host to your current machine is not convenient.  In that case,
 114 you will probably want to use the IMAP protocol.  Your mail is kept on
 115 the mail host, and you can read it while you are connected via IMAP to
 116 the mail host.
 117
 118 @cindex Webmail
 119    So how does reading mail via the web work, you ask.  In that case,
 120 the web interface just allows you to remote-control a MUA on the web
 121 host.  Whether the web host is also a mail host, and how all the
 122 pieces interact is completely irrelevant.  You usually cannot use
 123 Emacs to read mail via the web, unless you use software that parses
 124 the ever-changing HTML of the web interface.
 125
 126 @node Emacs Speaks SMTP
 127 @chapter Emacs Speaks SMTP
 128
 129    Emacs includes a package for sending your mail to a SMTP server and
 130 have it take care of delivering it to the final destination, rather
 131 than letting the MTA on your local system take care of it.  This can
 132 be useful if you don't have a MTA set up on your host, or if your
 133 machine is often disconnected from the internet.
 134
 135   Sending mail via SMTP requires configuring your mail user agent
 136 (@pxref{Mail Methods,,,emacs}) to use the SMTP library.  How to do
 137 this should be described for each mail user agent; for the default
 138 mail user agent the variable @code{send-mail-function} (@pxref{Mail
 139 Sending,,,emacs}) is used; for the Message and Gnus user agents the
 140 variable @code{message-send-mail-function} (@pxref{Mail
 141 Variables,,,message}) is used.
 142
 143 @example
 144 ;; If you use the default mail user agent.
 145 (setq send-mail-function 'smtpmail-send-it)
 146 ;; If you use Message or Gnus.
 147 (setq message-send-mail-function 'smtpmail-send-it)
 148 @end example
 149
 150   Before using SMTP you must find out the hostname of the SMTP server
 151 to use.  Your system administrator should provide you with this
 152 information, but often it is the same as the server you receive mail
 153 from.
 154
 155 @table @code
 156 @item smtpmail-smtp-server
 157 @vindex smtpmail-smtp-server
 158 @vindex SMTPSERVER
 159   The variable @code{smtpmail-smtp-server} controls the hostname of
 160 the server to use.  It is a string with an IP address or hostname.  It
 161 defaults to the contents of the @env{SMTPSERVER} environment
 162 variable, or, if empty, the contents of
 163 @code{smtpmail-default-smtp-server}.
 164
 165 @item smtpmail-default-smtp-server
 166 @vindex smtpmail-default-smtp-server
 167   The variable @code{smtpmail-default-smtp-server} controls the
 168 default hostname of the server to use.  It is a string with an IP
 169 address or hostname.  It must be set before the SMTP library is
 170 loaded.  It has no effect if set after the SMTP library has been
 171 loaded, or if @code{smtpmail-smtp-server} is defined.  It is usually
 172 set by system administrators in a site wide initialization file.
 173 @end table
 174
 175 The following example illustrates what you could put in
 176 @file{~/.emacs} to set the SMTP server name.
 177
 178 @example
 179 ;; Send mail using SMTP via mail.example.org.
 180 (setq smtpmail-smtp-server "mail.example.org")
 181 @end example
 182
 183 @cindex Mail Submission
 184 SMTP is normally used on the registered ``smtp'' TCP service port 25.
 185 Some environments use SMTP in ``Mail Submission'' mode, which uses
 186 port 587.  Using other ports is not uncommon, either for security by
 187 obscurity purposes, port forwarding, or otherwise.
 188
 189 @table @code
 190 @item smtpmail-smtp-service
 191 @vindex smtpmail-smtp-service
 192   The variable @code{smtpmail-smtp-service} controls the port on the
 193 server to contact.  It is either a string, in which case it will be
 194 translated into an integer using system calls, or an integer.
 195 @end table
 196
 197 The following example illustrates what you could put in
 198 @file{~/.emacs} to set the SMTP service port.
 199
 200 @example
 201 ;; Send mail using SMTP on the mail submission port 587.
 202 (setq smtpmail-smtp-service 587)
 203 @end example
 204
 205 @node Authentication
 206 @chapter Authentication
 207
 208 @cindex SASL
 209 @cindex CRAM-MD5
 210 @cindex LOGIN
 211 @cindex STARTTLS
 212 Many environments require SMTP clients to authenticate themselves
 213 before they are allowed to route mail via a server.  The two following
 214 variables contains the authentication information needed for this.
 215 The first variable, @code{smtpmail-auth-credentials}, instructs the
 216 SMTP library to use a SASL authentication step, currently only the
 217 CRAM-MD5 and LOGIN mechanisms are supported and will be selected in
 218 that order if the server supports them.  The second variable,
 219 @code{smtpmail-starttls-credentials}, instructs the SMTP library to
 220 connect to the server using STARTTLS.  This means the protocol
 221 exchange can be integrity protected and confidential by using TLS, and
 222 optionally also authentication of the client.  It is common to use
 223 both these mechanisms, e.g., to use STARTTLS to achieve integrity and
 224 confidentiality and then use SASL for client authentication.
 225
 226 @table @code
 227 @item smtpmail-auth-credentials
 228 @vindex smtpmail-auth-credentials
 229   The variable @code{smtpmail-auth-credentials} contains a list of
 230 hostname, port, username and password tuples.  When the SMTP library
 231 connects to a host on a certain port, this variable is searched to
 232 find a matching entry for that hostname and port.  If an entry is
 233 found, the authentication process is invoked and the credentials are
 234 used.  The hostname field follows the same format as
 235 @code{smtpmail-smtp-server} (i.e., a string) and the port field the
 236 same format as @code{smtpmail-smtp-service} (i.e., a string or an
 237 integer).  The username and password fields, which either can be
 238 @code{nil} to indicate that the user is queried for the value
 239 interactively, should be strings with the username and password,
 240 respectively, information that is normally provided by system
 241 administrators.
 242
 243 @item smtpmail-starttls-credentials
 244 @vindex smtpmail-starttls-credentials
 245   The variable @code{smtpmail-starttls-credentials} contains a list of
 246 tuples with hostname, port, name of file containing client key, and
 247 name of file containing client certificate.  The processing is similar
 248 to the previous variable.  The client key and certificate may be
 249 @code{nil} if you do not wish to use client authentication.  The use
 250 of this variable requires the @samp{starttls} external program to be
 251 installed, you can get @file{starttls-*.tar.gz} from
 252 @uref{ftp://ftp.opaopa.org/pub/elisp/}.
 253 @end table
 254
 255 The following example illustrates what you could put in
 256 @file{~/.emacs} to enable both SASL authentication and STARTTLS.  The
 257 server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
 258 server port (@code{smtpmail-smtp-service}) is @var{port}, and the
 259 username and password are @var{username} and @var{password}
 260 respectively.
 261
 262 @example
 263 ;; Authenticate using this username and password against my server.
 264 (setq smtpmail-auth-credentials
 265       '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
 266 ;; Use STARTTLS without authentication against the server.
 267 (setq smtpmail-starttls-credentials
 268       '(("@var{hostname}" "@var{port}" nil nil)))
 269 @end example
 270
 271 @node Queued delivery
 272 @chapter Queued delivery
 273
 274 @cindex Dialup connection
 275 If you connect to the internet via a dialup connection, or for some
 276 other reason don't have permanent internet connection, sending mail
 277 will fail when you are not connected.  The SMTP library implements
 278 queued delivery, and the following variable control its behaviour.
 279
 280 @table @code
 281 @item smtpmail-queue-mail
 282 @vindex smtpmail-queue-mail
 283   The variable @code{smtpmail-queue-mail} controls whether a simple
 284 off line mail sender is active.  This variable is a boolean, and
 285 defaults to @code{nil} (disabled).  If this is non-@code{nil}, mail is
 286 not sent immediately but rather queued in the directory
 287 @code{smtpmail-queue-dir} and can be later sent manually by invoking
 288 @code{smtpmail-send-queued-mail} (typically when you connect to the
 289 internet).
 290
 291 @item smtpmail-queue-dir
 292 @vindex smtpmail-queue-dir
 293   The variable @code{smtpmail-queue-dir} specifies the name of the
 294 directory to hold queued messages.  It defaults to
 295 @file{~/Mail/queued-mail/}.
 296 @end table
 297
 298 @findex smtpmail-send-queued-mail
 299   The function @code{smtpmail-send-queued-mail} can be used to send
 300 any queued mail when @code{smtpmail-queue-mail} is enabled.  It is
 301 typically invoked interactively with @kbd{M-x
 302 smtpmail-send-queued-mail RET} when you are connected to the internet.
 303
 304 @node Server workarounds
 305 @chapter Server workarounds
 306
 307 Some SMTP servers have special requirements.  The following variables
 308 implement support for common requirements.
 309
 310 @table @code
 311
 312 @item smtpmail-local-domain
 313 @vindex smtpmail-local-domain
 314   The variable @code{smtpmail-local-domain} controls the hostname sent
 315 in the first @code{EHLO} or @code{HELO} command sent to the server.
 316 It should only be set if the @code{system-name} function returns a
 317 name that isn't accepted by the server.  Do not set this variable
 318 unless your server complains.
 319
 320 @item smtpmail-sendto-domain
 321 @vindex smtpmail-sendto-domain
 322   The variable @code{smtpmail-sendto-domain} makes the SMTP library
 323 add @samp{@@} and the specified value to recipients specified in the
 324 message when they are sent using the @code{RCPT TO} command.  Some
 325 configurations of sendmail requires this behaviour.  Don't bother to
 326 set this unless you have get an error like:
 327
 328 @example
 329         Sending failed; SMTP protocol error
 330 @end example
 331
 332 when sending mail, and the debug buffer (@pxref{Debugging})) contains
 333 an error such as:
 334
 335 @example
 336         RCPT TO: @var{someone}
 337         501 @var{someone}: recipient address must contain a domain
 338 @end example
 339
 340 @end table
 341
 342
 343 @node Debugging
 344 @chapter Debugging
 345
 346 Sometimes delivery fails, often with the generic error message
 347 @samp{Sending failed; SMTP protocol error}.  Enabling one or both of
 348 the following variables and inspecting a trace buffer will often give
 349 clues to the reason for the error.
 350
 351 @table @code
 352
 353 @item smtpmail-debug-info
 354 @vindex smtpmail-debug-info
 355   The variable @code{smtpmail-debug-info} controls whether to print
 356 the SMTP protocol exchange in the minibuffer, and retain the entire
 357 exchange in a buffer @samp{*trace of SMTP session to @var{server}*},
 358 where @var{server} is the name of the mail server to which you send
 359 mail.
 360
 361 @item smtpmail-debug-verb
 362 @vindex smtpmail-debug-verb
 363   The variable @code{smtpmail-debug-verb} controls whether to send the
 364 @code{VERB} token to the server.  The @code{VERB} server instructs the
 365 server to be more verbose, and often also to attempt final delivery
 366 while your SMTP session is still running.  It is usually only useful
 367 together with @code{smtpmail-debug-info}.  Note that this may cause
 368 mail delivery to take considerable time if the final destination
 369 cannot accept mail.
 370
 371 @end table
 372
 373 @node Index
 374 @chapter Index
 375
 376 @section Concept Index
 377
 378 @printindex cp
 379
 380 @section Function and Variable Index
 381
 382 @printindex fn
 383
 384 @contents
 385 @bye
 386
 387 @ignore
 388    arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f
 389 @end ignore