README.md
1
2
3## An extensible mail notification daemon
4
5Mailnag is a daemon program that checks POP3 and IMAP servers for new mail.
6On mail arrival it performs various actions provided by plugins.
7Mailnag comes with a set of desktop-independent default plugins for
8visual/sound notifications, script execution etc. and can be extended
9with additional plugins easily.
10
11__This project needs your support!__
12If you like Mailnag, please help to keep it going by [contributing code](https://github.com/pulb/mailnag),
13[reporting/fixing bugs](https://github.com/pulb/mailnag/issues), [translating strings into your native language](https://hosted.weblate.org/projects/mailnag/mailnag/),
14[writing docs](https://github.com/pulb/mailnag/wiki) or by [making a donation](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=8F5FNJ3U4N7AW).
15
16<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=8F5FNJ3U4N7AW" target="_blank">
17<img src="https://www.paypalobjects.com/en_US/GB/i/btn/btn_donateCC_LG.gif" alt="PayPal — The safer, easier way to pay online."/></a>
18
19## Installation
20
21### Ubuntu
22Mailnag has an official [Ubuntu PPA](https://launchpad.net/~pulb/+archive/mailnag).
23Issue the following commands in a terminal to enable the PPA and install Mailnag.
24
25 sudo add-apt-repository ppa:pulb/mailnag
26 sudo apt-get update
27 sudo apt-get install mailnag
28
29As of Ubuntu 13.04 (Raring), Mailnag is also available in the official repos.
30Run `sudo apt-get install mailnag` in a terminal to install it.
31
32### Debian
33Mailnag is available in Debian stable and unstable.
34Run `sudo apt-get install mailnag` in a terminal to install it.
35
36### Fedora
37As of Fedora 17, Mailnag is available in the official Fedora repos.
38Just run `yum install mailnag` (as root) in a terminal to install the package.
39
40### Arch Linux
41Mailnag is available in the official repos.
42Please run `pacman -Syu mailnag` (as root) to install the package.
43
44### openSUSE
45Mailnag is available in openSUSE Tumbleweed.
46Run `sudo zypper install mailnag` in a terminal to install it.
47
48### Generic Tarballs
49Distribution independent tarball releases are available [here](https://github.com/pulb/mailnag/releases).
50Just run `./setup.py install` (as root) to install Mailnag,
51though make sure the requirements stated below are met.
52
53###### Requirements
54* python (>= 3.5)
55* pygobject
56* gir-notify (>= 0.7.6)
57* gir-gtk-3.0
58* gir-gdkpixbuf-2.0
59* gir-glib-2.0
60* gir-gst-plugins-base-1.0
61* python-dbus
62* pyxdg
63* gettext
64* gir1.2-secret-1 (optional)
65
66
67## Configuration
68Run `mailnag-config` to setup Mailnag.
69Closing the configuration window will start Mailnag automatically.
70
71### Default Mail Client
72Clicking a mail notification popup will open the default mail client specified in `GNOME Control Center -> Details -> Default Applications`.
73If you're a webmail (e.g. gmail) user and want your account to be launched in a browser, please install a tool like [gnome-gmail](http://gnome-gmail.sourceforge.net).
74
75### Desktop Integration
76By default, Mailnag emits libnotify notifications, which work fine on most desktop environments
77but are visible for a few seconds only. If you like to have a tighter desktop integration
78(e.g. a permanently visible indicator in your top panel) you have to install an appropriate
79extension/plugin for your desktop shell. Currently the following desktop shells are supported:
80* GNOME-Shell ([GNOME-Shell extension](https://github.com/pulb/mailnag-gnome-shell))
81* KDE ([Plasma 5 applet by driglu4it](https://store.kde.org/p/1420222/))
82* Cinnamon ([Applet by hyOzd](https://bitbucket.org/hyOzd/mailnagapplet))
83* Elementary Pantheon ([MessagingMenu plugin](https://github.com/pulb/mailnag-messagingmenu-plugin))
84* XFCE ([MessagingMenu plugin](https://github.com/pulb/mailnag-messagingmenu-plugin))
85
86Furthermore, I highly recommend GNOME users to install the [GOA plugin](https://github.com/pulb/mailnag-goa-plugin),
87which makes Mailnag aware of email accounts specified in GNOME Online Accounts.
88
89### Troubleshooting
90
91__Gmail doesn't work__
92If Mailnag is unable to connect to your Gmail account, please try the following solutions:
93* Install the [GOA plugin](https://github.com/pulb/mailnag-goa-plugin) to connect via GNOME online accounts
94* Have a look at the [FAQ](https://github.com/pulb/mailnag/wiki/FAQ)
95* Try to apply [this](https://github.com/pulb/mailnag/issues/190) workaround
96
97__Other issues__
98If Mailnag doesn't work properly for you, either examine the system log for errors (`journalctl -b _COMM=mailnag`)
99or run `mailnag` in a terminal and observe the output.
100
101
){kind=link}
