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

          <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.

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.

              -> 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 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-
              exprssion 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).

              -> 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.
              -> 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.
              -> 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.

              -> 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.

              -> 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 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.

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

              or, alternatively:

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

AUTHOR

       Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

SEE ALSO

       mu(1)