A minimalistic address book for e-mails only (mainly for aerc)
Skip mailboxes containing non-ASCII characters
Handle =?utf-8?b? (lowercase b or q)



You can also use your local clone with git send-email.


A minimalistic address book for e-mails only.


Install Janet if necessary (p.e. on Arch Linux: yay -S janet-lang, about 3 MB).

Clone this repository:

git clone https://git.sr.ht/~maxgyver83/emailbook-janet

If don't have Janet installed and really don't want to install it, simply download this binary (for Linux, x86-64), about 850 kB (TODO: Add link). (In this case, replace all further occurrences of emailbook.janet with emailbook-janet.)

If you like, copy emailbook.janet to a directory which is in your PATH (p.e. $HOME/.local/bin/ or /usr/local/bin/). (Otherwise, use always the full path.)


#Command line

#Add a new entry like this:
emailbook.janet ~/emailbook.txt --add 'jd : John Doe <john.doe@example.com>'

Entries should look like MAILBOX or ALIAS : MAILBOX.

  • ALIAS is your personal abbreviation (optional).
  • See How a mailbox looks like (=optional display name plus e-mail address).
#Search a recipient:
emailbook.janet ~/emailbook.txt --search 'john'
emailbook.janet ~/emailbook.txt --key 'jd'
emailbook.janet ~/emailbook.txt --value 'john'

--search looks both at keys (=aliases) and values. --key and --value limit the search accordingly.

#Add all senders/recipients from an e-mail to your address book:
cat test/sample1 | emailbook.janet ~/emailbook.txt --parse --all

This skips p.e. "John Doe" <jd@example.com> when the address book already contains the same entry without double quotes (and vice versa).

Plain e-mail addresses are wrapped in angle brackets automatically.

E-mails like noreply@example.com are always ignored.


emailbook.janet might work for other e-mail clients but it was tested only with aerc.

#Use emailbook for autocompletion of e-mail senders/recipients:

Add this line to ~/.config/aerc/aerc.conf, [compose] section:

address-book-cmd=emailbook.janet /home/user/emailbook.txt --search "%s"

Note: aerc adds double quotes and angle brackets automatically during autocompletion.

#Add binding to add all senders/recipients from current e-mail:

Add this line to ~/.config/aerc/binds.conf, [view] section:

aa = :pipe -m emailbook.janet /home/user/emailbook.txt --parse --all<Enter>

Just an example. aa stands for "add all".

You could also use a separate binding for adding only the sender:

af = :pipe -m emailbook.janet /home/user/emailbook.txt --parse --from<Enter>

#How a mailbox looks like

A mailbox is an e-mail address plus optionally a display name.

E-mail senders/recipients should be written like these examples:

  • john.doe@example.com
  • <john.doe@example.com>
  • John Doe <john.doe@example.com>
  • "Doe, Joe" <john.doe@example.com>

Normally, a mailbox is composed of two parts: (1) an optional display name that indicates the name of the recipient (which can be a person or a system) that could be displayed to the user of a mail application, and (2) an addr-spec address enclosed in angle brackets ("<" and ">"). There is an alternate simple form of a mailbox where the addr-spec address appears alone, without the recipient's name or the angle brackets.

RFC 5322, Section 3.4

Double-quote the display name if it contains other characters than:

ALPHA DIGIT ! # $ % & ' * + - / = ? ^ _ ` { | } ~

#Prior art

emailbook.janet is a rewrite of emailbook (POSIX shell script) which is heavily inspired by/similar to ~renerocksai/aercbook. But there are some differences:

emailbook.janet ...

  • is written in Janet,
  • doesn't add aliases automatically,
  • strips single quotes around display names (both 'xxx' and "'xxx'"),
  • strips redundant display names (p.e. "john@example.com" <john@example.com>),
  • skips noreply entries during parsing,
  • decodes encoded names like =?UTF-8?Q?M=C3=BCller?= (→ Müller),
  • only returns relevant entries for queries.

Now, this applies also to aercbook:

  • parses all recipients, not only the first line,
  • decodes encoded names like =?UTF-8?B?5byg5LiJ?= (→ 张三).