awesome/lib/lain/wiki/imap.md

Usage

Read here.

Description

Shows mails count fetching over IMAP.

local myimap = lain.widget.imap(args)

New mails are notified like this:

+--------------------------------------------+
| +---+                                      |
| |\ /| donald@disney.org has 3 new messages |
| +---+                                      |
+--------------------------------------------+

Input table

Required parameters are:

Variable	Meaning	Type
server	Mail server	string
mail	User mail	string
password	User password	string
widget	Widget to render	function

while the optional are:

Variable	Meaning	Type	Default
port	IMAP port	integer	993
timeout	Refresh timeout (in seconds)	integer	60
pwdtimeout	Timeout for password retrieval function (see here)	integer	10
is_plain	Define whether password is a plain password (true) or a command that retrieves it (false)	boolean	false
followtag	Notification behaviour	boolean	false
notify	Show notification popups	string	"on"
settings	User settings	function	empty function

settings can use imap_now table, which contains the following non negative integers:

• ["MESSAGES"]
• ["RECENT"]
• ["UNSEEN"]

example of fetch: total = imap_now["MESSAGES"]. For backwards compatibility, settings can also use mailcount, a pointer to imap_now["UNSEEN"].

Also, settings can modify mail_notification_preset table, which will be the preset for the naughty notifications. Check here for the list of variables it can contain. Default definition:

mail_notification _preset = {
    icon = "lain/icons/mail.png",
    position = "top_left"
}

Note that mailcount and imap_now elements are equals to 0 either if there are no new mails or credentials are invalid, so make sure that your settings are correct.

With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting followtag to true it will be shown on the currently focused tag screen.

You can have multiple instances of this widget at the same time.

Password security

The reason why is_plain is false by default is to discourage the habit of storing passwords in plain.

In general, when is_plain == false, password can be either a string, a table or a function: the widget will execute it asynchronously in the first two cases.

Using plain passwords

You can set your password in plain like this:

myimapcheck = lain.widget.imap {
    is_plain = true,
    password = "mymailpassword",
    -- [...]
}

and you will have the same security provided by ~/.netrc.

Using a password manager

I recommend to use spm or pass. In this case, password has to be a function. Example stub:

myimapcheck = lain.widget.imap {
    password = function()
        -- do your retrieval
        return retrieved_password, try_again
    end,
    -- [...]
}

Where retrieved_password is the password retrieved from the manager, and try_again supports DBus Secret Service.

The process flow is that the first password() call spawns the unlock prompt, then the second call retrieves the password. Here is an example of password function.

Output table

Variable	Meaning	Type
widget	The widget	wibox.widget.textbox
update	Update widget	function
timer	The widget timer	gears.timer
pwdtimer	Password retrieval timer (available only if password is a function)	gears.timer

The update function can be used to refresh the widget before timeout expires.

You can use timer to start/stop the widget as you like.