mu server [options]
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
where each of the parameters is prefixed by their name and a colon. For example, to view a certain message, the command would be:
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 (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
Using the add command, we can add a message to the database.
-> cmd:add path:<path> maildir:<maildir> <- (:info add :path <path> :docid <docid>)
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>)
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 [email protected] ...) ...)
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.
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>)
The guile command is reserved for future use.
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 1000 messages):
(:info index :status running :processed <processed> :updated <updated>)and finally:
(:info index :status complete :processed <processed :updated <updated> :cleaned-up <cleaned-up>)
Using the mkdir command, we can create a new maildir.
-> cmd:mkdir path:<path> <- (:info mkdir :message "<maildir> has been created")
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.
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>)
Using the remove command, we can remove the message from disk, and update the database accordingly.
-> cmd:remove docid:<docid> <- (:remove <docid>)
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>)
-> cmd:view path:<path-to-msg> [extract-images:true] [use-agent:false] [auto-retrieve-key:false] <- (:view <s-exp>)
AUTHORDirk-Jan C. Binnema <[email protected]>