mu-server - Online in the Cloud

PROGRAM:

NAME

mu_server - the mu backend for the mu4e e-mail client

SYNOPSIS

mu server [options]

DESCRIPTION

mu server starts a simple shell in which one can query and manipulate the mu database. The
output of the commands is terms of Lisp symbolic expressions (s-exps). mu server is not
meant for use by humans; instead, it is designed specifically for the mu4e e-mail client.

In this man-page, we document the commands mu server accepts, as well as their responses.
In general, the commands sent to the server are of the form

cmd:<command> [<parameters>]*

where each of the parameters is prefixed by their name and a colon. For example, to view a
certain message, the command would be:

cmd:view docid:12345

Parameters can be sent in any order, and parameters not used by a certain command are
simply ignored.

OUTPUT FORMAT

mu server accepts a number of commands, and delivers its results in the form:

\376<length>\377<s-expr>

\376 (one byte 0xfe), followed by the length of the s-expression expressed as an
hexadecimal number, followed by another \377 (one byte 0xff), followed by the actual s-
expression.

By prefixing the expression with its length, it can be processed more efficiently. The
\376 and \377 were chosen since they never occur in valid UTF-8 (in which the s-
expressions are encoded).

COMMAND AND RESPONSE

add

Using the add command, we can add a message to the database.

-> cmd:add path:<path> maildir:<maildir>
<- (:info add :path <path> :docid <docid>)

compose

Using the compose command, we get the (original) message, and tell what to do with
it. The user-interface is then expected to pre-process the message, e.g. set the
subject, sender and recipient for a reply message.

Messages of type 'new' don't use the docid: parameter, the other ones do.

-> cmd:compose type:<reply|forward|edit|new> [docid:<docid>]
<- (:compose <reply|forward|edit|new> :original <s-exp> :include (<list-of-attachments))

The <list-of-attachments> is an s-expression describing the attachments to include
in the message; this currently only applies to message we are forwarding. This s-
expression looks like:

(:file-name <filename> :mime-type <mime-type> :disposition <disposition>)

contacts

Using the compose command, we can retrieve an s-expression with all known contacts
(name + e-mail address). For the details, see mu-cfind(1).

-> cmd:contacts [personal:true|false] [after:<time_t>]
<- (:contacts ((:name abc :mail foo@example.com ...) ...)

extract

Using the extract command we can save and open attachments.
-> cmd:extract action:<save|open|temp> index:<index> [path:<path>] [what:<what> [param:<param>]]

If the action is 'save', the path argument is required; the attachment will be
saved, and a message
<- (:info save :message "... has been saved")
is sent.

If the action is 'open', the attachment will saved to a temporary file, after which
it will be opened with the default handler for this kind of file (see mu-
extract(1)), and a message
<- (:info open :message "... has been opened")
is sent.

If the action is 'temp', the arguments 'what' is required. The attachment will
saved to a temporary file, and the following message is sent:
<- (:temp :what <what> :param <param :docid 12345)
The front-end can then take action on the temp file, based on what :what and :param
contain. mu4e uses this mechanism e.g. for piping an attachment to a shell command.

find

Using the find command we can search for messages.
-> cmd:find query:"<query>" [threads:true|false] [sortfield:<sortfield>]
[reverse:true|false] [maxnum:<maxnum>]
The query-parameter provides the search query; the threads-parameter determines
whether the results will be returned in threaded fashion or not; the sortfield-
parameter (a string, "to", "from", "subject", "date", "size", "prio") sets the
search field, the reverse-parameter, if true, set the sorting order Z->A and,
finally, the maxnum-parameter limits the number of results to return (<= 0 means
'unlimited').

First, this will return an 'erase'-sexp, to clear the buffer from possible results
from a previous query.
<- (:erase t)

This will return a series of 0 up to <maxnum> s-expression corresponding to each
message found (if there's no maxnum, all results will be returned). The information
message s-exps this function returns do not contain the message body; the view
command is for that.
<- (...)
and finally, we receive:
<- (:found <number-of-matches>)

guile The guile command is reserved for future use.

index

Using the index command, we can (re)index the database, similar to what mu find
does. The my-addresses parameter (optionally) registers 'my' email addresses; see
the documentation for mu_store_set_my_addresses.

-> cmd:index path:<path> [my-addresses:<comma-separated-list-of-email-addresses>]
As a response, it will send (for each 500 messages):
(:info index :status running :processed <processed> :updated <updated>)
and finally:
(:info index :status complete :processed <processed :updated <updated>
:cleaned-up <cleaned-up>)

mkdir

Using the mkdir command, we can create a new maildir.

-> cmd:mkdir path:<path>
<- (:info mkdir :message "<maildir> has been created")

move

Using the move command, we can move messages to another maildir or change its flags
(which ultimately means it is being move to a different filename), and update the
database correspondingly. The function returns an s-exp describing the updated
message, so that it can be updated in the user interface.

-> cmd:move docid:<docid>|msgid:<msgid> [maildir:<maildir>] [flags:<flags>]
<- (:update <s-exp> :move t)

One of docid and msgid must be specified to identify the message. At least one of
maildir and flags must be specified.

ping

The ping command provokes a pong response. It is used for the initial handshake
between mu4e and mu server.
-> cmd:ping
<- (:pong "mu" :version <version> :doccount <doccount>)

remove

Using the remove command, we can remove the message from disk, and update the
database accordingly.

-> cmd:remove docid:<docid>
<- (:remove <docid>)

view

Using the view command, we can retrieve all information (including the body) of a
particular e-mail message.

If the optional parameter extract-images is true, extract images to temp files, and
include links to them in the returned s-exp.

If the optional parameter use-agent is true, try to use gpg-agent when verifying
PGP/GPG message parts.

If the optional parameter auto-retrieve-key is true, attempt to retrieve public
keys online automatically.

-> cmd:view docid:<docid>|msgid:<msgid> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
<- (:view <s-exp>)

or, alternatively:

-> cmd:view path:<path-to-msg> [extract-images:true] [use-agent:false] [auto-retrieve-key:false]
<- (:view <s-exp>)

Use mu-server online using onworks.net services