1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001, 2003
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.
60 @vindex mail-default-directory
61 The variable @code{mail-default-directory} controls the default
62 directory for mail buffers, and also says where to put their auto-save
66 @c Commented out because it is not user-oriented;
67 @c it doesn't say how to do some job. -- rms.
68 @cindex directory servers
71 @cindex names and addresses
72 There is an interface to directory servers using various protocols such
73 as LDAP or the CCSO white pages directory system (PH/QI), described in a
74 separate manual. It may be useful for looking up names and addresses.
75 @xref{Top,,EUDC, eudc, EUDC Manual}.
79 * Format: Mail Format. Format of the mail being composed.
80 * Headers: Mail Headers. Details of permitted mail header fields.
81 * Aliases: Mail Aliases. Abbreviating and grouping mail addresses.
82 * Mode: Mail Mode. Special commands for editing mail being composed.
83 * Amuse: Mail Amusements. Distracting the NSA; adding fortune messages.
84 * Methods: Mail Methods. Using alternative mail-composition methods.
85 * SMTP: Sending via SMTP. Sending mail via SMTP.
89 @section The Format of the Mail Buffer
91 In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header
92 fields} which say who sent it, when, to whom, why, and so on. Some
93 header fields, such as @samp{Date} and @samp{Sender}, are created
94 automatically when you send the message. Others, such as the recipient
95 names, must be specified by you in order to send the message properly.
97 Mail mode provides a few commands to help you edit some header fields,
98 and some are preinitialized in the buffer automatically at times. You can
99 insert and edit header fields using ordinary editing commands.
101 The line in the buffer that says
104 --text follows this line--
108 is a special delimiter that separates the headers you have specified from
109 the text. Whatever follows this line is the text of the message; the
110 headers precede it. The delimiter line itself does not appear in the
111 message actually sent. The text used for the delimiter line is controlled
112 by the variable @code{mail-header-separator}.
114 Here is an example of what the headers and text in the mail buffer
119 CC: lungfish@@spam.org, byob@@spam.org
120 Subject: The Emacs Manual
121 --Text follows this line--
122 Please ignore this message.
126 @section Mail Header Fields
127 @cindex headers (of mail message)
129 A header field in the mail buffer starts with a field name at the
130 beginning of a line, terminated by a colon. Upper and lower case are
131 equivalent in field names (and in mailing addresses also). After the
132 colon and optional whitespace comes the contents of the field.
134 You can use any name you like for a header field, but normally people
135 use only standard field names with accepted meanings. Here is a table
136 of fields commonly used in outgoing messages.
140 This field contains the mailing addresses to which the message is
141 addressed. If you list more than one address, use commas, not spaces,
145 The contents of the @samp{Subject} field should be a piece of text
146 that says what the message is about. The reason @samp{Subject} fields
147 are useful is that most mail-reading programs can provide a summary of
148 messages, listing the subject of each message but not its text.
151 This field contains additional mailing addresses to send the message to,
152 like @samp{To} except that these readers should not regard the message
156 This field contains additional mailing addresses to send the message to,
157 which should not appear in the header of the message actually sent.
158 Copies sent this way are called @dfn{blind carbon copies}.
160 @vindex mail-self-blind
161 @cindex copy of every outgoing message
162 To send a blind carbon copy of every outgoing message to yourself, set
163 the variable @code{mail-self-blind} to @code{t}. To send a blind carbon
164 copy of every message to some other @var{address}, set the variable
165 @code{mail-default-headers} to @code{"Bcc: @var{address}\n"}.
168 This field contains the name of one file and directs Emacs to append a
169 copy of the message to that file when you send the message. If the file
170 is in Rmail format, Emacs writes the message in Rmail format; otherwise,
171 Emacs writes the message in system mail file format. To specify
172 more than one file, use several @samp{FCC} fields, with one file
175 @vindex mail-archive-file-name
176 To put a fixed file name in the @samp{FCC} field each time you start
177 editing an outgoing message, set the variable
178 @code{mail-archive-file-name} to that file name. Unless you remove the
179 @samp{FCC} field before sending, the message will be written into that
180 file when it is sent.
183 Use the @samp{From} field to say who you are, when the account you are
184 using to send the mail is not your own. The contents of the @samp{From}
185 field should be a valid mailing address, since replies will normally go
186 there. If you don't specify the @samp{From} field yourself, Emacs uses
187 the value of @code{user-mail-address} as the default.
190 Use this field to direct replies to a different address. Most
191 mail-reading programs (including Rmail) automatically send replies to
192 the @samp{Reply-to} address in preference to the @samp{From} address.
193 By adding a @samp{Reply-to} field to your header, you can work around
194 any problems your @samp{From} address may cause for replies.
196 @cindex @env{REPLYTO} environment variable
197 @vindex mail-default-reply-to
198 To put a fixed @samp{Reply-to} address into every outgoing message, set
199 the variable @code{mail-default-reply-to} to that address (as a string).
200 Then @code{mail} initializes the message with a @samp{Reply-to} field as
201 specified. You can delete or alter that header field before you send
202 the message, if you wish. When Emacs starts up, if the environment
203 variable @env{REPLYTO} is set, @code{mail-default-reply-to} is
204 initialized from that environment variable.
207 This field contains a piece of text describing the message you are
208 replying to. Some mail systems can use this information to correlate
209 related pieces of mail. Normally this field is filled in by Rmail
210 when you reply to a message in Rmail, and you never need to
211 think about it (@pxref{Rmail}).
214 This field lists the message IDs of related previous messages. Rmail
215 sets up this field automatically when you reply to a message.
218 The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear
219 any number of times, and each such header field can contain multiple
220 addresses, separated by commas. This way, you can specify any number
221 of places to send the message. These fields can also have
222 continuation lines: one or more lines starting with whitespace,
223 following the starting line of the field, are considered part of the
224 field. Here's an example of a @samp{To} field with a continuation
229 To: foo@@here.net, this@@there.net,
230 me@@gnu.cambridge.mass.usa.earth.spiral3281
234 @vindex mail-from-style
235 When you send the message, if you didn't write a @samp{From} field
236 yourself, Emacs puts in one for you. The variable
237 @code{mail-from-style} controls the format:
241 Use just the email address, as in @samp{king@@grassland.com}.
243 Use both email address and full name, as in @samp{king@@grassland.com (Elvis
246 Use both email address and full name, as in @samp{Elvis Parsley
247 <king@@grassland.com>}.
249 Allow the system to insert the @samp{From} field.
252 @vindex mail-default-headers
253 You can direct Emacs to insert certain default headers into the
254 outgoing message by setting the variable @code{mail-default-headers}
255 to a string. Then @code{C-x m} inserts this string into the message
256 headers. If the default header fields are not appropriate for a
257 particular message, edit them as appropriate before sending the
261 @section Mail Aliases
263 @cindex @file{.mailrc} file
266 You can define @dfn{mail aliases} in a file named @file{~/.mailrc}.
267 These are short mnemonic names which stand for mail addresses or groups of
268 mail addresses. Like many other mail programs, Emacs expands aliases
269 when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and
270 @samp{Reply-to} fields, plus their @samp{Resent-} variants.
272 To define an alias in @file{~/.mailrc}, write a line in the following
276 alias @var{shortaddress} @var{fulladdresses}
280 Here @var{fulladdresses} stands for one or more mail addresses for
281 @var{shortaddress} to expand into. Separate multiple addresses with
282 spaces; if an address contains a space, quote the whole address with a
283 pair of double-quotes.
285 For instance, to make @code{maingnu} stand for
286 @code{gnu@@gnu.org} plus a local address of your own, put in
290 alias maingnu gnu@@gnu.org local-gnu
293 Emacs also recognizes include commands in @samp{.mailrc} files.
297 source @var{filename}
301 The file @file{~/.mailrc} is used primarily by other mail-reading
302 programs; it can contain various other commands. Emacs ignores
303 everything in it except for alias definitions and include commands.
305 @findex define-mail-alias
306 Another way to define a mail alias, within Emacs alone, is with the
307 @code{define-mail-alias} command. It prompts for the alias and then the
308 full address. You can use it to define aliases in your @file{.emacs}
312 (define-mail-alias "maingnu" "gnu@@gnu.org")
316 @code{define-mail-alias} records aliases by adding them to a
317 variable named @code{mail-aliases}. If you are comfortable with
318 manipulating Lisp lists, you can set @code{mail-aliases} directly. The
319 initial value of @code{mail-aliases} is @code{t}, which means that
320 Emacs should read @file{.mailrc} to get the proper value.
322 @vindex mail-personal-alias-file
323 You can specify a different file name to use instead of
324 @file{~/.mailrc} by setting the variable
325 @code{mail-personal-alias-file}.
327 @findex expand-mail-aliases
328 Normally, Emacs expands aliases when you send the message. You do not
329 need to expand mail aliases before sending the message, but you can
330 expand them if you want to see where the mail will actually go. To do
331 this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail
332 aliases currently present in the mail headers that hold addresses.
334 If you like, you can have mail aliases expand as abbrevs, as soon as
335 you type them in (@pxref{Abbrevs}). To enable this feature, execute the
339 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
343 @findex define-mail-abbrev
345 This can go in your @file{.emacs} file. @xref{Hooks}. If you use this
346 feature, you must use @code{define-mail-abbrev} instead of
347 @code{define-mail-alias}; the latter does not work with this package.
348 Note that the mail abbreviation package uses the variable
349 @code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias
350 names are converted to lower case.
352 @kindex C-c C-a @r{(Mail mode)}
353 @findex mail-interactive-insert-alias
354 The mail abbreviation package also provides the @kbd{C-c C-a}
355 (@code{mail-interactive-insert-alias}) command, which reads an alias
356 name (with completion) and inserts its definition at point. This is
357 useful when editing the message text itself or a header field such as
358 @samp{Subject} in which Emacs does not normally expand aliases.
360 Note that abbrevs expand only if you insert a word-separator character
361 afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause
362 expansion as well. Here's how to do that:
365 (add-hook 'mail-mode-hook
367 (substitute-key-definition
368 'next-line 'mail-abbrev-next-line
369 mail-mode-map global-map)
370 (substitute-key-definition
371 'end-of-buffer 'mail-abbrev-end-of-buffer
372 mail-mode-map global-map)))
380 The major mode used in the mail buffer is Mail mode, which is much
381 like Text mode except that various special commands are provided on the
382 @kbd{C-c} prefix. These commands all have to do specifically with
383 editing or sending the message. In addition, Mail mode defines the
384 character @samp{%} as a word separator; this is helpful for using the
385 word commands to edit mail addresses.
387 Mail mode is normally used in buffers set up automatically by the
388 @code{mail} command and related commands. However, you can also switch
389 to Mail mode in a file-visiting buffer. This is a useful thing to do if
390 you have saved the text of a draft message in a file.
393 * Mail Sending:: Commands to send the message.
394 * Header Editing:: Commands to move to header fields and edit them.
395 * Citing Mail:: Copying all or part of a message you are replying to.
396 * Mail Mode Misc:: Spell checking, signatures, etc.
400 @subsection Mail Sending
402 Mail mode has two commands for sending the message you have been
407 Send the message, and leave the mail buffer selected (@code{mail-send}).
409 Send the message, and select some other buffer (@code{mail-send-and-exit}).
412 @kindex C-c C-s @r{(Mail mode)}
413 @kindex C-c C-c @r{(Mail mode)}
415 @findex mail-send-and-exit
416 @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail
417 buffer unmodified, but leaves that buffer selected so that you can
418 modify the message (perhaps with new recipients) and send it again.
419 @kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the
420 window or switches to another buffer. It puts the mail buffer at the
421 lowest priority for reselection by default, since you are finished with
422 using it. This is the usual way to send the message.
424 In a file-visiting buffer, sending the message does not clear the
425 modified flag, because only saving the file should do that. As a
426 result, you don't get a warning if you try to send the same message
429 @c This is indexed in mule.texi, node "Recognize Coding".
430 @c @vindex sendmail-coding-system
431 When you send a message that contains non-ASCII characters, they need
432 to be encoded with a coding system (@pxref{Coding Systems}). Usually
433 the coding system is specified automatically by your chosen language
434 environment (@pxref{Language Environments}). You can explicitly specify
435 the coding system for outgoing mail by setting the variable
436 @code{sendmail-coding-system} (@pxref{Recognize Coding}).
438 If the coding system thus determined does not handle the characters in
439 a particular message, Emacs asks you to select the coding system to use,
440 showing a list of possible coding systems.
443 @subsection Mail Header Editing
445 Mail mode provides special commands to move to particular header
446 fields and to complete addresses in headers.
450 Move to the @samp{To} header field, creating one if there is none
453 Move to the @samp{Subject} header field, creating one if there is
454 none (@code{mail-subject}).
456 Move to the @samp{CC} header field, creating one if there is none
459 Move to the @samp{BCC} header field, creating one if there is none
462 Move to the @samp{FCC} header field, creating one if there is none
465 Complete a mailing address (@code{mail-complete}).
468 @kindex C-c C-f C-t @r{(Mail mode)}
470 @kindex C-c C-f C-s @r{(Mail mode)}
472 @kindex C-c C-f C-c @r{(Mail mode)}
474 @kindex C-c C-f C-b @r{(Mail mode)}
476 @kindex C-c C-f C-f @r{(Mail mode)}
478 There are five commands to move point to particular header fields, all
479 based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They
480 are listed in the table above. If the field in question does not exist,
481 these commands create one. We provide special motion commands for these
482 particular fields because they are the fields users most often want to
485 @findex mail-complete
486 @kindex M-TAB @r{(Mail mode)}
487 While editing a header field that contains mailing addresses, such as
488 @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing
489 address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It inserts
490 the full name corresponding to the address, if it can determine the full
491 name. The variable @code{mail-complete-style} controls whether to insert
492 the full name, and what style to use, as in @code{mail-from-style}
493 (@pxref{Mail Headers}).
495 For completion purposes, the valid mailing addresses are taken to be
496 the local users' names plus your personal mail aliases. You can
497 specify additional sources of valid addresses; look at the customization
498 group @samp{mailalias} to see the options for this
499 (@pxref{Customization Groups}).
501 If you type @kbd{M-@key{TAB}} in the body of the message,
502 @code{mail-complete} invokes @code{ispell-complete-word}, as in Text
506 @subsection Citing Mail
509 Mail mode also has commands for yanking or @dfn{citing} all or part of
510 a message that you are replying to. These commands are active only when
511 you started sending a message using an Rmail command.
515 Yank the selected message from Rmail (@code{mail-yank-original}).
517 Yank the region from the Rmail buffer (@code{mail-yank-region}).
519 Fill each paragraph cited from another message
520 (@code{mail-fill-yanked-message}).
523 @kindex C-c C-y @r{(Mail mode)}
524 @findex mail-yank-original
525 When mail sending is invoked from the Rmail mail reader using an Rmail
526 command, @kbd{C-c C-y} can be used inside the mail buffer to insert
527 the text of the message you are replying to. Normally it indents each line
528 of that message three spaces and eliminates most header fields. A numeric
529 argument specifies the number of spaces to indent. An argument of just
530 @kbd{C-u} says not to indent at all and not to eliminate anything.
531 @kbd{C-c C-y} always uses the current message from the Rmail buffer,
532 so you can insert several old messages by selecting one in Rmail,
533 switching to @samp{*mail*} and yanking it, then switching back to
534 Rmail to select another.
536 @vindex mail-yank-prefix
537 You can specify the text for @kbd{C-c C-y} to insert at the beginning
538 of each line: set @code{mail-yank-prefix} to the desired string. (A
539 value of @code{nil} means to use indentation; this is the default.)
540 However, @kbd{C-u C-c C-y} never adds anything at the beginning of the
541 inserted lines, regardless of the value of @code{mail-yank-prefix}.
543 @kindex C-c C-r @r{(Mail mode)}
544 @findex mail-yank-region
545 To yank just a part of an incoming message, set the region in Rmail to
546 the part you want; then go to the @samp{*Mail*} message and type
547 @kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is
548 indented or prefixed according to @code{mail-yank-prefix}.
550 @kindex C-c C-q @r{(Mail mode)}
551 @findex mail-fill-yanked-message
552 After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q}
553 (@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked
554 old message or messages. One use of @kbd{C-c C-q} fills all such
555 paragraphs, each one individually. To fill a single paragraph of the
556 quoted message, use @kbd{M-q}. If filling does not automatically
557 handle the type of citation prefix you use, try setting the fill prefix
558 explicitly. @xref{Filling}.
561 @subsection Mail Mode Miscellany
565 Move to the beginning of the message body text (@code{mail-text}).
567 Insert the file @file{~/.signature} at the end of the message text
568 (@code{mail-signature}).
569 @item C-c C-i @var{file} @key{RET}
570 Insert the contents of @var{file} at the end of the outgoing message
571 (@code{mail-attach-file}).
572 @item M-x ispell-message
573 Perform spelling correction on the message text, but not on citations from
577 @kindex C-c C-t @r{(Mail mode)}
579 @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header
580 separator line---that is, to the beginning of the message body text.
582 @kindex C-c C-w @r{(Mail mode)}
583 @findex mail-signature
584 @vindex mail-signature
585 @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at
586 the end of the message to say more about who you are. The text comes
587 from the file @file{~/.signature} in your home directory. To insert
588 your signature automatically, set the variable @code{mail-signature} to
589 @code{t}; after that, starting a mail message automatically inserts the
590 contents of your @file{~/.signature} file. If you want to omit your
591 signature from a particular message, delete it from the buffer before
592 you send the message.
594 You can also set @code{mail-signature} to a string; then that string
595 is inserted automatically as your signature when you start editing a
596 message to send. If you set it to some other Lisp expression, the
597 expression is evaluated each time, and its value (which should be a
598 string) specifies the signature.
600 @findex ispell-message
601 You can do spelling correction on the message text you have written
602 with the command @kbd{M-x ispell-message}. If you have yanked an
603 incoming message into the outgoing draft, this command skips what was
604 yanked, but it checks the text that you yourself inserted. (It looks
605 for indentation or @code{mail-yank-prefix} to distinguish the cited
606 lines from your input.) @xref{Spelling}.
608 @kindex C-c C-i @r{(Mail mode)}
609 @findex mail-attach-file
610 To include a file in the outgoing message, you can use @kbd{C-x i},
611 the usual command to insert a file in the current buffer. But it is
612 often more convenient to use a special command, @kbd{C-c C-i}
613 (@code{mail-attach-file}). This command inserts the file contents at
614 the end of the buffer, after your signature if any, with a delimiter
615 line that includes the file name.
617 @vindex mail-mode-hook
618 @vindex mail-setup-hook
619 Turning on Mail mode (which @kbd{C-x m} does automatically) runs the
620 normal hooks @code{text-mode-hook} and @code{mail-mode-hook}.
621 Initializing a new outgoing message runs the normal hook
622 @code{mail-setup-hook}; if you want to add special fields to your mail
623 header or make other changes to the appearance of the mail buffer, use
624 that hook. @xref{Hooks}.
626 The main difference between these hooks is just when they are
627 invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs
628 as soon as the @samp{*mail*} buffer is created. Then the
629 @code{mail-setup} function inserts the default contents of the buffer.
630 After these default contents are inserted, @code{mail-setup-hook} runs.
632 @node Mail Amusements
633 @section Mail Amusements
637 @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing
638 mail message. The keywords are chosen from a list of words that suggest
639 you are discussing something subversive.
641 The idea behind this feature is the suspicion that the
642 NSA@footnote{The US National Security Agency.} snoops on
643 all electronic mail messages that contain keywords suggesting they might
644 find them interesting. (The NSA says they don't, but that's what they
645 @emph{would} say.) The idea is that if lots of people add suspicious
646 words to their messages, the NSA will get so busy with spurious input
647 that they will have to give up reading it all.
649 Here's how to insert spook keywords automatically whenever you start
650 entering an outgoing message:
653 (add-hook 'mail-setup-hook 'spook)
656 Whether or not this confuses the NSA, it at least amuses people.
658 @findex fortune-to-signature
659 @cindex fortune cookies
660 You can use the @code{fortune} program to put a ``fortune cookie''
661 message into outgoing mail. To do this, add
662 @code{fortune-to-signature} to @code{mail-setup-hook}:
665 (add-hook 'mail-setup-hook 'fortune-to-signature)
669 @section Mail-Composition Methods
670 @cindex mail-composition methods
672 @cindex MH mail interface
673 @cindex Message mode for sending mail
674 In this chapter we have described the usual Emacs mode for editing
675 and sending mail---Mail mode. Emacs has alternative facilities for
676 editing and sending mail, including
677 MH-E and Message mode, not documented in this manual.
678 @xref{MH-E,,,mh-e, The Emacs Interface to MH}. @xref{Message,,,message,
679 Message Manual}. You can choose any of them as your preferred method.
680 The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use
681 whichever agent you have specified, as do various other Emacs commands
682 and facilities that send mail.
684 @vindex mail-user-agent
685 To specify your mail-composition method, customize the variable
686 @code{mail-user-agent}. Currently legitimate values include
687 @code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent},
688 @code{message-user-agent} and @code{gnus-user-agent}.
690 If you select a different mail-composition method, the information
691 in this chapter about the @samp{*mail*} buffer and Mail mode does not
692 apply; the other methods use a different format of text in a different
693 buffer, and their commands are different as well.
695 @node Sending via SMTP
696 @section Sending via SMTP
699 Emacs includes a package for sending your mail to a SMTP server and
700 have it take care of delivering it to the final destination, rather
701 than letting the MTA on your local system take care of it. This can
702 be useful if you don't have a MTA set up on your host, or if your
703 machine is often disconnected from the Internet.
705 Sending mail via SMTP requires configuring your mail user agent
706 (@pxref{Mail Methods}) to use the SMTP library. How to do this should
707 be described for each mail user agent; for the Message and Gnus user
708 agents the variable @code{message-send-mail-function} (@pxref{Mail
709 Variables,,,message}) is used.
711 @vindex send-mail-function
712 The variable @code{send-mail-function} controls how the default mail
713 user agent sends mail. It should be set to a function. The default
714 is @code{sendmail-send-it}, but must be set to @code{smtpmail-send-it}
715 in order to use the SMTP library. @code{feedmail-send-it} is another
718 Before using SMTP you must find out the hostname of the SMTP server
719 to use. Your system administrator should provide you with this
720 information, but often it is the same as the server you receive mail
723 @vindex smtpmail-smtp-server
724 The variable @code{smtpmail-smtp-server} controls the hostname of
725 the server to use. It is a string with an IP address or hostname. It
726 defaults to the contents of the @code{SMTPSERVER} environment
727 variable, or, if empty, the contents of
728 @code{smtpmail-default-smtp-server}.
730 @vindex smtpmail-default-smtp-server
731 The variable @code{smtpmail-default-smtp-server} controls the
732 default hostname of the server to use. It is a string with an IP
733 address or hostname. It must be set before the SMTP library is
734 loaded. It has no effect if set after the SMTP library has been
735 loaded, or if @code{smtpmail-smtp-server} is defined. It is usually
736 set by system administrators in a site wide initialization file.
738 @cindex Mail Submission
739 SMTP is normally used on the registered ``smtp'' TCP service port 25.
740 Some environments use SMTP in ``Mail Submission'' mode, which uses
741 port 587. Using other ports is not uncommon, either for security by
742 obscurity purposes, port forwarding, or otherwise.
744 @vindex smtpmail-smtp-service
745 The variable @code{smtpmail-smtp-service} controls the port on the
746 server to contact. It is either a string, in which case it will be
747 translated into an integer using system calls, or an integer.
749 Many environments require SMTP clients to authenticate themselves
750 before they are allowed to route mail via a server. The two following
751 variables contains the authentication information needed for this.
752 The first variable, @code{smtpmail-auth-credentials}, instructs the
753 SMTP library to use a SASL authentication step, currently only the
754 CRAM-MD5, PLAIN and LOGIN-MD5 mechanisms are supported and will be
755 selected in that order if the server supports them. The second
756 variable, @code{smtpmail-starttls-credentials}, instructs the SMTP
757 library to connect to the server using STARTTLS. This means the
758 protocol exchange can be integrity protected and confidential by using
759 TLS, and optionally also authentication of the client. It is common
760 to use both these mechanisms, e.g. to use STARTTLS to achieve
761 integrity and confidentiality and then use SASL for client
764 @vindex smtpmail-auth-credentials
765 The variable @code{smtpmail-auth-credentials} contains a list of
766 hostname, port, username and password tuples. When the SMTP library
767 connects to a host on a certain port, this variable is searched to
768 find a matching entry for that hostname and port. If an entry is
769 found, the authentication process is invoked and the credentials are
770 used. The hostname field follows the same format as
771 @code{smtpmail-smtp-server} (i.e., a string) and the port field the
772 same format as @code{smtpmail-smtp-service} (i.e., a string or an
773 integer). The username and password fields, which either can be
774 @samp{nil} to indicate that the user is queried for the value
775 interactively, should be strings with the username and password,
776 respectively, information that is normally provided by system
779 @vindex smtpmail-starttls-credentials
780 The variable @code{smtpmail-starttls-credentials} contains a list of
781 tuples with hostname, port, name of file containing client key, and
782 name of file containing client certificate. The processing is similar
783 to the previous variable. The client key and certificate may be
784 @samp{nil} if you do not wish to use client authentication. The use
785 of this variable requires the @samp{starttls} external program to be
786 installed, you can get it from
787 @samp{ftp://ftp.opaopa.org/pub/elisp/starttls-*.tar.gz}.
789 The remaining variables are more esoteric and is normally not needed.
791 @vindex smtpmail-debug-info
792 The variable @code{smtpmail-debug-info} controls whether to print
793 the SMTP protocol exchange in the minibuffer, and retain the entire
794 exchange in a buffer @samp{*trace of SMTP session to
797 @vindex smtpmail-debug-verb
798 The variable @code{smtpmail-debug-verb} controls whether to send the
799 VERB token to the server. The VERB server instructs the server to be
800 more verbose, and often also to attempt final delivery while your SMTP
801 session is still running. It is usually only useful together with
802 @code{smtpmail-debug-info}. Note that this may cause mail delivery to
803 take considerable time if the final destination cannot accept mail.
805 @vindex smtpmail-local-domain
806 The variable @code{smtpmail-local-domain} controls the hostname sent
807 in the first EHLO or HELO command sent to the server. It should only
808 be set if the @code{system-name} function returns a name that isn't
809 accepted by the server. Do not set this variable unless your server
812 @vindex smtpmail-sendto-domain
813 The variable @code{smtpmail-sendto-domain} makes the SMTP library
814 add @samp{@@} and the specified value to recipients specified in the
815 message when they are sent using the RCPT TO command. Some
816 configurations of sendmail requires this behaviour. Don't bother to
817 set this unless you have get an error like:
820 Sending failed; SMTP protocol error
823 when sending mail, and the *trace of SMTP session to <somewhere>*
824 buffer (enabled via @code{smtpmail-debug-info}) includes an exchange
829 501 <someone>: recipient address must contain a domain
832 @vindex smtpmail-queue-mail
833 The variable @code{smtpmail-queue-mail} controls whether a simple
834 off line mail sender is active. This variable is a boolean, and
835 defaults to @samp{nil} (disabled). If this is non-nil, mail is not
836 sent immediately but rather queued in the directory
837 @code{smtpmail-queue-dir} and can be later sent manually by invoking
838 @code{smtpmail-send-queued-mail} (typically when you connect to the
841 @vindex smtpmail-queue-dir
842 The variable @code{smtpmail-queue-dir} specifies the name of the
843 directory to hold queued messages. It defaults to
844 @samp{~/Mail/queued-mail/}.
846 @findex smtpmail-send-queued-mail
847 The function @code{smtpmail-send-queued-mail} can be used to send
848 any queued mail when @code{smtpmail-queue-mail} is enabled. It is
849 typically invoked interactively with @kbd{M-x RET
850 smtpmail-send-queued-mail RET} when you are connected to the Internet.