mu4e-alert

mu4e-alert copied to clipboard

• mu4e alert

  [[./CHANGELOG.org][file:https://img.shields.io/badge/version-v0.4-blue.svg]] [[http://melpa.org/#/mu4e-alert][file:http://melpa.org/packages/mu4e-alert-badge.svg]] [[http://stable.melpa.org/#/mu4e-alert][file:http://stable.melpa.org/packages/mu4e-alert-badge.svg]] [[http://www.gnu.org/licenses/gpl-3.0.html][http://img.shields.io/:license-gpl3-blue.svg]] [[http://makeapullrequest.com][file:https://img.shields.io/badge/PRs-welcome-brightgreen.svg]]

  [[https://raw.githubusercontent.com/iqbalansari/mu4e-alert/master/screenshots/mu4e-alert-in-action.png][screenshots/mu4e-alert-in-action.png?raw=true]]

** Table of contents :TOC_4_gh:

• [[#mu4e-alert][mu4e alert]]
  • [[#what-is-this][What is this?]]
  • [[#requirements][Requirements]]
  • [[#installation][Installation]]
    • [[#elpa][ELPA]]
    • [[#el-get][El-get]]
  • [[#usage][Usage]]
    • [[#desktop-notifications-for-unread-emails][Desktop notifications for unread emails]]
    • [[#mode-line-display-of-unread-emails][Mode Line display of unread emails]]
  • [[#customizations][Customizations]]
    • [[#general-options][General options]]
    • [[#customizing-the-desktop-notifications][Customizing the desktop notifications]]
      • [[#customizing-the-types-of-notifications-displayed][Customizing the types of notifications displayed]]
      • [[#customizing-the-notifications-for-unread-emails-counts][Customizing the notifications for unread emails counts]]
      • [[#customizing-the-notifications-for-unread-emails-subjects][Customizing the notifications for unread emails subjects]]
      • [[#customizing-urgency-hint][Customizing urgency hint]]
    • [[#customizing-the-mode-line-display][Customizing the mode-line display]]
  • [[#getting-desktop-notifications][Getting desktop notifications]]
    • [[#linux][Linux]]
      • [[#notifications][notifications]]
      • [[#libnotify][libnotify]]
    • [[#mac-osx][Mac OSX]]
      • [[#growl][growl]]
      • [[#notifier][notifier]]
  • [[#advanced-customizations][Advanced customizations]]

** What is this? mu4e-alert is an Emacs extension providing desktop notifications for [[https://github.com/djcb/mu][mu4e]], additionally it can display the number of unread emails in the mode-line.

** Requirements This package requires Emacs v24.3 or above and Mu version [[https://github.com/djcb/mu/releases/tag/v0.9.9.6][v0.9.9.6]] or above. It assumes that you have a working mu/mu4e setup.

** Installation *** ELPA ~mu4e-alert~ is available on [[http://melpa.org/#/mu4e-alert][MELPA]] and [[http://stable.melpa.org/#/mu4e-alert][MELPA Stable]]. Please follow the instructions on MELPA [[http://melpa.org/#/getting-started][website]] to enable it, if you haven't already.

You can then install ~mu4e-alert~ from the [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Menu.html][package menu]]. Alternatively
install it by doing the following

Refresh the package index
#+BEGIN_QUOTE
M-x package-refresh-contents RET
#+END_QUOTE

And then install it by doing
#+BEGIN_QUOTE
M-x package-install RET mu4e-alert
#+END_QUOTE

*** El-get ~mu4e-alert~ can also be installed using ~el-get~. Assuming you have latest version of el-get installing it by doing something similar to #+BEGIN_QUOTE M-x el-get-install RET mu4e-alert #+END_QUOTE

** Usage *** Desktop notifications for unread emails To enable desktop notifications manually, use the command ~mu4e-alert-enable-notifications~. To enable notification automatically on Emacs startup add something like the following to your ~init~ file

#+BEGIN_SRC emacs-lisp
  ;; Choose the style you prefer for desktop notifications
  ;; If you are on Linux you can use
  ;; 1. notifications - Emacs lisp implementation of the Desktop Notifications API
  ;; 2. libnotify     - Notifications using the `notify-send' program, requires `notify-send' to be in PATH
  ;;
  ;; On Mac OSX you can set style to
  ;; 1. notifier      - Notifications using the `terminal-notifier' program, requires `terminal-notifier' to be in PATH
  ;; 1. growl         - Notifications using the `growl' program, requires `growlnotify' to be in PATH
  (mu4e-alert-set-default-style 'libnotify)
  (add-hook 'after-init-hook #'mu4e-alert-enable-notifications)
#+END_SRC

~mu4e-alert~ uses the value of ~alert-default-style~ as the default
notification style, which defaults to ~message~, if you want to use different
style please add a rule for category "mu4e-alert" using alert's API or use
the function ~mu4e-alert-set-default-style~ to customize the value of
~mu4e-alert-style~.

You can disable notifications using the command ~mu4e-alert-disable-notifications~

*** Mode Line display of unread emails Display of the unread email count in the mode-line can be enabled using the command ~mu4e-alert-enable-mode-line-display~ or adding something like the following to your ~init~ file

#+BEGIN_SRC emacs-lisp
  (add-hook 'after-init-hook #'mu4e-alert-enable-mode-line-display)
#+END_SRC

After enabling mode-line display the unread emails can be viewed by clicking
the mode-line indicator.

Use the command ~mu4e-alert-disable-mode-line-display~ to disable mode-line
indication of unread emails

** Customizations ~mu4e-alert~ should work with default options, nevertheless it offers the following customizations. Please see the ~mu4e-alert.el~ file or do =M-x= customize-group =RET= mu4e-alert =RET= to for documentation of customizable options.

*** General options The query used to find unread (read 'interesting') emails can be customized using the variable ~mu4e-alert-interesting-mail-query~. So, for example, if you want ~mu4e-alert~ to ignore a certain maildir you can customize it to do so. In this example, we ignore a maildir that is located at ~/[Gmail].All Mail~ by adding this to the ~init.el~ file:

#+BEGIN_SRC emacs-lisp
  (setq mu4e-alert-interesting-mail-query
        (concat
         "flag:unread"
         " AND NOT flag:trashed"
         " AND NOT maildir:"
         "\"/[Gmail].All Mail\""))
#+END_SRC

*** Customizing the desktop notifications **** Customizing the types of notifications displayed ~mu4e-alert~ can display both the count as well subject of unread emails in the desktop notifications. Use the variable ~mu4e-alert-email-notification-types~ to customize the type of notifications displayed. It should be set to a list of types of notification you want to receive. Following are the notification types supported for now

- count    - Display the count of unread emails
- subjects - Display the subject of unread emails

For example, adding the following snippet to your init file, will instruct
~mu4e-alert~ to only display the number of unread emails.

#+BEGIN_SRC emacs-lisp
  (setq mu4e-alert-email-notification-types '(count))
#+END_SRC

**** Customizing the notifications for unread emails counts ~mu4e-alert~ allows you to customize the notifications for emails count by setting the following values

 |-----------------------------------------------+-------------------------------------------------------|
 | Variable                                      | Aspect customized                                     |
 |-----------------------------------------------+-------------------------------------------------------|
 | mu4e-alert-email-count-title                  | Title used for email count notifications              |
 | mu4e-alert-email-count-notification-formatter | Formatting the message body of the email notification |
 |-----------------------------------------------+-------------------------------------------------------|

**** Customizing the notifications for unread emails subjects For displaying subjects of unread emails, ~mu4e-alert~ groups unread emails according some criteria. Then subjects of the emails in each of the groups are displayed in separate desktop notifications.

 The following variables can be used to customize the notifications for subjects

 |------------------------------------------------+-------------------------------------------------------------------------------------------------------------|
 | Variable                                       | Aspect customized                                                                                           |
 |------------------------------------------------+-------------------------------------------------------------------------------------------------------------|
 | mu4e-alert-mail-grouper                        | Function used to group unread emails                                                                        |
 | mu4e-alert-group-by                            | Field used to group emails (this is applicable only if mu4e-alert-mail-grouper is set to the default value) |
 | mu4e-alert-grouped-mail-sorter                 | Function used to sort the groups of unread emails                                                           |
 | mu4e-alert-grouped-mail-notification-formatter | Function used to get notification for group of unread emails                                                |
 | mu4e-alert-notify-repeated-mails               | If set to non-nil, ~mu4e-alert~ displays notifications for all emails irrespective of whether user has been |
 |                                                | notified about the email earlier. By default user is not notified about such repeated emails                |
 |------------------------------------------------+-------------------------------------------------------------------------------------------------------------|

**** Customizing urgency hint By default ~mu4e-alert~ sets the urgency hint for current Emacs frame (or the any mu4e frame if available), you can disable it by setting the variable ~mu4e-alert-set-window-urgency~ to ~nil~.

*** Customizing the mode-line display The mode-line indicator for unread emails can be customized by setting the value of the variable ~mu4e-alert-modeline-formatter~

** Getting desktop notifications By default the user is notified of unread messages using Emacs' ~message~ function. To get desktop notifications you can instruct ~mu4e-alert~ to use an appropriate style [[https://github.com/jwiegley/alert#builtin-alert-styles][provided]] by the ~alert~ library that works on your system.

The easiest way to do this is use the function ~mu4e-alert-set-default-style~, calling it with the style to be used for notifications

The styles available vary according to the OS

*** Linux The following styles for desktop notifications, are available on Linux

**** notifications This style uses ~notifications.el~ an implementation of the Desktop Notifications API, which ships with Emacs. It requires that Emacs is compiled with DBus support

**** libnotify This style uses the command-line program ~notify-send~ to notify the user. The program should be in ~PATH~

*** Mac OSX The following styles for desktop notifications, are available on Mac OSX. Also see the discussion on the issue [[https://github.com/iqbalansari/mu4e-alert/issues/2][Does it works with MacOS X?]]

**** growl This style uses the command-line program ~growlnotify~ to notify the user using ~Growl~. The program should be in ~PATH~

**** notifier This style uses the command-line program ~terminal-notifier~ to notify the user. The program should be in ~PATH~

** Advanced customizations ~mu4e-alert~ uses the excellent [[https://github.com/jwiegley/alert][alert]] library for desktop notifications, more fine-grained customizations to the notifications can be done by using the ~alert~'s API.

As an example the following customization will color the fringe (along with the usual desktop notification) if there are unread messages and the user is visiting one of ~mu4e-main-view~, ~mu4e-headers-view~ or viewing an email in mu4e.

#+BEGIN_SRC emacs-lisp (mu4e-alert-set-default-style 'libnotify) (alert-add-rule :category "mu4e-alert" :style 'fringe :predicate (lambda (_) (string-match-p "^mu4e-" (symbol-name major-mode))) :continue t) (mu4e-alert-enable-notifications) #+END_SRC