org-contrib/org-mime.org

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