mu/man/mu-cfind.1.org

MU CFIND

• NAME
• SYNOPSIS
• DESCRIPTION
• SEARCHING CONTACTS
• CFIND OPTIONS
  • –format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv
  • –personal,-p only show addresses seen in messages where one of `my' e-mail
  • –after=<timestamp> only show addresses last seen after
• JSON FORMAT
• INTEGRATION WITH MUTT
• ENCODING
• SEE ALSO

NAME

mu-cfind - find contacts in the mu database and export them for use in other programs.

SYNOPSIS

mu [common-options] cfind [options] [<pattern>]

DESCRIPTION

mu cfind is the mu command for finding contacts (name and e-mail address of people who were either an e-mail's sender or receiver). There are different output formats available, for importing the contacts into other programs.

SEARCHING CONTACTS

When you index your messages (see mu index), mu creates a list of unique e-mail addresses found and the accompanying name, and caches this list. In case the same e-mail address is used with different names, the most recent non-empty name is used.

mu cfind starts a search for contacts that match a regular expression. For example:

$ mu cfind '@gmail\.com'

would find all contacts with a gmail-address, while

$ mu cfind Mary

lists all contacts with Mary in either name or e-mail address.

If you do not specify a search expression, mu cfind returns the full list of contacts. Note, mu cfind uses a cache with the e-mail information, which is populated during the indexing process.

The regular expressions are basic case-insensitive PCRE, see pcre(3).

CFIND OPTIONS

–format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv

sets the output format to the given value. The following are available:

–format=	description
plain	default, simple list
mutt-alias	mutt alias-format
mutt-ab	mutt external address book format
wl	wanderlust addressbook format
org-contact	org-mode org-contact format
bbdb	BBDB format
csv	comma-separated values [1]
json	JSON format

[1] CSV is not fully standardized, but mu cfind follows some common practices: any double-quote is replaced by a double-double quote (thus, "hello" become ""hello"", and fields with commas are put in double-quotes. Normally, this should only apply to name fields.

–personal,-p only show addresses seen in messages where one of `my' e-mail

addresses was seen in one of the address fields; this is to exclude addresses only seen in mailing-list messages. See the --my-address parameter to mu init.

–after=<timestamp> only show addresses last seen after

<timestamp>. <timestamp> is a UNIX time_t value, the number of seconds since 1970-01-01 (in UTC).

From the command line, you can use the date command to get this value. For example, only consider addresses last seen after 2020-06-01, you could specify

  --after=`date +%s --date='2020-06-01'`

JSON FORMAT

With --format=json, the matching contacts come out as a JSON array, e.g.,

[
  {
    "email"         : "syb@example.com",
    "name"          : "Sybil Gerard",
    "display"       : "Sybil Gerard <syb@example.com>",
    "last-seen"     : 1075982687,
    "last-seen-iso" : "2004-02-05T14:04:47Z",
    "personal"      : false,
    "frequency"     : 14
  },
  {
    "email"         : "ed@example.com",
    "name"          : "Mallory, Edward",
    "display"       : "\"Mallory, Edward\" <ed@example.com>",
    "last-seen"     : 1425991805,
    "last-seen-iso" : "2015-03-10T14:50:05Z",
    "personal"      : true,
    "frequency"     : 2
  }
]

Each contact has the following fields:

property	description
email	the email-address
name	the name (or none)
display	the combination name and e-mail address for display purposes
last-seen	date of most recent message with this contact (Unix time)
last-seen-iso	last-seen represented as an ISO-8601 timestamp
personal	whether the email was seen in a message together with a personal address
frequency	approximation of the number of times this contact was seen in messages

The JSON format is useful for further processing, e.g. using the jq(1) tool:

List display names, sorted by their last-seen date:

$ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort

INTEGRATION WITH MUTT

You can use mu cfind as an external address book server for mutt. For this to work, add the following to your muttrc:

set query_command = "mu cfind --format=mutt-ab '%s'"

Now, in mutt, you can search for e-mail addresses using the query-command, which is (by default) accessible by pressing Q.

ENCODING

mu cfind output is encoded according to the current locale except for --format=bbdb. This is hard-coded to UTF-8, and as such specified in the output-file, so emacs/bbdb can handle things correctly, without guessing.

SEE ALSO

mu(1), mu-index(1), mu-find(1), pcre(3), jq(1)