comparison man/smtpmail.texi @ 52071:25d8603103b7

Fix typos and mark-up (from Jesper Harder <[e-mail]>).

52070:318ea3203ba5

@menu
* How Mail Works::	Brief introduction to mail concepts.
* Emacs Speaks SMTP::   How to use the SMTP library in Emacs.
* Authentication::	Authenticating yourself to the server.
* Queued delivery::	Sending mail without an Internet connection.
* Server workarounds::	Mail servers with special requirements.
* Debugging::		Tracking down problems.

Indices

@node How Mail Works
@chapter How Mail Works

@cindex SMTP
@cindex MTA
   On the Internet, mail is sent from mail host to mail host using the
simple mail transfer protocol (SMTP).  To send and receive mail, you
must get it from and send it to a mail host.  Every mail host runs a
mail transger agent (MTA) such as Exim that accepts mails and passes
them on.  The communication between a mail host and other clients does
not necessarily involve SMTP, however.  Here is short overview of what
is involved.

@cindex MUA

for your mail keeps it in a file somewhere.  The messages get into the
file by way of a mail delivery agent (MDA) such as procmail.  These
delivery agents often allow you to filter and munge your mails before
you get to see it.  When your computer is that mail host, this file is
called a spool, and sometimes located in the directory
/var/spool/mail/.  All your MUA has to do is read mail from the spool,
then.

@cindex POP3
@cindex IMAP
   When your computer is not always connected to the Internet, you
must get the mail from the remote mail host using a protocol such as
POP3 or IMAP.  POP3 essentially downloads all your mail from the mail
host to your computer.  The mail is stored in some file on your
computer, and again, all your MUA has to do is read mail from the
spool.

   Emacs includes a package for sending your mail to a SMTP server and
have it take care of delivering it to the final destination, rather
than letting the MTA on your local system take care of it.  This can
be useful if you don't have a MTA set up on your host, or if your
machine is often disconnected from the Internet.

  Sending mail via SMTP requires configuring your mail user agent
(@pxref{Mail Methods,,,emacs}) to use the SMTP library.  How to do
this should be described for each mail user agent; for the default
mail user agent the variable @code{send-mail-function} (@pxref{Mail

@item smtpmail-smtp-server
@vindex smtpmail-smtp-server
@vindex SMTPSERVER
  The variable @code{smtpmail-smtp-server} controls the hostname of
the server to use.  It is a string with an IP address or hostname.  It
defaults to the contents of the @code{SMTPSERVER} environment
variable, or, if empty, the contents of
@code{smtpmail-default-smtp-server}.

@item smtpmail-default-smtp-server
@vindex smtpmail-default-smtp-server

found, the authentication process is invoked and the credentials are
used.  The hostname field follows the same format as
@code{smtpmail-smtp-server} (i.e., a string) and the port field the
same format as @code{smtpmail-smtp-service} (i.e., a string or an
integer).  The username and password fields, which either can be
@samp{nil} to indicate that the user is queried for the value
interactively, should be strings with the username and password,
respectively, information that is normally provided by system
administrators.

@item smtpmail-starttls-credentials
@vindex smtpmail-starttls-credentials
  The variable @code{smtpmail-starttls-credentials} contains a list of
tuples with hostname, port, name of file containing client key, and
name of file containing client certificate.  The processing is similar
to the previous variable.  The client key and certificate may be
@samp{nil} if you do not wish to use client authentication.  The use
of this variable requires the @samp{starttls} external program to be
installed, you can get @file{starttls-*.tar.gz} from
@uref{ftp://ftp.opaopa.org/pub/elisp/}.
@end table

The following example illustrates what you could put in
@file{~/.emacs} to enable both SASL authentication and STARTTLS.  The
server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
server port (@code{smtpmail-smtp-service}) is @var{port}, and the
username and password are @var{username} and "@var{password}
respectively.

@example
;; Authenticate using this username and password against my server.
(setq smtpmail-auth-credentials

@node Queued delivery
@chapter Queued delivery

@cindex Dialup connection
If you connect to the Internet via a dialup connection, or for some
other reason doesn't have permanent Internet connection, sending mail
will fail when you are not connected.  The SMTP library implements
queued delivery, and the following variable control its behaviour.

@table @code
@item smtpmail-queue-mail
@vindex smtpmail-queue-mail
  The variable @code{smtpmail-queue-mail} controls whether a simple
off line mail sender is active.  This variable is a boolean, and
defaults to @samp{nil} (disabled).  If this is non-nil, mail is not
sent immediately but rather queued in the directory
@code{smtpmail-queue-dir} and can be later sent manually by invoking
@code{smtpmail-send-queued-mail} (typically when you connect to the
Internet).

@item smtpmail-queue-mail
@vindex smtpmail-queue-dir
  The variable @code{smtpmail-queue-dir} specifies the name of the
directory to hold queued messages.  It defaults to
@file{~/Mail/queued-mail/}.
@end table

@findex smtpmail-send-queued-mail
  The function @code{smtpmail-send-queued-mail} can be used to send
any queued mail when @code{smtpmail-queue-mail} is enabled.  It is
typically invoked interactively with @kbd{M-x RET
smtpmail-send-queued-mail RET} when you are connected to the Internet.

@node Server workarounds
@chapter Server workarounds

Some SMTP servers have special requirements.  The following variables

52071:25d8603103b7

@menu
* How Mail Works::	Brief introduction to mail concepts.
* Emacs Speaks SMTP::   How to use the SMTP library in Emacs.
* Authentication::	Authenticating yourself to the server.
* Queued delivery::	Sending mail without an internet connection.
* Server workarounds::	Mail servers with special requirements.
* Debugging::		Tracking down problems.

Indices

@node How Mail Works
@chapter How Mail Works

@cindex SMTP
@cindex MTA
   On the internet, mail is sent from mail host to mail host using the
simple mail transfer protocol (SMTP).  To send and receive mail, you
must get it from and send it to a mail host.  Every mail host runs a
mail transfer agent (MTA) such as Exim that accepts mails and passes
them on.  The communication between a mail host and other clients does
not necessarily involve SMTP, however.  Here is short overview of what
is involved.

@cindex MUA

for your mail keeps it in a file somewhere.  The messages get into the
file by way of a mail delivery agent (MDA) such as procmail.  These
delivery agents often allow you to filter and munge your mails before
you get to see it.  When your computer is that mail host, this file is
called a spool, and sometimes located in the directory
@file{/var/spool/mail/}.  All your MUA has to do is read mail from the
spool, then.

@cindex POP3
@cindex IMAP
   When your computer is not always connected to the internet, you
must get the mail from the remote mail host using a protocol such as
POP3 or IMAP.  POP3 essentially downloads all your mail from the mail
host to your computer.  The mail is stored in some file on your
computer, and again, all your MUA has to do is read mail from the
spool.

   Emacs includes a package for sending your mail to a SMTP server and
have it take care of delivering it to the final destination, rather
than letting the MTA on your local system take care of it.  This can
be useful if you don't have a MTA set up on your host, or if your
machine is often disconnected from the internet.

  Sending mail via SMTP requires configuring your mail user agent
(@pxref{Mail Methods,,,emacs}) to use the SMTP library.  How to do
this should be described for each mail user agent; for the default
mail user agent the variable @code{send-mail-function} (@pxref{Mail

@item smtpmail-smtp-server
@vindex smtpmail-smtp-server
@vindex SMTPSERVER
  The variable @code{smtpmail-smtp-server} controls the hostname of
the server to use.  It is a string with an IP address or hostname.  It
defaults to the contents of the @env{SMTPSERVER} environment
variable, or, if empty, the contents of
@code{smtpmail-default-smtp-server}.

@item smtpmail-default-smtp-server
@vindex smtpmail-default-smtp-server

found, the authentication process is invoked and the credentials are
used.  The hostname field follows the same format as
@code{smtpmail-smtp-server} (i.e., a string) and the port field the
same format as @code{smtpmail-smtp-service} (i.e., a string or an
integer).  The username and password fields, which either can be
@code{nil} to indicate that the user is queried for the value
interactively, should be strings with the username and password,
respectively, information that is normally provided by system
administrators.

@item smtpmail-starttls-credentials
@vindex smtpmail-starttls-credentials
  The variable @code{smtpmail-starttls-credentials} contains a list of
tuples with hostname, port, name of file containing client key, and
name of file containing client certificate.  The processing is similar
to the previous variable.  The client key and certificate may be
@code{nil} if you do not wish to use client authentication.  The use
of this variable requires the @samp{starttls} external program to be
installed, you can get @file{starttls-*.tar.gz} from
@uref{ftp://ftp.opaopa.org/pub/elisp/}.
@end table

The following example illustrates what you could put in
@file{~/.emacs} to enable both SASL authentication and STARTTLS.  The
server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
server port (@code{smtpmail-smtp-service}) is @var{port}, and the
username and password are @var{username} and @var{password}
respectively.

@example
;; Authenticate using this username and password against my server.
(setq smtpmail-auth-credentials

@node Queued delivery
@chapter Queued delivery

@cindex Dialup connection
If you connect to the internet via a dialup connection, or for some
other reason don't have permanent internet connection, sending mail
will fail when you are not connected.  The SMTP library implements
queued delivery, and the following variable control its behaviour.

@table @code
@item smtpmail-queue-mail
@vindex smtpmail-queue-mail
  The variable @code{smtpmail-queue-mail} controls whether a simple
off line mail sender is active.  This variable is a boolean, and
defaults to @code{nil} (disabled).  If this is non-@code{nil}, mail is
not sent immediately but rather queued in the directory
@code{smtpmail-queue-dir} and can be later sent manually by invoking
@code{smtpmail-send-queued-mail} (typically when you connect to the
internet).

@item smtpmail-queue-dir
@vindex smtpmail-queue-dir
  The variable @code{smtpmail-queue-dir} specifies the name of the
directory to hold queued messages.  It defaults to
@file{~/Mail/queued-mail/}.
@end table

@findex smtpmail-send-queued-mail
  The function @code{smtpmail-send-queued-mail} can be used to send
any queued mail when @code{smtpmail-queue-mail} is enabled.  It is
typically invoked interactively with @kbd{M-x
smtpmail-send-queued-mail RET} when you are connected to the internet.

@node Server workarounds
@chapter Server workarounds

Some SMTP servers have special requirements.  The following variables