1 \input texinfo @c -*-texinfo-*-
4 @settitle Message Manual
9 This file documents Message, the Emacs message composition mode.
11 Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
12 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
19 and with the Back-Cover Texts as in (a) below. A copy of the license
20 is included in the section entitled ``GNU Free Documentation License''.
22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
23 modify this GNU manual. Buying copies from the FSF supports it in
24 developing GNU and promoting software freedom.''
30 * Message: (message). Mail and news composition mode that
40 @author by Lars Magne Ingebrigtsen
43 @vskip 0pt plus 1filll
57 All message composition from Gnus (both mail and news) takes place in
61 * Interface:: Setting up message buffers.
62 * Commands:: Commands you can execute in message mode buffers.
63 * Variables:: Customizing the message buffers.
64 * Compatibility:: Making Message backwards compatible.
65 * Appendices:: More technical things.
66 * GNU Free Documentation License:: The license for this documentation.
67 * Index:: Variable, function and concept index.
68 * Key Index:: List of Message mode keys.
71 @c Adjust ../Makefile.in if you change the following lines:
72 Message is distributed with Gnus. The Gnus distribution
74 corresponding to this manual is No Gnus v0.11.
80 When a program (or a person) wants to respond to a message---reply,
81 follow up, forward, cancel---the program (or person) should just put
82 point in the buffer where the message is and call the required command.
83 @code{Message} will then pop up a new @code{message} mode buffer with
84 appropriate headers filled out, and the user can edit the message before
88 * New Mail Message:: Editing a brand new mail message.
89 * New News Message:: Editing a brand new news message.
90 * Reply:: Replying via mail.
91 * Wide Reply:: Responding to all people via mail.
92 * Followup:: Following up via news.
93 * Canceling News:: Canceling a news article.
94 * Superseding:: Superseding a message.
95 * Forwarding:: Forwarding a message via news or mail.
96 * Resending:: Resending a mail message.
97 * Bouncing:: Bouncing a mail message.
98 * Mailing Lists:: Send mail to mailing lists.
101 You can customize the Message Mode tool bar, see @kbd{M-x
102 customize-apropos RET message-tool-bar}. This feature is only available
105 @node New Mail Message
106 @section New Mail Message
109 The @code{message-mail} command pops up a new message buffer.
111 Two optional parameters are accepted: The first will be used as the
112 @code{To} header and the second as the @code{Subject} header. If these
113 are @code{nil}, those two headers will be empty.
116 @node New News Message
117 @section New News Message
120 The @code{message-news} command pops up a new message buffer.
122 This function accepts two optional parameters. The first will be used
123 as the @code{Newsgroups} header and the second as the @code{Subject}
124 header. If these are @code{nil}, those two headers will be empty.
130 @findex message-reply
131 The @code{message-reply} function pops up a message buffer that's a
132 reply to the message in the current buffer.
134 @vindex message-reply-to-function
135 Message uses the normal methods to determine where replies are to go
136 (@pxref{Responses}), but you can change the behavior to suit your needs
137 by fiddling with the @code{message-reply-to-function} variable.
139 If you want the replies to go to the @code{Sender} instead of the
140 @code{From}, you could do something like this:
143 (setq message-reply-to-function
145 (cond ((equal (mail-fetch-field "from") "somebody")
146 (list (cons 'To (mail-fetch-field "sender"))))
151 This function will be called narrowed to the head of the article that is
154 As you can see, this function should return a list. In this case, it
155 returns @code{((To . "Whom"))} if it has an opinion as to what the To
156 header should be. If it does not, it should just return @code{nil}, and
157 the normal methods for determining the To header will be used.
159 Each list element should be a cons, where the @sc{car} should be the
160 name of a header (e.g. @code{Cc}) and the @sc{cdr} should be the header
161 value (e.g. @samp{larsi@@ifi.uio.no}). All these headers will be
162 inserted into the head of the outgoing mail.
168 @findex message-wide-reply
169 The @code{message-wide-reply} pops up a message buffer that's a wide
170 reply to the message in the current buffer. A @dfn{wide reply} is a
171 reply that goes out to all people listed in the @code{To}, @code{From}
172 (or @code{Reply-to}) and @code{Cc} headers.
174 @vindex message-wide-reply-to-function
175 Message uses the normal methods to determine where wide replies are to go,
176 but you can change the behavior to suit your needs by fiddling with the
177 @code{message-wide-reply-to-function}. It is used in the same way as
178 @code{message-reply-to-function} (@pxref{Reply}).
180 @vindex message-dont-reply-to-names
181 Addresses that match the @code{message-dont-reply-to-names} regular
182 expression (or list of regular expressions) will be removed from the
183 @code{Cc} header. A value of @code{nil} means exclude your name only.
185 @vindex message-prune-recipient-rules
186 @code{message-prune-recipient-rules} is used to prune the addresses
187 used when doing a wide reply. It's meant to be used to remove
188 duplicate addresses and the like. It's a list of lists, where the
189 first element is a regexp to match the address to trigger the rule,
190 and the second is a regexp that will be expanded based on the first,
191 to match addresses to be pruned.
193 It's complicated to explain, but it's easy to use.
195 For instance, if you get an email from @samp{foo@@example.org}, but
196 @samp{foo@@zot.example.org} is also in the @code{Cc} list, then your
197 wide reply will go out to both these addresses, since they are unique.
199 To avoid this, do something like the following:
202 (setq message-prune-recipient-rules
203 '(("^\\([^@@]+\\)@@\\(.*\\)" "\\1@@.*[.]\\2")))
206 If, for instance, you want all wide replies that involve messages from
207 @samp{cvs@@example.org} to go to that address, and nowhere else (i.e.,
208 remove all other recipients if @samp{cvs@@example.org} is in the
212 (setq message-prune-recipient-rules
213 '(("cvs@@example.org" ".")))
216 @vindex message-wide-reply-confirm-recipients
217 If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you
218 will be asked to confirm that you want to reply to multiple
219 recipients. The default is @code{nil}.
224 @findex message-followup
225 The @code{message-followup} command pops up a message buffer that's a
226 followup to the message in the current buffer.
228 @vindex message-followup-to-function
229 Message uses the normal methods to determine where followups are to go,
230 but you can change the behavior to suit your needs by fiddling with the
231 @code{message-followup-to-function}. It is used in the same way as
232 @code{message-reply-to-function} (@pxref{Reply}).
234 @vindex message-use-followup-to
235 The @code{message-use-followup-to} variable says what to do about
236 @code{Followup-To} headers. If it is @code{use}, always use the value.
237 If it is @code{ask} (which is the default), ask whether to use the
238 value. If it is @code{t}, use the value unless it is @samp{poster}. If
239 it is @code{nil}, don't use the value.
243 @section Canceling News
245 @findex message-cancel-news
246 The @code{message-cancel-news} command cancels the article in the
249 @vindex message-cancel-message
250 The value of @code{message-cancel-message} is inserted in the body of
251 the cancel message. The default is @samp{I am canceling my own
255 @vindex message-insert-canlock
257 When Message posts news messages, it inserts @code{Cancel-Lock}
258 headers by default. This is a cryptographic header that ensures that
259 only you can cancel your own messages, which is nice. The downside
260 is that if you lose your @file{.emacs} file (which is where Gnus
261 stores the secret cancel lock password (which is generated
262 automatically the first time you use this feature)), you won't be
263 able to cancel your message. If you want to manage a password yourself,
264 you can put something like the following in your @file{~/.gnus.el} file:
267 (setq canlock-password "geheimnis"
268 canlock-password-for-verify canlock-password)
271 Whether to insert the header or not is controlled by the
272 @code{message-insert-canlock} variable.
274 Not many news servers respect the @code{Cancel-Lock} header yet, but
275 this is expected to change in the future.
281 @findex message-supersede
282 The @code{message-supersede} command pops up a message buffer that will
283 supersede the message in the current buffer.
285 @vindex message-ignored-supersedes-headers
286 Headers matching the @code{message-ignored-supersedes-headers} are
287 removed before popping up the new message buffer. The default is@*
288 @samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@*
289 ^Received:\\|^X-From-Line:\\|^X-Trace:\\|^X-Complaints-To:\\|@*
290 Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@*
291 ^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@*
292 ^X-Payment:\\|^Approved:}.
299 @findex message-forward
300 The @code{message-forward} command pops up a message buffer to forward
301 the message in the current buffer. If given a prefix, forward using
305 @item message-forward-ignored-headers
306 @vindex message-forward-ignored-headers
307 All headers that match this regexp will be deleted when forwarding a message.
309 @item message-make-forward-subject-function
310 @vindex message-make-forward-subject-function
311 A list of functions that are called to generate a subject header for
312 forwarded messages. The subject generated by the previous function is
313 passed into each successive function.
315 The provided functions are:
318 @item message-forward-subject-author-subject
319 @findex message-forward-subject-author-subject
320 Source of article (author or newsgroup), in brackets followed by the
323 @item message-forward-subject-fwd
324 Subject of article with @samp{Fwd:} prepended to it.
327 @item message-wash-forwarded-subjects
328 @vindex message-wash-forwarded-subjects
329 If this variable is @code{t}, the subjects of forwarded messages have
330 the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:},
331 @samp{(fwd)}) removed before the new subject is
332 constructed. The default value is @code{nil}.
334 @item message-forward-as-mime
335 @vindex message-forward-as-mime
336 If this variable is @code{t} (the default), forwarded messages are
337 included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded
338 messages will just be copied inline to the new message, like previous,
339 non @acronym{MIME}-savvy versions of Gnus would do.
341 @item message-forward-before-signature
342 @vindex message-forward-before-signature
343 If non-@code{nil}, put forwarded message before signature, else after.
351 @findex message-resend
352 The @code{message-resend} command will prompt the user for an address
353 and resend the message in the current buffer to that address.
355 @vindex message-ignored-resent-headers
356 Headers that match the @code{message-ignored-resent-headers} regexp will
357 be removed before sending the message.
363 @findex message-bounce
364 The @code{message-bounce} command will, if the current buffer contains a
365 bounced mail message, pop up a message buffer stripped of the bounce
366 information. A @dfn{bounced message} is typically a mail you've sent
367 out that has been returned by some @code{mailer-daemon} as
370 @vindex message-ignored-bounced-headers
371 Headers that match the @code{message-ignored-bounced-headers} regexp
372 will be removed before popping up the buffer. The default is
373 @samp{^\\(Received\\|Return-Path\\|Delivered-To\\):}.
377 @section Mailing Lists
379 @cindex Mail-Followup-To
380 Sometimes while posting to mailing lists, the poster needs to direct
381 followups to the post to specific places. The Mail-Followup-To (MFT)
382 was created to enable just this. Three example scenarios where this is
387 A mailing list poster can use MFT to express that responses should be
388 sent to just the list, and not the poster as well. This will happen
389 if the poster is already subscribed to the list.
392 A mailing list poster can use MFT to express that responses should be
393 sent to the list and the poster as well. This will happen if the poster
394 is not subscribed to the list.
397 If a message is posted to several mailing lists, MFT may also be used
398 to direct the following discussion to one list only, because
399 discussions that are spread over several lists tend to be fragmented
400 and very difficult to follow.
404 Gnus honors the MFT header in other's messages (i.e. while following
405 up to someone else's post) and also provides support for generating
406 sensible MFT headers for outgoing messages as well.
409 @c * Honoring an MFT post:: What to do when one already exists
410 @c * Composing with a MFT header:: Creating one from scratch.
413 @c @node Composing with a MFT header
414 @subsection Composing a correct MFT header automagically
416 The first step in getting Gnus to automagically generate a MFT header
417 in posts you make is to give Gnus a list of the mailing lists
418 addresses you are subscribed to. You can do this in more than one
419 way. The following variables would come in handy.
423 @vindex message-subscribed-addresses
424 @item message-subscribed-addresses
425 This should be a list of addresses the user is subscribed to. Its
426 default value is @code{nil}. Example:
428 (setq message-subscribed-addresses
429 '("ding@@gnus.org" "bing@@noose.org"))
432 @vindex message-subscribed-regexps
433 @item message-subscribed-regexps
434 This should be a list of regexps denoting the addresses of mailing
435 lists subscribed to. Default value is @code{nil}. Example: If you
436 want to achieve the same result as above:
438 (setq message-subscribed-regexps
439 '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org")
442 @vindex message-subscribed-address-functions
443 @item message-subscribed-address-functions
444 This can be a list of functions to be called (one at a time!!) to
445 determine the value of MFT headers. It is advisable that these
446 functions not take any arguments. Default value is @code{nil}.
448 There is a pre-defined function in Gnus that is a good candidate for
449 this variable. @code{gnus-find-subscribed-addresses} is a function
450 that returns a list of addresses corresponding to the groups that have
451 the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters,
452 gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value.
453 This is how you would do it.
456 (setq message-subscribed-address-functions
457 '(gnus-find-subscribed-addresses))
460 @vindex message-subscribed-address-file
461 @item message-subscribed-address-file
462 You might be one organized human freak and have a list of addresses of
463 all subscribed mailing lists in a separate file! Then you can just
464 set this variable to the name of the file and life would be good.
468 You can use one or more of the above variables. All their values are
469 ``added'' in some way that works :-)
471 Now you are all set. Just start composing a message as you normally do.
472 And just send it; as always. Just before the message is sent out, Gnus'
473 MFT generation thingy kicks in and checks if the message already has a
474 MFT field. If there is one, it is left alone. (Except if it's empty -
475 in that case, the field is removed and is not replaced with an
476 automatically generated one. This lets you disable MFT generation on a
477 per-message basis.) If there is none, then the list of recipient
478 addresses (in the To: and Cc: headers) is checked to see if one of them
479 is a list address you are subscribed to. If none of them is a list
480 address, then no MFT is generated; otherwise, a MFT is added to the
481 other headers and set to the value of all addresses in To: and Cc:
484 @findex message-generate-unsubscribed-mail-followup-to
486 @findex message-goto-mail-followup-to
487 Hm. ``So'', you ask, ``what if I send an email to a list I am not
488 subscribed to? I want my MFT to say that I want an extra copy.'' (This
489 is supposed to be interpreted by others the same way as if there were no
490 MFT, but you can use an explicit MFT to override someone else's
491 to-address group parameter.) The function
492 @code{message-generate-unsubscribed-mail-followup-to} might come in
493 handy. It is bound to @kbd{C-c C-f C-a} by default. In any case, you
494 can insert a MFT of your own choice; @kbd{C-c C-f C-m}
495 (@code{message-goto-mail-followup-to}) will help you get started.
497 @c @node Honoring an MFT post
498 @subsection Honoring an MFT post
500 @vindex message-use-mail-followup-to
501 When you followup to a post on a mailing list, and the post has a MFT
502 header, Gnus' action will depend on the value of the variable
503 @code{message-use-mail-followup-to}. This variable can be one of:
507 Always honor MFTs. The To: and Cc: headers in your followup will be
508 derived from the MFT header of the original post. This is the default.
511 Always dishonor MFTs (just ignore the darned thing)
514 Gnus will prompt you for an action.
518 It is considered good netiquette to honor MFT, as it is assumed the
519 fellow who posted a message knows where the followups need to go
526 * Buffer Entry:: Commands after entering a Message buffer.
527 * Header Commands:: Commands for moving headers or changing headers.
528 * Movement:: Moving around in message buffers.
529 * Insertion:: Inserting things into message buffers.
530 * MIME:: @acronym{MIME} considerations.
531 * IDNA:: Non-@acronym{ASCII} domain name considerations.
532 * Security:: Signing and encrypting messages.
533 * Various Commands:: Various things.
534 * Sending:: Actually sending the message.
535 * Mail Aliases:: How to use mail aliases.
536 * Spelling:: Having Emacs check your spelling.
541 @section Buffer Entry
545 You most often end up in a Message buffer when responding to some other
546 message of some sort. Message does lots of handling of quoted text, and
547 may remove signatures, reformat the text, or the like---depending on
548 which used settings you're using. Message usually gets things right,
549 but sometimes it stumbles. To help the user unwind these stumblings,
550 Message sets the undo boundary before each major automatic action it
551 takes. If you press the undo key (usually located at @kbd{C-_}) a few
552 times, you will get back the un-edited message you're responding to.
555 @node Header Commands
556 @section Header Commands
558 @subsection Commands for moving to headers
560 These following commands move to the header in question. If it doesn't
561 exist, it will be inserted.
567 @findex describe-mode
568 Describe the message mode.
572 @findex message-goto-to
573 Go to the @code{To} header (@code{message-goto-to}).
577 @findex message-goto-from
578 Go to the @code{From} header (@code{message-goto-from}). (The ``o''
579 in the key binding is for Originator.)
583 @findex message-goto-bcc
584 Go to the @code{Bcc} header (@code{message-goto-bcc}).
588 @findex message-goto-fcc
589 Go to the @code{Fcc} header (@code{message-goto-fcc}).
593 @findex message-goto-cc
594 Go to the @code{Cc} header (@code{message-goto-cc}).
598 @findex message-goto-subject
599 Go to the @code{Subject} header (@code{message-goto-subject}).
603 @findex message-goto-reply-to
604 Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
608 @findex message-goto-newsgroups
609 Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
613 @findex message-goto-distribution
614 Go to the @code{Distribution} header (@code{message-goto-distribution}).
618 @findex message-goto-followup-to
619 Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
623 @findex message-goto-keywords
624 Go to the @code{Keywords} header (@code{message-goto-keywords}).
628 @findex message-goto-summary
629 Go to the @code{Summary} header (@code{message-goto-summary}).
633 @findex message-insert-or-toggle-importance
634 This inserts the @samp{Importance:} header with a value of
635 @samp{high}. This header is used to signal the importance of the
636 message to the receiver. If the header is already present in the
637 buffer, it cycles between the three valid values according to RFC
638 1376: @samp{low}, @samp{normal} and @samp{high}.
642 @findex message-generate-unsubscribed-mail-followup-to
643 Insert a reasonable @samp{Mail-Followup-To:} header
644 (@pxref{Mailing Lists}) in a post to an
645 unsubscribed list. When making original posts to a mailing list you are
646 not subscribed to, you have to type in a @samp{Mail-Followup-To:} header
647 by hand. The contents, usually, are the addresses of the list and your
648 own address. This function inserts such a header automatically. It
649 fetches the contents of the @samp{To:} header in the current mail
650 buffer, and appends the current @code{user-mail-address}.
652 If the optional argument @code{include-cc} is non-@code{nil}, the
653 addresses in the @samp{Cc:} header are also put into the
654 @samp{Mail-Followup-To:} header.
658 @subsection Commands to change headers
664 @findex message-sort-headers
665 @vindex message-header-format-alist
666 Sort headers according to @code{message-header-format-alist}
667 (@code{message-sort-headers}).
671 @findex message-insert-to
672 Insert a @code{To} header that contains the @code{Reply-To} or
673 @code{From} header of the message you're following up
674 (@code{message-insert-to}).
678 @findex message-insert-newsgroups
679 Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
680 or @code{Newsgroups} header of the article you're replying to
681 (@code{message-insert-newsgroups}).
685 @findex message-to-list-only
686 Send a message to the list only. Remove all addresses but the list
687 address from @code{To:} and @code{Cc:} headers.
691 @findex message-insert-disposition-notification-to
692 Insert a request for a disposition
693 notification. (@code{message-insert-disposition-notification-to}).
694 This means that if the recipient supports RFC 2298 she might send you a
695 notification that she received the message.
697 @item M-x message-insert-importance-high
698 @kindex M-x message-insert-importance-high
699 @findex message-insert-importance-high
701 Insert an @samp{Importance} header with a value of @samp{high},
702 deleting headers if necessary.
704 @item M-x message-insert-importance-low
705 @kindex M-x message-insert-importance-low
706 @findex message-insert-importance-low
708 Insert an @samp{Importance} header with a value of @samp{low}, deleting
709 headers if necessary.
713 @findex message-change-subject
715 Change the current @samp{Subject} header. Ask for new @samp{Subject}
716 header and append @samp{(was: <Old Subject>)}. The old subject can be
717 stripped on replying, see @code{message-subject-trailing-was-query}
718 (@pxref{Message Headers}).
722 @findex message-cross-post-followup-to
723 @vindex message-cross-post-default
724 @vindex message-cross-post-note-function
727 Set up the @samp{FollowUp-To} header with a target newsgroup for a
728 cross-post, add that target newsgroup to the @samp{Newsgroups} header if
729 it is not a member of @samp{Newsgroups}, and insert a note in the body.
730 If @code{message-cross-post-default} is @code{nil} or if this command is
731 called with a prefix-argument, only the @samp{FollowUp-To} header will
732 be set but the target newsgroup will not be added to the
733 @samp{Newsgroups} header. The function to insert a note is controlled
734 by the @code{message-cross-post-note-function} variable.
738 @findex message-reduce-to-to-cc
739 Replace contents of @samp{To} header with contents of @samp{Cc} or
740 @samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc}
741 header will be used instead.)
745 @findex message-insert-wide-reply
746 Insert @samp{To} and @samp{Cc} headers as if you were doing a wide
747 reply even if the message was not made for a wide reply first.
751 @findex message-add-archive-header
752 @vindex message-archive-header
753 @vindex message-archive-note
755 Insert @samp{X-No-Archive: Yes} in the header and a note in the body.
756 The header and the note can be customized using
757 @code{message-archive-header} and @code{message-archive-note}. When
758 called with a prefix argument, ask for a text to insert. If you don't
759 want the note in the body, set @code{message-archive-note} to
771 @findex message-goto-body
772 Move to the beginning of the body of the message
773 (@code{message-goto-body}).
777 @findex message-goto-signature
778 Move to the signature of the message (@code{message-goto-signature}).
782 @findex message-beginning-of-line
783 @vindex message-beginning-of-line
784 If at beginning of header value, go to beginning of line, else go to
785 beginning of header value. (The header value comes after the header
786 name and the colon.) This behavior can be disabled by toggling
787 the variable @code{message-beginning-of-line}.
799 @findex message-yank-original
800 Yank the message that's being replied to into the message buffer
801 (@code{message-yank-original}).
805 @findex message-yank-buffer
806 Prompt for a buffer name and yank the contents of that buffer into the
807 message buffer (@code{message-yank-buffer}).
811 @findex message-fill-yanked-message
812 Fill the yanked message (@code{message-fill-yanked-message}). Warning:
813 Can severely mess up the yanked text if its quoting conventions are
814 strange. You'll quickly get a feel for when it's safe, though. Anyway,
815 just remember that @kbd{C-x u} (@code{undo}) is available and you'll be
820 @findex message-insert-signature
821 Insert a signature at the end of the buffer
822 (@code{message-insert-signature}).
826 @findex message-insert-headers
827 Insert the message headers (@code{message-insert-headers}).
831 @findex message-mark-inserted-region
832 Mark some region in the current article with enclosing tags. See
833 @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
834 When called with a prefix argument, use slrn style verbatim marks
835 (@samp{#v+} and @samp{#v-}).
839 @findex message-mark-insert-file
840 Insert a file in the current article with enclosing tags.
841 See @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
842 When called with a prefix argument, use slrn style verbatim marks
843 (@samp{#v+} and @samp{#v-}).
855 Message is a @acronym{MIME}-compliant posting agent. The user generally
856 doesn't have to do anything to make the @acronym{MIME} happen---Message will
857 automatically add the @code{Content-Type} and
858 @code{Content-Transfer-Encoding} headers.
860 @findex mml-attach-file
862 The most typical thing users want to use the multipart things in
863 @acronym{MIME} for is to add ``attachments'' to mail they send out.
864 This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}),
865 which will prompt for a file name and a @acronym{MIME} type.
867 @vindex mml-dnd-protocol-alist
868 @vindex mml-dnd-attach-options
869 If your Emacs supports drag and drop, you can also drop the file in the
870 Message buffer. The variable @code{mml-dnd-protocol-alist} specifies
871 what kind of action is done when you drop a file into the Message
872 buffer. The variable @code{mml-dnd-attach-options} controls which
873 @acronym{MIME} options you want to specify when dropping a file. If it
874 is a list, valid members are @code{type}, @code{description} and
875 @code{disposition}. @code{disposition} implies @code{type}. If it is
876 @code{nil}, don't ask for options. If it is @code{t}, ask the user
877 whether or not to specify options.
879 You can also create arbitrarily complex multiparts using the @acronym{MML}
880 language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME
886 @cindex internationalized domain names
887 @cindex non-ascii domain names
889 Message is a @acronym{IDNA}-compliant posting agent. The user
890 generally doesn't have to do anything to make the @acronym{IDNA}
891 happen---Message will encode non-@acronym{ASCII} domain names in @code{From},
892 @code{To}, and @code{Cc} headers automatically.
894 Until @acronym{IDNA} becomes more well known, Message queries you
895 whether @acronym{IDNA} encoding of the domain name really should
896 occur. Some users might not be aware that domain names can contain
897 non-@acronym{ASCII} now, so this gives them a safety net if they accidently
898 typed a non-@acronym{ASCII} domain name.
900 @vindex message-use-idna
901 The @code{message-use-idna} variable control whether @acronym{IDNA} is
902 used. If the variable is @code{nil} no @acronym{IDNA} encoding will
903 ever happen, if it is set to the symbol @code{ask} the user will be
904 queried, and if set to @code{t} (which is the default if @acronym{IDNA}
905 is fully available) @acronym{IDNA} encoding happens automatically.
907 @findex message-idna-to-ascii-rhs
908 If you want to experiment with the @acronym{IDNA} encoding, you can
909 invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer
910 to have the non-@acronym{ASCII} domain names encoded while you edit
913 Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU
914 Libidn} installed in order to use this functionality.
926 Using the @acronym{MML} language, Message is able to create digitally
927 signed and digitally encrypted messages. Message (or rather
928 @acronym{MML}) currently support @acronym{PGP} (RFC 1991),
929 @acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}.
932 * Signing and encryption:: Signing and encrypting commands.
933 * Using S/MIME:: Using S/MIME
934 * Using PGP/MIME:: Using PGP/MIME
935 * PGP Compatibility:: Compatibility with older implementations
938 @node Signing and encryption
939 @subsection Signing and encrypting commands
941 Instructing @acronym{MML} to perform security operations on a
942 @acronym{MIME} part is done using the @kbd{C-c C-m s} key map for
943 signing and the @kbd{C-c C-m c} key map for encryption, as follows.
948 @findex mml-secure-message-sign-smime
950 Digitally sign current message using @acronym{S/MIME}.
954 @findex mml-secure-message-sign-pgp
956 Digitally sign current message using @acronym{PGP}.
960 @findex mml-secure-message-sign-pgpmime
962 Digitally sign current message using @acronym{PGP/MIME}.
966 @findex mml-secure-message-encrypt-smime
968 Digitally encrypt current message using @acronym{S/MIME}.
972 @findex mml-secure-message-encrypt-pgp
974 Digitally encrypt current message using @acronym{PGP}.
978 @findex mml-secure-message-encrypt-pgpmime
980 Digitally encrypt current message using @acronym{PGP/MIME}.
984 @findex mml-unsecure-message
985 Remove security related @acronym{MML} tags from message.
989 These commands do not immediately sign or encrypt the message, they
990 merely insert the proper @acronym{MML} secure tag to instruct the
991 @acronym{MML} engine to perform that operation when the message is
992 actually sent. They may perform other operations too, such as locating
993 and retrieving a @acronym{S/MIME} certificate of the person you wish to
994 send encrypted mail to. When the mml parsing engine converts your
995 @acronym{MML} into a properly encoded @acronym{MIME} message, the secure
996 tag will be replaced with either a part or a multipart tag. If your
997 message contains other mml parts, a multipart tag will be used; if no
998 other parts are present in your message a single part tag will be used.
999 This way, message mode will do the Right Thing (TM) with
1000 signed/encrypted multipart messages.
1002 Since signing and especially encryption often is used when sensitive
1003 information is sent, you may want to have some way to ensure that your
1004 mail is actually signed or encrypted. After invoking the above
1005 sign/encrypt commands, it is possible to preview the raw article by
1006 using @kbd{C-u C-c RET P} (@code{mml-preview}). Then you can
1007 verify that your long rant about what your ex-significant other or
1008 whomever actually did with that funny looking person at that strange
1009 party the other night, actually will be sent encrypted.
1011 @emph{Note!} Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs
1012 RFC822 headers. They only operate on the @acronym{MIME} object. Keep this
1013 in mind before sending mail with a sensitive Subject line.
1015 By default, when encrypting a message, Gnus will use the
1016 ``signencrypt'' mode, which means the message is both signed and
1017 encrypted. If you would like to disable this for a particular
1018 message, give the @code{mml-secure-message-encrypt-*} command a prefix
1019 argument, e.g., @kbd{C-u C-c C-m c p}.
1021 Actually using the security commands above is not very difficult. At
1022 least not compared with making sure all involved programs talk with each
1023 other properly. Thus, we now describe what external libraries or
1024 programs are required to make things work, and some small general hints.
1027 @subsection Using S/MIME
1029 @emph{Note!} This section assume you have a basic familiarity with
1030 modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and
1033 The @acronym{S/MIME} support in Message (and @acronym{MML}) require
1034 OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt
1035 operations. OpenSSL can be found at @uref{http://www.openssl.org/}.
1036 OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail
1037 addresses from certificates, and it insert a spurious CR character into
1038 @acronym{MIME} separators so you may wish to avoid it if you would like
1039 to avoid being regarded as someone who send strange mail. (Although by
1040 sending @acronym{S/MIME} messages you've probably already lost that
1043 To be able to send encrypted mail, a personal certificate is not
1044 required. Message (@acronym{MML}) need a certificate for the person to whom you
1045 wish to communicate with though. You're asked for this when you type
1046 @kbd{C-c C-m c s}. Currently there are two ways to retrieve this
1047 certificate, from a local file or from DNS. If you chose a local
1048 file, it need to contain a X.509 certificate in @acronym{PEM} format.
1049 If you chose DNS, you're asked for the domain name where the
1050 certificate is stored, the default is a good guess. To my belief,
1051 Message (@acronym{MML}) is the first mail agent in the world to support
1052 retrieving @acronym{S/MIME} certificates from DNS, so you're not
1053 likely to find very many certificates out there. At least there
1054 should be one, stored at the domain @code{simon.josefsson.org}. LDAP
1055 is a more popular method of distributing certificates, support for it
1056 is planned. (Meanwhile, you can use @code{ldapsearch} from the
1057 command line to retrieve a certificate into a file and use it.)
1059 As for signing messages, OpenSSL can't perform signing operations
1060 without some kind of configuration. Especially, you need to tell it
1061 where your private key and your certificate is stored. @acronym{MML}
1062 uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it
1063 contain a @code{custom} group used for this configuration. So, try
1064 @kbd{M-x customize-group RET smime RET} and look around.
1066 Currently there is no support for talking to a CA (or RA) to create
1067 your own certificate. None is planned either. You need to do this
1068 manually with OpenSSL or using some other program. I used Netscape
1069 and got a free @acronym{S/MIME} certificate from one of the big CA's on the
1070 net. Netscape is able to export your private key and certificate in
1071 PKCS #12 format. Use OpenSSL to convert this into a plain X.509
1072 certificate in PEM format as follows.
1075 $ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem
1078 The @file{key+cert.pem} file should be pointed to from the
1079 @code{smime-keys} variable. You should now be able to send signed mail.
1081 @emph{Note!} Your private key is now stored unencrypted in the file,
1082 so take care in handling it. Storing encrypted keys on the disk are
1083 supported, and Gnus will ask you for a passphrase before invoking
1084 OpenSSL. Read the OpenSSL documentation for how to achieve this. If
1085 you use unencrypted keys (e.g., if they are on a secure storage, or if
1086 you are on a secure single user machine) simply press @code{RET} at
1087 the passphrase prompt.
1089 @node Using PGP/MIME
1090 @subsection Using PGP/MIME
1092 @acronym{PGP/MIME} requires an external OpenPGP implementation, such
1093 as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
1094 implementations such as PGP 2.x and PGP 5.x are also supported. One
1095 Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG,
1096 pgg, PGG Manual}), is included, but Mailcrypt is also supported.
1097 @xref{PGP Compatibility}.
1100 Message internally calls GnuPG (the @command{gpg} command) to perform
1101 data encryption, and in certain cases (decrypting or signing for
1102 example), @command{gpg} requires user's passphrase. Currently the
1103 recommended way to supply your passphrase to @command{gpg} is to use the
1104 @command{gpg-agent} program.
1106 To use @command{gpg-agent} in Emacs, you need to run the following
1107 command from the shell before starting Emacs.
1110 eval `gpg-agent --daemon`
1113 This will invoke @command{gpg-agent} and set the environment variable
1114 @code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it.
1115 It might be good idea to put this command in your @file{.xsession} or
1116 @file{.bash_profile}. @xref{Invoking GPG-AGENT, , , gnupg, Using the
1119 Once your @command{gpg-agent} is set up, it will ask you for a
1120 passphrase as needed for @command{gpg}. Under the X Window System,
1121 you will see a new passphrase input dialog appear. The dialog is
1122 provided by PIN Entry (the @command{pinentry} command), and as of
1123 version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a
1124 single tty. So, if you are using a text console, you may need to put
1125 a passphrase into gpg-agent's cache beforehand. The following command
1129 gpg --use-agent --sign < /dev/null > /dev/null
1132 The Lisp variable @code{pgg-gpg-use-agent} controls whether to use
1133 @command{gpg-agent}. See also @xref{Caching passphrase, , , pgg, The
1137 @node PGP Compatibility
1138 @subsection Compatibility with older implementations
1140 @vindex gpg-temp-directory
1141 Note, if you are using the @code{gpg.el} you must make sure that the
1142 directory specified by @code{gpg-temp-directory} have permissions
1145 Creating your own key is described in detail in the documentation of
1146 your PGP implementation, so we refer to it.
1148 If you have imported your old PGP 2.x key into GnuPG, and want to send
1149 signed and encrypted messages to your fellow PGP 2.x users, you'll
1150 discover that the receiver cannot understand what you send. One
1151 solution is to use PGP 2.x instead (i.e., if you use @code{pgg}, set
1152 @code{pgg-default-scheme} to @code{pgp}). If you do want to use
1153 GnuPG, you can use a compatibility script called @code{gpg-2comp}
1155 @uref{http://muppet.faveve.uni-stuttgart.de/~gero/gpg-2comp/}. You
1156 could also convince your fellow PGP 2.x users to convert to GnuPG.
1157 @vindex mml-signencrypt-style-alist
1158 As a final workaround, you can make the sign and encryption work in
1159 two steps; separately sign, then encrypt a message. If you would like
1160 to change this behavior you can customize the
1161 @code{mml-signencrypt-style-alist} variable. For example:
1164 (setq mml-signencrypt-style-alist '(("smime" separate)
1166 ("pgpauto" separate)
1167 ("pgpmime" separate)))
1170 This causes to sign and encrypt in two passes, thus generating a
1171 message that can be understood by PGP version 2.
1173 (Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more
1174 information about the problem.)
1176 @node Various Commands
1177 @section Various Commands
1183 @findex message-caesar-buffer-body
1184 Caesar rotate (aka. rot13) the current message
1185 (@code{message-caesar-buffer-body}). If narrowing is in effect, just
1186 rotate the visible portion of the buffer. A numerical prefix says how
1187 many places to rotate the text. The default is 13.
1191 @findex message-elide-region
1192 @vindex message-elide-ellipsis
1193 Elide the text between point and mark (@code{message-elide-region}).
1194 The text is killed and replaced with the contents of the variable
1195 @code{message-elide-ellipsis}. The default value is to use an ellipsis
1200 @findex message-kill-address
1201 Kill the address under point.
1205 @findex message-kill-to-signature
1206 Kill all the text up to the signature, or if that's missing, up to the
1207 end of the message (@code{message-kill-to-signature}).
1211 @findex message-delete-not-region
1212 Delete all text in the body of t