Add 2010 to copyright years.

[bpt/emacs.git] / doc / emacs / sending.texi

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002,
@c   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Sending Mail
@chapter Sending Mail
@cindex sending mail
@cindex mail
@cindex message

  To send a message in Emacs, you start by typing a command (@kbd{C-x m})
to select and initialize the @samp{*mail*} buffer.  Then you edit the text
and headers of the message in this buffer, and type another command
(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message.

@table @kbd
@item C-x m
Begin composing a message to send (@code{compose-mail}).
@item C-x 4 m
Likewise, but display the message in another window
(@code{compose-mail-other-window}).
@item C-x 5 m
Likewise, but make a new frame (@code{compose-mail-other-frame}).
@item C-c C-s
In Mail mode, send the message (@code{mail-send}).
@item C-c C-c
Send the message and bury the mail buffer (@code{mail-send-and-exit}).
@end table

@kindex C-x m
@findex compose-mail
@kindex C-x 4 m
@findex compose-mail-other-window
@kindex C-x 5 m
@findex compose-mail-other-frame
  The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named
@samp{*mail*} and initializes it with the skeleton of an outgoing
message.  @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the
@samp{*mail*} buffer in a different window, leaving the previous current
buffer visible.  @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates
a new frame to select the @samp{*mail*} buffer.

  Because the mail-composition buffer is an ordinary Emacs buffer, you can
switch to other buffers while in the middle of composing mail, and switch
back later (or never).  If you use the @kbd{C-x m} command again when you
have been composing another message but have not sent it, you are asked to
confirm before the old message is erased.  If you answer @kbd{n}, the
@samp{*mail*} buffer remains selected with its old contents, so you can
finish the old message and send it.  @kbd{C-u C-x m} is another way to do
this.  Sending the message marks the @samp{*mail*} buffer ``unmodified,''
which avoids the need for confirmation when @kbd{C-x m} is next used.

  If you are composing a message in the @samp{*mail*} buffer and want to
send another message before finishing the first, rename the
@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc
Buffer}).  Then you can use @kbd{C-x m} or its variants described above
to make a new @samp{*mail*} buffer.  Once you've done that, you can work
with each mail buffer independently.

@vindex mail-default-directory
  The variable @code{mail-default-directory} controls the default
directory for mail buffers, and also says where to put their auto-save
files.

@c Not mentioned: mail-bury-selects-summary.  Really an Rmail feature.

@ignore
@c Commented out because it is not user-oriented;
@c it doesn't say how to do some job.  -- rms.
@cindex directory servers
@cindex LDAP
@cindex PH/QI
@cindex names and addresses
There is an interface to directory servers using various protocols such
as LDAP or the CCSO white pages directory system (PH/QI), described in a
separate manual.  It may be useful for looking up names and addresses.
@xref{Top,,EUDC, eudc, EUDC Manual}.
@end ignore

@menu
* Format: Mail Format.	     Format of the mail being composed.
* Headers: Mail Headers.     Details of some standard mail header fields.
* Aliases: Mail Aliases.     Abbreviating and grouping mail addresses.
* Mode: Mail Mode.	     Special commands for editing mail being composed.
* Amuse: Mail Amusements.    Distracting the NSA; adding fortune messages.
* Methods: Mail Methods.     Using alternative mail-composition methods.
@end menu

@node Mail Format
@section The Format of the Mail Buffer

  In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header
fields} which say who sent it, when, to whom, why, and so on.  Some
header fields, such as @samp{Date} and @samp{Message-Id}, are created
automatically when you send the message.  Others, such as the recipient
names, must be specified by you in order to send the message properly.

  In the mail buffer, you can insert and edit header fields using
ordinary editing commands.  Mail mode provides commands to help you
edit some header fields, and some are automatically preinitialized in
the buffer, when appropriate.

@vindex mail-header-separator
  The line in the buffer that says

@example
--text follows this line--
@end example

@noindent
is a special delimiter that separates the headers you have specified from
the text.  Whatever follows this line is the text of the message; the
headers precede it.  The delimiter line itself does not appear in the
message actually sent.  The text used for the delimiter line is controlled
by the variable @code{mail-header-separator}.

  Here is an example of what the headers and text in the mail buffer
might look like.

@example
To: gnu@@gnu.org
CC: lungfish@@spam.org, byob@@spam.org
Subject: The Emacs Manual
--text follows this line--
Please ignore this message.
@end example

@node Mail Headers
@section Mail Header Fields
@cindex headers (of mail message)

  A header field in the mail buffer starts with a field name at the
beginning of a line, terminated by a colon.  Upper and lower case are
equivalent in field names (and in mailing addresses also).  After the
colon and optional whitespace comes the contents of the field.

  You can use any name you like for a header field, but normally people
use only standard field names with accepted meanings.  Here is a table
of fields commonly used in outgoing messages.  Emacs preinitializes some
of these when you start to compose a mail, depending on various options
you can set.  You can delete or alter any header field before you send
the message, if you wish.

@table @samp
@item To
This field contains the mailing addresses to which the message is
addressed.  If you list more than one address, use commas, not spaces,
to separate them.

@item Subject
The contents of the @samp{Subject} field should be a piece of text
that says what the message is about.  The reason @samp{Subject} fields
are useful is that most mail-reading programs can provide a summary of
messages, listing the subject of each message but not its text.

@item CC
This field contains additional mailing addresses to send the message to,
like @samp{To} except that these readers should not regard the message
as directed at them.

@item BCC
This field contains additional mailing addresses to send the message to,
which should not appear in the header of the message actually sent.
Copies sent this way are called @dfn{blind carbon copies}.

@vindex mail-self-blind
@cindex copy of every outgoing message
To send a blind carbon copy of every outgoing message to yourself, set
the variable @code{mail-self-blind} to @code{t}.  To send a blind carbon
copy of every message to some other @var{address}, set the variable
@code{mail-default-headers} to @code{"Bcc: @var{address}\n"}.

@item FCC
This field contains the name of one file and directs Emacs to append a
copy of the message to that file when you send the message.  Emacs
writes the message in mbox format, unless the file is in Babyl format
(used by Rmail before Emacs 23), in which case Emacs writes Babyl.  If
an Rmail buffer is visiting the file, Emacs updates it accordingly.
To specify more than one file, use several @samp{FCC} fields, with one
file name in each field.

@vindex mail-archive-file-name
To put a fixed file name in the @samp{FCC} field each time you start
editing an outgoing message, set the variable
@code{mail-archive-file-name} to that file name.  Unless you remove the
@samp{FCC} field before sending, the message will be written into that
file when it is sent.

@item From
Use the @samp{From} field to say who you are.  You might need to change
this if the account you are using to send the mail is not your own.  The
contents of the @samp{From} field should be a valid mailing address,
since replies will normally go there.  

@vindex mail-setup-with-from
Emacs initializes this field (unless the variable
@code{mail-setup-with-from} is @code{nil}) using
@code{user-mail-address} as the default.  If there is no @samp{From}
field when you send a mail, Emacs adds one.

@item Reply-to
Use this field to direct replies to a different address.  Most
mail-reading programs (including Rmail) automatically send replies to
the @samp{Reply-to} address in preference to the @samp{From} address.
By adding a @samp{Reply-to} field to your header, you can work around
any problems your @samp{From} address may cause for replies.

@cindex @env{REPLYTO} environment variable
@vindex mail-default-reply-to
To put a fixed @samp{Reply-to} address into every outgoing message, set
the variable @code{mail-default-reply-to} to that address (as a string).
Then Emacs initializes the message with a @samp{Reply-to} field as
specified.  When you first compose a mail, if
@code{mail-default-reply-to} is @code{nil}, Emacs initializes it from the
environment variable @env{REPLYTO}.

@item Mail-reply-to
  This field takes precedence over @samp{Reply-to}.  It is used because
some mailing lists set the @samp{Reply-to} field for their own purposes
(a somewhat controversial practice).

@item Mail-followup-to
  This field contains one or more addresses.  It is typically used when
you reply to a message from a mailing list that you are subscribed to.
It usually indicates that you want replies to go to the list, and that
you do not need an extra copy sent directly to you.

@vindex mail-mailing-lists
  The variable @code{mail-mailing-lists} holds a list of mailing list
addresses that you are subscribed to.  If it is non-@code{nil}, Emacs
inserts an appropriate @samp{Mail-followup-to} header when sending mail
to a mailing list.

@c There is also "Sent-via", added by C-c C-v, but it does not seem
@c particularly useful (?).

@item In-reply-to
This field contains a piece of text describing the message you are
replying to.  Some mail systems can use this information to correlate
related pieces of mail.  Normally this field is filled in by Rmail
when you reply to a message in Rmail, and you never need to
think about it (@pxref{Rmail}).

@item References
This field lists the Message-Ids of related previous messages (a
Message-Id is a unique identifier generated when a message is sent).
Rmail sets up this field automatically when you reply to a message.
@end table

  The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear
any number of times, and each such header field can contain multiple
addresses, separated by commas.  This way, you can specify any number
of places to send the message.  These fields can also have
continuation lines: one or more lines starting with whitespace,
following the starting line of the field, are considered part of the
field.  Here's an example of a @samp{To} field with a continuation
line:

@example
@group
To: foo@@here.net, this@@there.net,
  me@@gnu.cambridge.mass.usa.earth.spiral3281
@end group
@end example

@vindex mail-from-style
  When you send the message, if you didn't write a @samp{From} field
yourself, Emacs puts in one for you, using @code{user-mail-address}.
The variable @code{mail-from-style} controls the format:

@table @code
@item nil
Use just the email address, as in @samp{king@@grassland.com}.
@item parens
Use both email address and full name, as in:@*
@samp{king@@grassland.com (Elvis Parsley)}.
@item angles
Use both email address and full name, as in:@*
@samp{Elvis Parsley <king@@grassland.com>}.
@item system-default
Allow the system to insert the @samp{From} field.
@end table

@c There is also mail-specify-envelope-from and mail-envelope-from, but
@c these are probably not topics for the Emacs manual.

@vindex mail-default-headers
  You can direct Emacs to insert certain default headers into the
outgoing message by setting the variable @code{mail-default-headers}
to a string.  Then @code{C-x m} inserts this string into the message
headers.  If the default header fields are not appropriate for a
particular message, edit them as necessary before sending the message.

@node Mail Aliases
@section Mail Aliases
@cindex mail aliases
@cindex @file{.mailrc} file
@cindex mailrc file

  You can define @dfn{mail aliases} in a file named @file{~/.mailrc}.
These are short mnemonic names which stand for mail addresses or groups of
mail addresses.  Like many other mail programs, Emacs expands aliases
when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and
@samp{Reply-to} fields, plus their @samp{Resent-} variants.
@c The list is defined by mail-address-field-regexp.

  To define an alias in @file{~/.mailrc}, write a line in the following
format:

@example
alias @var{shortaddress} @var{fulladdresses}
@end example

@noindent
Here @var{fulladdresses} stands for one or more mail addresses for
@var{shortaddress} to expand into.  Separate multiple addresses with
spaces; if an address contains a space, quote the whole address with a
pair of double quotes.

For instance, to make @code{maingnu} stand for
@code{gnu@@gnu.org} plus a local address of your own, put in
this line:@refill

@example
alias maingnu gnu@@gnu.org local-gnu
@end example

@noindent
Addresses specified in this way should use double quotes around an
entire address when the address contains spaces.  But you need not
include double quotes around parts of the address, such as the person's
full name.  Emacs puts them in if they are needed.  For example,

@example
alias jsmith "John Q. Smith <none@@example.com>"
@end example

@noindent
is correct in @samp{.mailrc}.  Emacs will insert the address as
@samp{"John Q. Smith" <none@@example.com>}.

  Emacs also recognizes ``include'' commands in @samp{.mailrc} files.
They look like this:

@example
source @var{filename}
@end example

@noindent
The file @file{~/.mailrc} is used primarily by other mail-reading
programs; it can contain various other commands.  Emacs ignores
everything in it except for alias definitions and include commands.

@findex define-mail-alias
  Another way to define a mail alias, within Emacs alone, is with the
@code{define-mail-alias} command.  It prompts for the alias and then the
full address.  You can use it to define aliases in your @file{.emacs}
file, like this:

@example
(define-mail-alias "maingnu" "gnu@@gnu.org")
@end example

@vindex mail-aliases
  @code{define-mail-alias} records aliases by adding them to a
variable named @code{mail-aliases}.  If you are comfortable with
manipulating Lisp lists, you can set @code{mail-aliases} directly.  The
initial value of @code{mail-aliases} is @code{t}, which means that
Emacs should read @file{.mailrc} to get the proper value.

@vindex mail-personal-alias-file
  You can specify a different file name to use instead of
@file{~/.mailrc} by setting the variable
@code{mail-personal-alias-file}.

@c There is also mail-alias-file for the system aliases.

@findex expand-mail-aliases
  Normally, Emacs expands aliases when you send the message.  You do not
need to expand mail aliases before sending the message, but you can
expand them if you want to see where the mail will actually go.  To do
this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail
aliases currently present in the mail headers that hold addresses.

  If you like, you can have mail aliases expand as abbrevs, as soon as
you type them in (@pxref{Abbrevs}).  To enable this feature, execute the
following:

@example
(add-hook 'mail-mode-hook 'mail-abbrevs-setup)
@end example

@noindent
@findex define-mail-abbrev
@vindex mail-abbrevs
This can go in your @file{.emacs} file.  @xref{Hooks}.  If you use this
feature, you must use @code{define-mail-abbrev} instead of
@code{define-mail-alias}; the latter does not work with this package.
Note that the mail abbreviation package uses the variable
@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias
names are converted to lower case.

@kindex C-c C-a @r{(Mail mode)}
@findex mail-abbrev-insert-alias
  The mail abbreviation package also provides the @kbd{C-c C-a}
(@code{mail-abbrev-insert-alias}) command, which reads an alias
name (with completion) and inserts its definition at point.  This is
useful when editing the message text itself or a header field such as
@samp{Subject} in which Emacs does not normally expand aliases.

  Note that abbrevs expand only if you insert a word-separator character
afterward.  However, you can rebind @kbd{C-n} and @kbd{M->} to cause
expansion as well.  Here's how to do that:

@smallexample
(add-hook 'mail-mode-hook
    (lambda ()
      (define-key
        mail-mode-map [remap next-line] 'mail-abbrev-next-line)
      (define-key
        mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer)))
@end smallexample

@node Mail Mode
@section Mail Mode
@cindex Mail mode
@cindex mode, Mail

  The major mode used in the mail buffer is Mail mode, which is much
like Text mode except that various special commands are provided on the
@kbd{C-c} prefix.  These commands all have to do specifically with
editing or sending the message. 

  Mail mode is normally used in buffers set up automatically by the
@code{mail} command and related commands.  However, you can also switch
to Mail mode in a file-visiting buffer.  This is a useful thing to do if
you have saved the text of a draft message in a file.

@menu
* Mail Sending::        Commands to send the message.
* Header Editing::      Commands to move to header fields and edit them.
* Citing Mail::         Copying all or part of a message you are replying to.
* Mail Mode Misc::      Spell checking, signatures, etc.
@end menu

@node Mail Sending
@subsection Mail Sending

  Mail mode has two commands for sending the message you have been
editing:

@table @kbd
@item C-c C-s
Send the message, and leave the mail buffer selected (@code{mail-send}).
@item C-c C-c
Send the message, and select some other buffer (@code{mail-send-and-exit}).
@end table

@kindex C-c C-s @r{(Mail mode)}
@kindex C-c C-c @r{(Mail mode)}
@findex mail-send
@findex mail-send-and-exit
@vindex mail-send-hook
  @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail
buffer unmodified, but leaves that buffer selected so that you can
modify the message (perhaps with new recipients) and send it again.
@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the
window or switches to another buffer.  It puts the mail buffer at the
lowest priority for reselection by default, since you are finished with
using it.  This is the usual way to send the message.  Sending a message
runs the hook @code{mail-send-hook}.

@c Options not mentioned: mail-interactive, mail-use-dsn.

  In a file-visiting buffer, sending the message does not clear the
modified flag, because only saving the file should do that.  Also, you
don't get a warning if you try to send the same message twice.

@c This is indexed in mule.texi, node "Recognize Coding".
@c @vindex sendmail-coding-system
  When you send a message that contains non-@acronym{ASCII} characters, they need
to be encoded with a coding system (@pxref{Coding Systems}).  Usually
the coding system is specified automatically by your chosen language
environment (@pxref{Language Environments}).  You can explicitly specify
the coding system for outgoing mail by setting the variable
@code{sendmail-coding-system} (@pxref{Recognize Coding}).

  If the coding system thus determined does not handle the characters in
a particular message, Emacs asks you to select the coding system to use,
showing a list of possible coding systems.

@c Not mentioned: mail-send-nonascii.

@cindex SMTP
@cindex Feedmail
@cindex Sendmail
@cindex Mailclient
@vindex send-mail-function
  The variable @code{send-mail-function} controls how the default mail
user agent sends mail.  It should be set to a function.  In most cases,
the default is @code{sendmail-send-it}, which delivers mail using the
Sendmail installation on the local host.  On Mac OS X and MS-Windows,
however, the default is normally @code{mailclient-send-it}, which
passes the mail buffer on to the system's designated mail client (see
@file{mailclient.el}).  To send mail through an SMTP server, set
@code{send-mail-function} to @code{smtpmail-send-it} and set up the
Emacs SMTP library (@pxref{Top,,Emacs SMTP Library, smtpmail, Sending
mail via SMTP}).  Another option is @code{feedmail-send-it} (see the
commentary section of the @file{feedmail.el} package).

@node Header Editing
@subsection Mail Header Editing

  Mail mode provides special commands to move to particular header
fields and to complete addresses in headers.

@table @kbd
@item C-c C-f C-t
Move to the @samp{To} header field, creating one if there is none
(@code{mail-to}).
@item C-c C-f C-s
Move to the @samp{Subject} header field, creating one if there is
none (@code{mail-subject}).
@item C-c C-f C-c
Move to the @samp{CC} header field, creating one if there is none
(@code{mail-cc}).
@item C-c C-f C-b
Move to the @samp{BCC} header field, creating one if there is none
(@code{mail-bcc}).
@item C-c C-f C-r
Move to the @samp{Reply-To} header field, creating one if there is none
(@code{mail-reply-to}).
@item C-c C-f C-a
Move to the @samp{Mail-Reply-To} header field, creating one if there is none
(@code{mail-mail-reply-to}).
@item C-c C-f C-l
Move to the @samp{Mail-Followup-To} header field, creating one if there is none
(@code{mail-mail-followup-to}).
@item C-c C-f C-f
Add a new @samp{FCC} header field, with file-name completion
(@code{mail-fcc}).
@c There is also C-c C-v, mail-sent-via, which adds one or more
@c "Sent-via" headers, but I don't know what the point of that header is.
@item M-@key{TAB}
Complete a mailing address (@code{mail-complete}).
@end table

@kindex C-c C-f C-t @r{(Mail mode)}
@findex mail-to
@kindex C-c C-f C-s @r{(Mail mode)}
@findex mail-subject
@kindex C-c C-f C-c @r{(Mail mode)}
@findex mail-cc
@kindex C-c C-f C-b @r{(Mail mode)}
@findex mail-bcc
@kindex C-c C-f C-r @r{(Mail mode)}
@findex mail-reply-to
@kindex C-c C-f C-a @r{(Mail mode)}
@findex mail-mail-reply-to
@kindex C-c C-f C-l @r{(Mail mode)}
@findex mail-mail-followup-to
@kindex C-c C-f C-f @r{(Mail mode)}
@findex mail-fcc
  There are several commands to move point to particular header fields,
all based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field'').
They are listed in the table above.  If the field in question does not
exist, these commands create one (the exception is @code{mail-fcc},
which creates a new field each time).  We provide special motion
commands for these particular fields because they are the fields users
most often want to edit.

@findex mail-complete
@kindex M-TAB @r{(Mail mode)}
@c `mail-complete-alist' specifies the headers.
  While editing a header field that contains mailing addresses, such
as @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing
address by typing @kbd{M-@key{TAB}} (@code{mail-complete}).  It
inserts the full name corresponding to the address, if it can
determine the full name.  The variable @code{mail-complete-style}
controls whether to insert the full name, and what style to use, as in
@code{mail-from-style} (@pxref{Mail Headers}).  (If your window
manager defines @kbd{M-@key{TAB}} to switch windows, you can type
@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.)

  For completion purposes, the valid mailing addresses are taken to be
the local users' names plus your personal mail aliases (@pxref{Mail
Aliases}).  You can specify additional sources of valid addresses;
browse the customization group @samp{mailalias} to see the variables for
customizing this feature (@pxref{Customization Groups}).

  If you type @kbd{M-@key{TAB}} in the body of the message, or on a
unrecognized header, @code{mail-complete} invokes the function specified
by @code{mail-complete-function}.  By default, this is
@code{ispell-complete-word}, as in Text mode.

@node Citing Mail
@subsection Citing Mail
@cindex citing mail

  Mail mode also has commands for yanking or @dfn{citing} all or part of
a message that you are replying to.  These commands are active only when
you started sending a message using an Rmail command.

@table @kbd
@item C-c C-y
Yank the selected message from Rmail (@code{mail-yank-original}).
@item C-c C-r
Yank the region from the Rmail buffer (@code{mail-yank-region}).
@item C-c C-q
Fill each paragraph cited from another message
(@code{mail-fill-yanked-message}).
@c There is also mail-split-line, but it does not seem very useful.
@end table

@kindex C-c C-y @r{(Mail mode)}
@findex mail-yank-original
  When mail sending is invoked from the Rmail mail reader using an Rmail
command, @kbd{C-c C-y} can be used inside the mail buffer to insert the
text of the message you are replying to.  Normally it indents each line
of that message three spaces and eliminates most header fields (as
specified by the variable @code{mail-yank-ignored-headers}).  A numeric
argument specifies the number of spaces to indent (the variable
@code{mail-indentation-spaces} specifies the default number).  An
argument of just @kbd{C-u} says not to indent at all and not to
eliminate anything.  @kbd{C-c C-y} always uses the current message from
the Rmail buffer, so you can insert several old messages by selecting
one in Rmail, switching to @samp{*mail*} and yanking it, then switching
back to Rmail to select another.

@vindex mail-yank-prefix
  You can specify the text for @kbd{C-c C-y} to insert at the beginning
of each line: set @code{mail-yank-prefix} to the desired string.  (A
value of @code{nil} means to use indentation; this is the default.)
However, @kbd{C-u C-c C-y} never adds anything at the beginning of the
inserted lines, regardless of the value of @code{mail-yank-prefix}.

@kindex C-c C-r @r{(Mail mode)}
@findex mail-yank-region
  To yank just a part of an incoming message, set the region in Rmail to
the part you want; then go to the @samp{*Mail*} message and type
@kbd{C-c C-r} (@code{mail-yank-region}).  Each line that is copied is
indented or prefixed according to @code{mail-yank-prefix}.

@kindex C-c C-q @r{(Mail mode)}
@findex mail-fill-yanked-message
  After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q}
(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked
old message or messages.  One use of @kbd{C-c C-q} fills all such
paragraphs, each one individually.  To fill a single paragraph of the
quoted message, use @kbd{M-q}.  If filling does not automatically
handle the type of citation prefix you use, try setting the fill prefix
explicitly.  @xref{Filling}.

@vindex mail-citation-hook
  You can customize mail citation through the hook
@code{mail-citation-hook}.  For example, you can use the Supercite
package, which provides more flexible citation
(@pxref{Introduction,,,sc, Supercite}).

@c No need to mention: mail-citation-prefix-regexp.

@node Mail Mode Misc
@subsection Mail Mode Miscellany

@table @kbd
@item C-c C-t
Move to the beginning of the message body text (@code{mail-text}).
@item C-c C-w
Insert a signature at the end of the message text (@code{mail-signature}).
@item C-c C-i @var{file} @key{RET}
Insert the contents of @var{file} at the end of the message text
(@code{mail-attach-file}).
@item M-x ispell-message
Perform spelling correction on the message text, but not on citations from
other messages, or the message headers.
@end table

@kindex C-c C-t @r{(Mail mode)}
@findex mail-text
  @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header
separator line---that is, to the beginning of the message body text.

@kindex C-c C-w @r{(Mail mode)}
@findex mail-signature
@vindex mail-signature
  @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text
(your @dfn{mail signature}) at the end of the message to say more about who
you are.  For example, it may contain telephone numbers, or your
physical location.  The text comes from the variable
@code{mail-signature}.  It can be a fixed string, or a Lisp expression
that returns a string.  If it is @code{t} or @code{nil}, the function
inserts the contents of the file @code{mail-signature-file}.  By
default, this is the file @file{~/.signature} in your home directory.

  If the variable @code{mail-signature} has a non-@code{nil} value,
starting a mail automatically inserts your signature.  Otherwise, you
must explicitly use the command @code{mail-signature}.  If you want to
omit your signature from a particular message, just delete it from the
buffer before you send the message.

  Convention says that the start of your signature should be marked by a
line whose contents are @samp{-- }.  If your signature comes from a
file, this prefix is added for you, but in all other cases you must add
it yourself.  The remainder of your signature should be no more than
four lines.

@findex ispell-message
  You can do spelling correction on the message text you have written
with the command @kbd{M-x ispell-message}.  If you have yanked an
incoming message into the outgoing draft, this command skips what was
yanked, but it checks the text that you yourself inserted.  (It looks
for indentation or @code{mail-yank-prefix} to distinguish the cited
lines from your input.)  @xref{Spelling}.

@kindex C-c C-i @r{(Mail mode)}
@findex mail-attach-file
  To include a file in the outgoing message, you can use @kbd{C-x i},
the usual command to insert a file in the current buffer.  But it is
often more convenient to use a special command, @kbd{C-c C-i}
(@code{mail-attach-file}).  This command inserts the file contents at
the end of the buffer, after your signature (if any), with a delimiter
line that includes the file name.  Note that this is not a MIME
attachment.

@vindex mail-mode-hook
@vindex mail-setup-hook
  Turning on Mail mode (which @kbd{C-x m} does automatically) runs the
normal hooks @code{text-mode-hook} and @code{mail-mode-hook}.
Initializing a new outgoing message runs the normal hook
@code{mail-setup-hook}; if you want to add special fields to your mail
header or make other changes to the appearance of the mail buffer, use
that hook.  @xref{Hooks}.

  The main difference between these hooks is just when they are
invoked.  Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs
as soon as the @samp{*mail*} buffer is created.  Then the
@code{mail-setup} function inserts the default contents of the buffer.
After these default contents are inserted, @code{mail-setup-hook} runs.

  If you use @kbd{M-x mail} to continue an existing composition,
@code{mail-mode-hook} runs immediately after switching to the
@samp{*mail*} buffer.  If the buffer is unmodified, or if you decide to
erase it and start again, @code{mail-setup-hook} runs after the default
contents are inserted.

@node Mail Amusements
@section Mail Amusements

@findex spook
@cindex NSA
  @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing
mail message.  The keywords are chosen from a list of words that suggest
you are discussing something subversive.

  The idea behind this feature is the suspicion that the
NSA@footnote{The US National Security Agency.} and other intelligence
agencies snoop on all electronic mail messages that contain keywords
suggesting they might find them interesting.  (The agencies say that
they don't, but that's what they @emph{would} say.)  The idea is that if
lots of people add suspicious words to their messages, the agencies will
get so busy with spurious input that they will have to give up reading
it all.  Whether or not this is true, it at least amuses some people.

@findex fortune-to-signature
@cindex fortune cookies
  You can use the @code{fortune} program to put a ``fortune cookie''
message into outgoing mail.  To do this, add
@code{fortune-to-signature} to @code{mail-setup-hook}:

@example
(add-hook 'mail-setup-hook 'fortune-to-signature)
@end example

@noindent
You will probably need to set the variable @code{fortune-file} before
using this.

@node Mail Methods
@section Mail-Composition Methods
@cindex mail-composition methods

@cindex MH mail interface
@cindex Message mode for sending mail
  In this chapter we have described the usual Emacs mode for editing
and sending mail---Mail mode.  Emacs has alternative facilities for
editing and sending mail, including
MH-E and Message mode, not documented in this manual.
@xref{Top,,MH-E,mh-e, The Emacs Interface to MH}.  @xref{Top,,Message,message,
Message Manual}.  You can choose any of them as your preferred method.
The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use
whichever agent you have specified, as do various other Emacs commands
and facilities that send mail.

@vindex mail-user-agent
  To specify your mail-composition method, customize the variable
@code{mail-user-agent}.  Currently legitimate values include
@code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent},
@code{message-user-agent} and @code{gnus-user-agent}.

  If you select a different mail-composition method, the information
in this chapter about the @samp{*mail*} buffer and Mail mode does not
apply; the other methods use a different format of text in a different
buffer, and their commands are different as well.

@vindex read-mail-command
  Similarly, to specify your preferred method for reading mail,
customize the variable @code{read-mail-command}.  The default is
@code{rmail} (@pxref{Rmail}).

@ignore
   arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6
@end ignore