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