1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Sending Mail, Rmail, Picture, Top
11 To send a message in Emacs, you start by typing a command (@kbd{C-x m})
12 to select and initialize the @samp{*mail*} buffer. Then you edit the text
13 and headers of the message in this buffer, and type another command
14 (@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message.
18 Begin composing a message to send (@code{compose-mail}).
20 Likewise, but display the message in another window
21 (@code{compose-mail-other-window}).
23 Likewise, but make a new frame (@code{compose-mail-other-frame}).
25 In Mail mode, send the message (@code{mail-send}).
27 Send the message and bury the mail buffer (@code{mail-send-and-exit}).
33 @findex compose-mail-other-window
35 @findex compose-mail-other-frame
36 The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named
37 @samp{*mail*} and initializes it with the skeleton of an outgoing
38 message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the
39 @samp{*mail*} buffer in a different window, leaving the previous current
40 buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates
41 a new frame to select the @samp{*mail*} buffer.
43 Because the mail-composition buffer is an ordinary Emacs buffer, you can
44 switch to other buffers while in the middle of composing mail, and switch
45 back later (or never). If you use the @kbd{C-x m} command again when you
46 have been composing another message but have not sent it, you are asked to
47 confirm before the old message is erased. If you answer @kbd{n}, the
48 @samp{*mail*} buffer is left selected with its old contents, so you can
49 finish the old message and send it. @kbd{C-u C-x m} is another way to do
50 this. Sending the message marks the @samp{*mail*} buffer ``unmodified,''
51 which avoids the need for confirmation when @kbd{C-x m} is next used.
53 If you are composing a message in the @samp{*mail*} buffer and want to
54 send another message before finishing the first, rename the
55 @samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc
56 Buffer}). Then you can use @kbd{C-x m} or its variants described above
57 to make a new @samp{*mail*} buffer. Once you've done that, you can work
58 with each mail buffer independently.
61 @c Commented out because it is not user-oriented;
62 @c it doesn't say how to do some job. -- rms.
63 @cindex directory servers
66 @cindex names and addresses
67 There is an interface to directory servers using various protocols such
68 as LDAP or the CCSO white pages directory system (PH/QI), described in a
69 separate manual. It may be useful for looking up names and addresses.
70 @xref{Top,,EUDC, eudc, EUDC Manual}.
74 * Format: Mail Format. Format of the mail being composed.
75 * Headers: Mail Headers. Details of permitted mail header fields.
76 * Aliases: Mail Aliases. Abbreviating and grouping mail addresses.
77 * Mode: Mail Mode. Special commands for editing mail being composed.
78 * Amuse: Mail Amusements. Distracting the NSA; adding fortune messages.
79 * Methods: Mail Methods. Using alternative mail-composition methods.
83 @section The Format of the Mail Buffer
85 In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header
86 fields} which say who sent it, when, to whom, why, and so on. Some
87 header fields, such as @samp{Date} and @samp{Sender}, are created
88 automatically when you send the message. Others, such as the recipient
89 names, must be specified by you in order to send the message properly.
91 Mail mode provides a few commands to help you edit some header fields,
92 and some are preinitialized in the buffer automatically at times. You can
93 insert and edit header fields using ordinary editing commands.
95 The line in the buffer that says
98 --text follows this line--
102 is a special delimiter that separates the headers you have specified from
103 the text. Whatever follows this line is the text of the message; the
104 headers precede it. The delimiter line itself does not appear in the
105 message actually sent. The text used for the delimiter line is controlled
106 by the variable @code{mail-header-separator}.
108 Here is an example of what the headers and text in the mail buffer
113 CC: lungfish@@spam.org, byob@@spam.org
114 Subject: The Emacs Manual
115 --Text follows this line--
116 Please ignore this message.
120 @section Mail Header Fields
121 @cindex headers (of mail message)
123 A header field in the mail buffer starts with a field name at the
124 beginning of a line, terminated by a colon. Upper and lower case are
125 equivalent in field names (and in mailing addresses also). After the
126 colon and optional whitespace comes the contents of the field.
128 You can use any name you like for a header field, but normally people
129 use only standard field names with accepted meanings. Here is a table
130 of fields commonly used in outgoing messages.
134 This field contains the mailing addresses to which the message is
135 addressed. If you list more than one address, use commas, not spaces,
139 The contents of the @samp{Subject} field should be a piece of text
140 that says what the message is about. The reason @samp{Subject} fields
141 are useful is that most mail-reading programs can provide a summary of
142 messages, listing the subject of each message but not its text.
145 This field contains additional mailing addresses to send the message to,
146 like @samp{To} except that these readers should not regard the message
150 This field contains additional mailing addresses to send the message to,
151 which should not appear in the header of the message actually sent.
152 Copies sent this way are called @dfn{blind carbon copies}.
154 @vindex mail-self-blind
155 @cindex copy of every outgoing message
156 To send a blind carbon copy of every outgoing message to yourself, set
157 the variable @code{mail-self-blind} to @code{t}. To send a blind carbon
158 copy of every message to some other @var{address}, set the variable
159 @code{mail-default-headers} to @code{"Bcc: @var{address}\n"}.
162 This field contains the name of one file and directs Emacs to append a
163 copy of the message to that file when you send the message. If the file
164 is in Rmail format, Emacs writes the message in Rmail format; otherwise,
165 Emacs writes the message in system mail file format.
167 @vindex mail-archive-file-name
168 To put a fixed file name in the @samp{FCC} field each time you start
169 editing an outgoing message, set the variable
170 @code{mail-archive-file-name} to that file name. Unless you remove the
171 @samp{FCC} field before sending, the message will be written into that
172 file when it is sent.
175 Use the @samp{From} field to say who you are, when the account you are
176 using to send the mail is not your own. The contents of the @samp{From}
177 field should be a valid mailing address, since replies will normally go
178 there. If you don't specify the @samp{From} field yourself, Emacs uses
179 the value of @code{user-mail-address} as the default.
182 Use this field to direct replies to a different address. Most
183 mail-reading programs (including Rmail) automatically send replies to
184 the @samp{Reply-to} address in preference to the @samp{From} address.
185 By adding a @samp{Reply-to} field to your header, you can work around
186 any problems your @samp{From} address may cause for replies.
188 @cindex @env{REPLYTO} environment variable
189 @vindex mail-default-reply-to
190 To put a fixed @samp{Reply-to} address into every outgoing message, set
191 the variable @code{mail-default-reply-to} to that address (as a string).
192 Then @code{mail} initializes the message with a @samp{Reply-to} field as
193 specified. You can delete or alter that header field before you send
194 the message, if you wish. When Emacs starts up, if the environment
195 variable @env{REPLYTO} is set, @code{mail-default-reply-to} is
196 initialized from that environment variable.
199 This field contains a piece of text describing a message you are
200 replying to. Some mail systems can use this information to correlate
201 related pieces of mail. Normally this field is filled in by Rmail
202 when you reply to a message in Rmail, and you never need to
203 think about it (@pxref{Rmail}).
206 This field lists the message IDs of related previous messages. Rmail
207 sets up this field automatically when you reply to a message.
210 The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} header fields can
211 appear any number of times, and each such header field can contain
212 multiple addresses, separated by commas. This way, you can specify any
213 number of places to send the message. A @samp{To}, @samp{CC}, or
214 @samp{BCC} field can also have continuation lines: one or more lines
215 starting with whitespace, following the starting line of the field, are
216 considered part of the field. Here's an example of a @samp{To} field
217 with a continuation line:@refill
221 To: foo@@here.net, this@@there.net,
222 me@@gnu.cambridge.mass.usa.earth.spiral3281
226 @vindex mail-from-style
227 When you send the message, if you didn't write a @samp{From} field
228 yourself, Emacs puts in one for you. The variable
229 @code{mail-from-style} controls the format:
233 Use just the email address, as in @samp{king@@grassland.com}.
235 Use both email address and full name, as in @samp{king@@grassland.com (Elvis
238 Use both email address and full name, as in @samp{Elvis Parsley
239 <king@@grassland.com>}.
241 Allow the system to insert the @samp{From} field.
244 @vindex mail-default-headers
245 You can direct Emacs to insert certain default headers into the
246 outgoing message by setting the variable @code{mail-default-headers}
247 to a string. Then @code{C-x m} inserts this string into the message
248 headers. If the default header fields are not appropriate for a
249 particular message, edit them as appropriate before sending the
253 @section Mail Aliases
255 @cindex @file{.mailrc} file
258 You can define @dfn{mail aliases} in a file named @file{~/.mailrc}.
259 These are short mnemonic names which stand for mail addresses or groups of
260 mail addresses. Like many other mail programs, Emacs expands aliases
261 when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and
262 @samp{Reply-to} fields, plus their @samp{Resent-} variants.
264 To define an alias in @file{~/.mailrc}, write a line in the following
268 alias @var{shortaddress} @var{fulladdresses}
272 Here @var{fulladdresses} stands for one or more mail addresses for
273 @var{shortaddress} to expand into. Separate multiple addresses with
274 spaces; if an address contains a space, quote the whole address with a
275 pair of double-quotes.
277 For instance, to make @code{maingnu} stand for
278 @code{gnu@@gnu.org} plus a local address of your own, put in
282 alias maingnu gnu@@gnu.org local-gnu
285 Emacs also recognizes include commands in @samp{.mailrc} files.
289 source @var{filename}
293 The file @file{~/.mailrc} is used primarily by other mail-reading
294 programs; it can contain various other commands. Emacs ignores
295 everything in it except for alias definitions and include commands.
297 @findex define-mail-alias
298 Another way to define a mail alias, within Emacs alone, is with the
299 @code{define-mail-alias} command. It prompts for the alias and then the
300 full address. You can use it to define aliases in your @file{.emacs}
304 (define-mail-alias "maingnu" "gnu@@gnu.org")
308 @code{define-mail-alias} records aliases by adding them to a
309 variable named @code{mail-aliases}. If you are comfortable with
310 manipulating Lisp lists, you can set @code{mail-aliases} directly. The
311 initial value of @code{mail-aliases} is @code{t}, which means that
312 Emacs should read @file{.mailrc} to get the proper value.
314 @vindex mail-personal-alias-file
315 You can specify a different file name to use instead of
316 @file{~/.mailrc} by setting the variable
317 @code{mail-personal-alias-file}.
319 @findex expand-mail-aliases
320 Normally, Emacs expands aliases when you send the message. You do not
321 need to expand mail aliases before sending the message, but you can
322 expand them if you want to see where the mail will actually go. To do
323 this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail
324 aliases currently present in the mail headers that hold addresses.
326 If you like, you can have mail aliases expand as abbrevs, as soon as
327 you type them in (@pxref{Abbrevs}). To enable this feature, execute the
331 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
335 @findex define-mail-abbrev
337 This can go in your @file{.emacs} file. @xref{Hooks}. If you use this
338 feature, you must use @code{define-mail-abbrev} instead of
339 @code{define-mail-alias}; the latter does not work with this package.
340 Note that the mail abbreviation package uses the variable
341 @code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias
342 names are converted to lower case.
344 @kindex C-c C-a @r{(Mail mode)}
345 @findex mail-interactive-insert-alias
346 The mail abbreviation package also provides the @kbd{C-c C-a}
347 (@code{mail-interactive-insert-alias}) command, which reads an alias
348 name (with completion) and inserts its definition at point. This is
349 useful when editing the message text itself or a header field such as
350 @samp{Subject} in which Emacs does not normally expand aliases.
352 Note that abbrevs expand only if you insert a word-separator character
353 afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause
354 expansion as well. Here's how to do that:
357 (add-hook 'mail-mode-hook
359 (substitute-key-definition
360 'next-line 'mail-abbrev-next-line
361 mail-mode-map global-map)
362 (substitute-key-definition
363 'end-of-buffer 'mail-abbrev-end-of-buffer
364 mail-mode-map global-map)))
372 The major mode used in the mail buffer is Mail mode, which is much
373 like Text mode except that various special commands are provided on the
374 @kbd{C-c} prefix. These commands all have to do specifically with
375 editing or sending the message. In addition, Mail mode defines the
376 character @samp{%} as a word separator; this is helpful for using the
377 word commands to edit mail addresses.
379 Mail mode is normally used in buffers set up automatically by the
380 @code{mail} command and related commands. However, you can also switch
381 to Mail mode in a file-visiting buffer. That is a useful thing to do if
382 you have saved draft message text in a file.
385 * Mail Sending:: Commands to send the message.
386 * Header Editing:: Commands to move to header fields and edit them.
387 * Citing Mail:: Copying all or part of a message you are replying to.
388 * Mail Mode Misc:: Spell checking, signatures, etc.
392 @subsection Mail Sending
394 Mail mode has two commands for sending the message you have been
399 Send the message, and leave the mail buffer selected (@code{mail-send}).
401 Send the message, and select some other buffer (@code{mail-send-and-exit}).
404 @kindex C-c C-s @r{(Mail mode)}
405 @kindex C-c C-c @r{(Mail mode)}
407 @findex mail-send-and-exit
408 @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail
409 buffer unmodified, but leaves that buffer selected so that you can
410 modify the message (perhaps with new recipients) and send it again.
411 @kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the
412 window or switches to another buffer. It puts the mail buffer at the
413 lowest priority for reselection by default, since you are finished with
414 using it. This is the usual way to send the message.
416 In a file-visiting buffer, sending the message does not clear the
417 modified flag, because only saving the file should do that. As a
418 result, you don't get a warning if you try to send the same message
421 @c This is indexed in mule.texi, node "Recognize Coding".
422 @c @vindex sendmail-coding-system
423 When you send a message that contains non-ASCII characters, they need
424 to be encoded with a coding system (@pxref{Coding Systems}). Usually
425 the coding system is specified automatically by your chosen language
426 environment (@pxref{Language Environments}). You can explicitly specify
427 the coding system for outgoing mail by setting the variable
428 @code{sendmail-coding-system} (@pxref{Recognize Coding}).
430 If the coding system thus determined does not handle the characters in
431 a particular message, Emacs asks you to select the coding system to use,
432 showing a list of possible coding systems.
435 @subsection Mail Header Editing
437 Mail mode provides special commands to move to particular header
438 fields and to complete addresses in headers.
442 Move to the @samp{To} header field, creating one if there is none
445 Move to the @samp{Subject} header field, creating one if there is
446 none (@code{mail-subject}).
448 Move to the @samp{CC} header field, creating one if there is none
451 Move to the @samp{BCC} header field, creating one if there is none
454 Move to the @samp{FCC} header field, creating one if there is none
457 Complete a mailing address (@code{mail-complete}).
460 @kindex C-c C-f C-t @r{(Mail mode)}
462 @kindex C-c C-f C-s @r{(Mail mode)}
464 @kindex C-c C-f C-c @r{(Mail mode)}
466 @kindex C-c C-f C-b @r{(Mail mode)}
468 @kindex C-c C-f C-f @r{(Mail mode)}
470 There are five commands to move point to particular header fields, all
471 based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They
472 are listed in the table above. If the field in question does not exist,
473 these commands create one. We provide special motion commands for these
474 particular fields because they are the fields users most often want to
477 @findex mail-complete
478 @kindex M-TAB @r{(Mail mode)}
479 While editing a header field that contains mailing addresses, such as
480 @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing
481 address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It inserts
482 the full name corresponding to the address, if it can determine the full
483 name. The variable @code{mail-complete-style} controls whether to insert
484 the full name, and what style to use, as in @code{mail-from-style}
485 (@pxref{Mail Headers}).
487 For completion purposes, the valid mailing addresses are taken to be
488 the local users' names plus your personal mail aliases. You can specify
489 additional sources of valid addresses; use the customization buffer
490 to see the options for this.
492 If you type @kbd{M-@key{TAB}} in the body of the message, it invokes
493 @code{ispell-complete-word}, as in Text mode.
496 @subsection Citing Mail
499 Mail mode also has commands for yanking or @dfn{citing} all or part of
500 a message that you are replying to. These commands are active only when
501 you started sending a message using an Rmail command.
505 Yank the selected message from Rmail (@code{mail-yank-original}).
507 Yank the region from the Rmail buffer (@code{mail-yank-region}).
509 Fill each paragraph cited from another message
510 (@code{mail-fill-yanked-message}).
513 @kindex C-c C-y @r{(Mail mode)}
514 @findex mail-yank-original
515 When mail sending is invoked from the Rmail mail reader using an Rmail
516 command, @kbd{C-c C-y} can be used inside the mail buffer to insert
517 the text of the message you are replying to. Normally it indents each line
518 of that message three spaces and eliminates most header fields. A numeric
519 argument specifies the number of spaces to indent. An argument of just
520 @kbd{C-u} says not to indent at all and not to eliminate anything.
521 @kbd{C-c C-y} always uses the current message from the Rmail buffer,
522 so you can insert several old messages by selecting one in Rmail,
523 switching to @samp{*mail*} and yanking it, then switching back to
524 Rmail to select another.
526 @vindex mail-yank-prefix
527 You can specify the text for @kbd{C-c C-y} to insert at the beginning
528 of each line: set @code{mail-yank-prefix} to the desired string. (A
529 value of @code{nil} means to use indentation; this is the default.)
530 However, @kbd{C-u C-c C-y} never adds anything at the beginning of the
531 inserted lines, regardless of the value of @code{mail-yank-prefix}.
533 @kindex C-c C-r @r{(Mail mode)}
534 @findex mail-yank-region
535 To yank just a part of an incoming message, set the region in Rmail to
536 the part you want; then go to the @samp{*Mail*} message and type
537 @kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is
538 indented or prefixed according to @code{mail-yank-prefix}.
540 @kindex C-c C-q @r{(Mail mode)}
541 @findex mail-fill-yanked-message
542 After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q}
543 (@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked
544 old message or messages. One use of @kbd{C-c C-q} fills all such
545 paragraphs, each one individually. To fill a single paragraph of the
546 quoted message, use @kbd{M-q}. If filling does not automatically
547 handle the type of citation prefix you use, try setting the fill prefix
548 explicitly. @xref{Filling}.
551 @subsection Mail Mode Miscellany
555 Move to the beginning of the message body text (@code{mail-text}).
557 Insert the file @file{~/.signature} at the end of the message text
558 (@code{mail-signature}).
559 @item C-c C-i @var{file} @key{RET}
560 Insert the contents of @var{file} at the end of the outgoing message
561 (@code{mail-attach-file}).
562 @item M-x ispell-message
563 Do spelling correction on the message text, but not on citations from
567 @kindex C-c C-t @r{(Mail mode)}
569 @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header
570 separator line---that is, to the beginning of the message body text.
572 @kindex C-c C-w @r{(Mail mode)}
573 @findex mail-signature
574 @vindex mail-signature
575 @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at
576 the end of the message to say more about who you are. The text comes
577 from the file @file{~/.signature} in your home directory. To insert
578 your signature automatically, set the variable @code{mail-signature} to
579 @code{t}; then starting a mail message automatically inserts the
580 contents of your @file{~/.signature} file. If you want to omit your
581 signature from a particular message, delete it from the buffer before
582 you send the message.
584 You can also set @code{mail-signature} to a string; then that string
585 is inserted automatically as your signature when you start editing a
586 message to send. If you set it to some other Lisp expression, the
587 expression is evaluated each time, and its value (which should be a
588 string) specifies the signature.
590 @findex ispell-message
591 You can do spelling correction on the message text you have written
592 with the command @kbd{M-x ispell-message}. If you have yanked an
593 incoming message into the outgoing draft, this command skips what was
594 yanked, but it checks the text that you yourself inserted. (It looks
595 for indentation or @code{mail-yank-prefix} to distinguish the cited
596 lines from your input.) @xref{Spelling}.
598 @kindex C-c C-i @r{(Mail mode)}
599 @findex mail-attach-file
600 To include a file in the outgoing message, you can use @kbd{C-x i},
601 the usual command to insert a file in the current buffer. But it is
602 often more convenient to use a special command, @kbd{C-c C-i}
603 (@code{mail-attach-file}). This command inserts the file contents at
604 the end of the buffer, after your signature if any, with a delimiter
605 line that includes the file name.
607 @vindex mail-mode-hook
608 @vindex mail-setup-hook
609 Turning on Mail mode (which @kbd{C-x m} does automatically) runs the
610 normal hooks @code{text-mode-hook} and @code{mail-mode-hook}.
611 Initializing a new outgoing message runs the normal hook
612 @code{mail-setup-hook}; if you want to add special fields to your mail
613 header or make other changes to the appearance of the mail buffer, use
614 that hook. @xref{Hooks}.
616 The main difference between these hooks is just when they are
617 invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs
618 as soon as the @samp{*mail*} buffer is created. Then the
619 @code{mail-setup} function puts in the default contents of the buffer.
620 After these default contents are inserted, @code{mail-setup-hook} runs.
622 @node Mail Amusements
623 @section Mail Amusements
627 @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing
628 mail message. The keywords are chosen from a list of words that suggest
629 you are discussing something subversive.
631 The idea behind this feature is the suspicion that the
632 NSA@footnote{The US National Security Agency.} snoops on
633 all electronic mail messages that contain keywords suggesting they might
634 find them interesting. (The NSA says they don't, but that's what they
635 @emph{would} say.) The idea is that if lots of people add suspicious
636 words to their messages, the NSA will get so busy with spurious input
637 that they will have to give up reading it all.
639 Here's how to insert spook keywords automatically whenever you start
640 entering an outgoing message:
643 (add-hook 'mail-setup-hook 'spook)
646 Whether or not this confuses the NSA, it at least amuses people.
648 @findex fortune-to-signature
649 @cindex fortune cookies
650 You can use the @code{fortune} program to put a ``fortune cookie''
651 message into outpoing mail. To do this, add
652 @code{fortune-to-signature} to @code{mail-setup-hook}:
655 (add-hook 'mail-setup-hook 'fortune-to-signature)
659 @section Mail-Composition Methods
660 @cindex mail-composition methods
662 @cindex MH mail interface
663 @cindex Message mode for sending mail
664 In this chapter we have described the usual Emacs mode for editing
665 and sending mail---Mail mode. Emacs has alternative facilities for
666 editing and sending mail, including
667 MH-E and Message mode, not documented in this manual.
668 @xref{,MH-E,,mh-e, The Emacs Interface to MH}. @xref{,Message,,message,
669 Message Manual}. You can choose any of them as your preferred method.
670 The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use
671 whichever agent you have specified. So do various other Emacs commands
672 and facilities that send mail.
674 @vindex mail-user-agent
675 To specify your mail-composition method, customize the variable
676 @code{mail-user-agent}. Currently legitimate values include
677 @code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent},
678 @code{message-user-agent} and @code{gnus-user-agent}.
680 If you select a different mail-composition method, the information
681 in this chapter about the @samp{*mail*} buffer and Mail mode does not
682 apply; the other methods use a different format of text in a different
683 buffer, and their commands are different as well.