MU-SERVER(1)						      General Commands Manual						      MU-SERVER(1)

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.

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 <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 pip-
	      ing 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)

User Manuals							    April 2012							      MU-SERVER(1)