Conky Mail Notifications using Maildirs

Configuring conky to display a count and symbol of new mail turned out to be more tricky than I had originally anticipated. This small post quickly explores the issues and my own misunderstandings that led to a working conky configuration and a better understanding of maildir.

When the documentation fails you, use the source.

I've been trying to configure conky to show an icon if there is new mail in my local maildir. However, I'm seemingly unable to achieve the desired result.

Here is a trimmed down version of my conky configuration for reference:

This is using conky's new 1.10 syntax.

conky.config = {
    out_to_x = false,
    own_window = false,
    out_to_console = true,
    background = false,

conky.text = [[
    ${mails ${HOME}/.mail/} 

However, when attempting to run this through conky, I receive the following error:

conky: cannot open directory

I also tried adding the mail_spool configuration setting to the conky.config table and removing the folder from the ${mails} variable. Furthermore, I tried both of the above using the ${new_mails} variable as well, similarly to no avail.

I actually receive a different error suggesting that mail_spool is no longer a valid configuration setting. Searching the code base, I feel this is accurate.

Another variation of the above I have tried is to try quoting the directory path, which failed with a different error suggesting conky is attempting to literally open the quoted folder.

It wasn't until I read the source of conky that I was able to figure out what the actual issue was.

What was not obvious to me from the documentation was that $mails and friends request a literal maildir as its parameter. This means, it's required to specify a folder with the triplet of folders: cur, new, and tmp under it. Without which, conky returns the error "cannot open directory" because conky is trying to open the directory {provided-mail-directory}/cur instead of the provided directory.

Therefore, to solve my issue, I had changed the path given to $mails to the following:

${mails ${HOME}/{email-account}/INBOX}

Where {email-account} is the email account I want updates for.

This has been a frustrating experience, and the documentation around conky is unfortunately out of date. But this is partially my own fault, my understanding of maildir was incorrect and certainly led me astray.

I'm debating whether to submit a pull request for expanding the documentation around maildir usage in the $*mails variables but it's likely my own misunderstanding of maildir that led me to so much issue.

Next, onto conky's use of if_match and $battery_short to display different battery symbols based on "charging", "discharging" and "full" states.