README

   1 NEATMAIL
   2 ========
   3
   4 Neatmail is a noninteractive mail client.  It generates listings of,
   5 and executes ex-like commands on messages in mailboxes in mbox format.
   6
   7 Neatmail provides the following commands (when invoked without an
   8 argument, most of them show a summary of supported options).
   9
  10 * mk: generate a listing of messages in an mbox.
  11 * ex: execute the specified commands on an mbox.
  12 * pg: page a message in an mbox.
  13 * pn: prune an mbox (shorten messages).
  14 * ns: check for new messages among several mboxes.
  15 * me: MIME-encode message headers.
  16
  17 For each message, the mk command writes tab-separated values of some
  18 of its headers.  This set of headers and the maximum length of each of
  19 them can be specified with -0 option.  In addition to message headers,
  20 ~subject (more compact subject header with thread indentation), ~size
  21 (message size), and ~date (receiving date) can also be given.  Each
  22 line begins with the value of the status header of the message (N if
  23 it is missing) and its message number.  Neatmail assumes that the
  24 status of a message, if present, is one or two capital letters (the
  25 first letter may be N for new, R for read, and O for old; the second
  26 letter, if present, may indicate user-defined categories).  This is an
  27 example invocation of mk:
  28
  29 $ neatmail mk -0 10from:20~subject: -st test/test.mbox
  30 N00000  [A <a@a.eu>]    [Message from A      ]
  31 N00001  [B <b@b.eu>]    [Message from B      ]
  32 N00002  [C <c@c.eu>]    [Message from C      ]
  33
  34 The ex command reads a list of commands from the standard input and
  35 executes them on a given mbox file.  It ignores all input lines except
  36 those beginning with a colon or a capital letter.  Lines beginning
  37 with a capital letter like "R100 ...", change the value of the status
  38 header of the message whose number follows the letter.  It also marks
  39 the current message.  Lines beginning with a colon are named commands.
  40 The list of named commands are as follows:
  41
  42 * rm: remove the message.
  43 * cp: copy the message to another mbox.
  44 * mv: move the message to another mbox.
  45 * hd, set: change the value of the given header of the message.
  46 * ft, filt: filter the message through the given command.
  47 * w: write the mbox.
  48 * g, g!: ex-like global command.
  49 * tj: join threads by modifying "Reply-To" headers.
  50 * ch: chop the message at the specified offset in kilobytes.
  51
  52 These commands act on the current message by default (if applicable),
  53 but different messages may be specified using ex-like addresses.  For
  54 instance, "2,5rm" removes messages 2 through 5.  Addresses may contain
  55 search patterns, like "/pattern/rm", in which the pattern is a POSIX
  56 extended regular expression (the same applies to global command
  57 patterns like "%g/pattern/rm").  Search patterns are matched to the
  58 subject field of message headers, except when the pattern is "^field:
  59 value", in which it is matched against the specified header field
  60 instead.
  61
  62 In the following example, ex removes message 1, moves all messages
  63 whose subjects match ".*neatmail.*" to mail.mbox file, and updates the
  64 mbox.
  65
  66 $ neatmail ex new.mbox <<EOF
  67 O000
  68 O001
  69 :rm
  70 R003
  71 R002
  72 N004
  73 :%g/^subject:.*neatmail.*/mv mail.mbox
  74 :w
  75 EOF
  76
  77 SUGGESTED USAGE
  78 ===============
  79
  80 Generate a message listing (see mk options):
  81 $ neatmail mk -st -r inbox >inbox.nm
  82
  83 Open inbox.nm in an editor, change the status field of
  84 messages, and append ex commands.
  85
  86 Page, reply, or forward messages (see pg options):
  87 $ neatmail pg -m -h from: -h subject: -h to: -h cc: 23@inbox >mail
  88
  89 Execute the commands specified in inbox.nm:
  90 $ (cat inbox.nm; echo ":w") | neatmail ex inbox
  91
  92 It is more convenient to place these commands in a script.  For
  93 fetching and sending messages, I use https://github.com/aligrudi/neatpop3
  94 and https://github.com/aligrudi/neatsmtp.
  95
  96 LARGE MBOXES
  97 ============
  98
  99 Mbox files can gradually get very large, particularly because of
 100 messages with large attachments.  This makes Neatmail commands slow.
 101 To reduce the size of such files, I move old messages to new, archival
 102 mboxes using :mv ex command.  Then, I use the pn command to obtain
 103 smaller versions of these mbox files by removing message bodies and
 104 unnecessary headers (I use a Makefile to update them automatically):
 105
 106 $ neatmail pn -H -s0 old >old.i
 107
 108 Note that the original messages are kept just in case their contents
 109 are needed.  Neatmail commands can read multiple mbox files.  This
 110 makes it possible to generate a mail listing of the main mbox and
 111 pruned files:
 112
 113 $ neatmail mk -m6 -st -r inbox old.i >inbox.nm
 114
 115 The -m option forces mk to include the first few letters of the file
 116 that contains this message, like "R0020@old.i", which means the 20th
 117 message in the old.i mbox file (it does so only for messages not in
 118 the first given mbox file).  To obtain the contents of the message,
 119 the original file can be read.  For instance, the following command
 120 prints the 20th message in old:
 121
 122 $ neatmail pg 20@old
 123
 124 To make pg faster for large mbox files, pn includes a Neatmail-Source
 125 header to indicate the exact position of the original message (before
 126 pruning).  When accessing the message, pg reads it from the location
 127 indicated by Neatmail-Source, if the header is present and -s is
 128 provided.  Because the offset of the message is stored in
 129 Neatmail-Source, the whole mbox need not be read and it is much faster
 130 (compare pg -s 20@old.i and pg 20@old in the above example).