NAME¶
mu_server - the mu backend for the mu4e e-mail client
DESCRIPTION¶
mu server starts a simple shell in which can 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
<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:
view docid:12345
Parameters can be sent in any order, and parameters not used by a certain
command are simply ignored.
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.
-> 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.
-> compose <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-exprssion looks like:
(:file-name <filename> :mime-type <mime-type> :disposition <disposition>)
- extract
-
Using the extract command we can save and open attachments.
-> 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)
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.
-> find query:"<query>" [maxnum:<maxnum>]
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>)
- index
-
Using the index command, we can (re)index the database, similar to
what mu find does.
-> index path:<path>
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.
-> 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.
-> 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.
-> ping
<- (:pong "mu" :version <version> :doccount <doccount>)
- remove
-
Using the remove command, we can remove the message from disk, and
update the database accordingly.
-> remove docid:<docid>
<- (:remove <docid>)
- view
-
Using the view command, we can all information (including the body)
of a particular e-mail message.
-> view docid:<docid>|msgid:<msgid>
<- (:view <s-exp>)
AUTHOR¶
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
SEE ALSO¶
mu(1)