Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MU-SERVER(1)		    General Commands Manual		  MU-SERVER(1)

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

       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; in-
       stead, 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 cer-
       tain command are	simply ignored.

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


       \376  (one  byte	 0xfe),	followed by the	length of the s-expression ex-
       pressed 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).


	      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	recip-
	      ient 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 at-
	      tachments	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

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


	      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 at-
	      tachment 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	tempo-
	      rary  file,  after which it will be opened with the default han-
	      dler 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-pa-
	      rameter  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 re-
	      sults 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 cor-
	      responding to each message found (if there's no maxnum, all  re-
	      sults  will  be  returned).  The information message s-exps this
	      function returns do not contain the message body;	the view  com-
	      mand is for that.
	      <- (...)
	      and finally, we receive:
	      <- (:found <number-of-matches>)

       guile  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

	      -> 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  mes-
	      sage. 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 (includ-
	      ing 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>)

       Dirk-Jan	C. Binnema <>


User Manuals			September 2012			  MU-SERVER(1)


Want to link to this manual page? Use this URL:

home | help