org-contrib/org-mime.org

   1 #+TITLE:     org-mime.el --- org html export for text/html MIME emails
   2 #+OPTIONS:    H:3 num:nil toc:3 \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   3 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   4 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   5 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   6 #+AUTHOR:     Eric Schulte
   7 #+EMAIL:      schulte.eric at gmail dot com
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 * General
  13
  14 =org-mime= can be used to send HTML email using Org-mode HTML export.
  15
  16 This approximates a WYSiWYG HTML mail editor from within Emacs, and
  17 can be useful for sending tables, fontified source code, and inline
  18 images in email.
  19
  20 * How to use it
  21 ** Setup
  22 If the org-mode =contrib/= directory is in your load path, then
  23 #+begin_src emacs-lisp
  24   (require 'org-mime)
  25 #+end_src
  26 is sufficient to load =org-mime=.
  27
  28 Next you need to tell =org-mime= which Emacs mail agent you use.
  29 - for gnus -- this is set by default
  30   #+begin_src emacs-lisp
  31     (setq org-mime-library 'mml)
  32   #+end_src
  33 - for Wanderlust (WL)
  34   #+begin_src emacs-lisp
  35     (setq org-mime-library 'semi)
  36   #+end_src
  37 - for VM -- not yet supported
  38   #+begin_src emacs-lisp
  39     (setq org-mime-library 'vm)
  40   #+end_src
  41
  42 =org-mime= exposes two functions
  43
  44 - `org-mime-htmlize' :: can be called from within a mail composition
  45      buffer to export either the entire buffer or just the active
  46      region to html, and embed the results into the buffer as a
  47      text/html mime section.
  48      : org-mime-htmlize is an interactive Lisp function in `org-mime.el'.
  49      :
  50      : (org-mime-htmlize ARG)
  51      :
  52      : Export a portion of an email body composed using `mml-mode' to
  53      : html using `org-mode'.  If called with an active region only
  54      : export that region, otherwise export the entire body.
  55      *warning*: There has been some concern voiced over the potential
  56      complexity of email resulting from calling this function on an
  57      active region resulting in multiple =multipart/alternative=
  58      sections in the same email.  Please see [[https://orgmode.org/list/87pr2iwefu.wl%dmaus@ictsoc.de][this email thread]] for a
  59      discussion of the potential pitfalls of this approach.  Speaking
  60      from personal experience this has not been a problem for the
  61      author.
  62
  63 - `org-mime-org-buffer-htmlize' :: can be called from within an
  64      Org-mode buffer to export either the whole buffer or the narrowed
  65      subtree or active region to HTML, and open a new email buffer
  66      including the resulting HTML content as an embedded mime section.
  67      : org-mime-org-buffer-htmlize is an interactive Lisp function in
  68      : `org-mime.el'.
  69      :
  70      : (org-mime-org-buffer-htmlize)
  71      :
  72      : Export the current org-mode buffer to HTML using
  73      : `org-export-as-html' and package the results into an email
  74      : handling with appropriate MIME encoding.
  75
  76
  77 The following key bindings are suggested, which bind the =C-c M-o= key
  78 sequence to the appropriate =org-mime= function in both email and
  79 Org-mode buffers.
  80 #+begin_src emacs-lisp
  81   (add-hook 'message-mode-hook
  82             (lambda ()
  83               (local-set-key "\C-c\M-o" 'org-mime-htmlize)))
  84
  85   (add-hook 'org-mode-hook
  86             (lambda ()
  87               (local-set-key "\C-c\M-o" 'org-mime-org-buffer-htmlize)))
  88 #+end_src
  89
  90 ** CSS style customization
  91 Email clients will often strip all global CSS from email messages.  In
  92 the case of web-based email readers this is essential in order to
  93 protect the CSS of the containing web site.  To ensure that your CSS
  94 styles are rendered correctly they must be included in the actual body
  95 of the elements to which they apply.
  96
  97 The `org-mime-html-hook' allows for the insertion of these important
  98 CSS elements into the resulting HTML before mime encoding.  The
  99 following are some possible uses of this hook.
 100
 101 - for those who use color themes with Dark backgrounds it is useful to
 102   set a dark background for all exported code blocks and example
 103   regions.  This can be accomplished with the following
 104   #+begin_src emacs-lisp
 105     (add-hook 'org-mime-html-hook
 106               (lambda ()
 107                 (org-mime-change-element-style
 108                  "pre" (format "color: %s; background-color: %s; padding: 0.5em;"
 109                                "#E6E1DC" "#232323"))))
 110   #+end_src
 111 - the following can be used to nicely offset block quotes in email
 112   bodies
 113   #+begin_src emacs-lisp
 114     (add-hook 'org-mime-html-hook
 115               (lambda ()
 116                 (org-mime-change-element-style
 117                  "blockquote" "border-left: 2px solid gray; padding-left: 4px;")))
 118   #+end_src
 119
 120 For other customization options see the =org-mime= customization
 121 group.
 122
 123 * Credits
 124
 125 =org-mime= was developed by Eric Schulte with much-appreciated help
 126 and discussion from everyone on the "[[https://orgmode.org/list/f22f52181003211934s70fe468fk54d126dc811c45d2@mail.gmail.com][using orgmode to send html mail]]"
 127 thread especially Eric S. Fraga for adding WL support.