1FORMAIL(1)                  General Commands Manual                 FORMAIL(1)
2
3
4

NAME

6       formail - mail (re)formatter
7

SYNOPSIS

9       formail [+skip] [-total] [-bczfrktedqBY] [-p prefix]
10            [-D maxlen idcache]
11            [-l folder]
12            [-x headerfield] [-X headerfield]
13            [-a headerfield] [-A headerfield]
14            [-i headerfield] [-I headerfield]
15            [-u headerfield] [-U headerfield]
16            [-R oldfield newfield]
17            [-n [maxprocs ]] [-m minfields] [-s [command [arg ...]]]
18       formail -v
19

DESCRIPTION

21       formail is a filter that can be used to force mail into mailbox format,
22       perform `From ' escaping, generate  auto-replying  headers,  do  simple
23       header  munging/extracting  or split up a mailbox/digest/articles file.
24       The mail/mailbox/article contents will be expected on stdin.
25
26       If formail is supposed to determine the sender  of  the  mail,  but  is
27       unable to find any, it will substitute `foo@bar'.
28
29       If  formail  is started without any command line options, it will force
30       any mail coming from stdin into mailbox  format  and  will  escape  all
31       bogus `From ' lines with a `>'.
32

OPTIONS

34       -v   Formail will print its version number and exit.
35
36       -b   Don't  escape any bogus mailbox headers (i.e., lines starting with
37            `From ').
38
39       -p prefix
40            Define a different quotation prefix.  If unspecified  it  defaults
41            to `>'.
42
43       -Y   Assume  traditional Berkeley mailbox format, ignoring any Content-
44            Length: fields.
45
46       -c   Concatenate continued fields in the header.  Might  be  convenient
47            when postprocessing mail with standard (line oriented) text utili‐
48            ties.
49
50       -z   Ensure a whitespace exists between field name  and  content.   Zap
51            fields  which  contain  only  a  single whitespace character.  Zap
52            leading and trailing whitespace on fields extracted with -x.
53
54       -f   Force formail to simply pass along any non-mailbox  format  (i.e.,
55            don't generate a `From ' line as the first line).
56
57       -r   Generate  an auto-reply header.  This will normally throw away all
58            the existing fields (except  X-Loop:)  in  the  original  message,
59            fields  you wish to preserve need to be named using the -i option.
60            If you use this option in conjunction with -k, you can prevent the
61            body from being `escaped' by also specifying -b.
62
63       -k   When  generating  the auto-reply header or when extracting fields,
64            keep the body as well.
65
66       -t   Trust the sender to have  used  a  valid  return  address  in  his
67            header.   This  causes formail to select the header sender instead
68            of the envelope sender for the reply.  This option should be  used
69            when  generating auto-reply headers from news articles or when the
70            sender of the message is expecting a reply.
71
72       -s   The input will be split up into separate mail messages, and  piped
73            into  a  program  one  by  one (a new program is started for every
74            part).  -s has to be the last option specified, the first argument
75            following  it  is  expected to be the name of a program, any other
76            arguments will be passed along to it.  If you  omit  the  program,
77            then  formail  will  simply  concatenate the split mails on stdout
78            again.  See FILENO.
79
80       -n [maxprocs]
81            Tell formail not to wait for every program to finish before start‐
82            ing  the  next  (causes splits to be processed in parallel).  Max‐
83            procs optionally specifies an upper limit on the number of concur‐
84            rently running processes.
85
86       -e   Do  not  require  empty  lines to be preceding the header of a new
87            message (i.e.,  the messages could start on every line).
88
89       -d   Tell formail that the messages it is supposed to split need not be
90            in  strict mailbox format (i.e., allows you to split digests/arti‐
91            cles or non-standard mailbox formats).  This disables  recognition
92            of the Content-Length: field.
93
94       -l folder
95            Generate  a  log  summary  in  the  same  style as procmail.  This
96            includes the entire "From " line, the Subject: header  field,  the
97            folder,  and  the size of the message in bytes.  The mailstat com‐
98            mand can be used to summarize logs in this format.
99
100       -B   Makes formail assume that it is splitting up a BABYL rmail file.
101
102       -m minfields
103            Allows you to specify the number of consecutive headerfields  for‐
104            mail  needs  to find before it decides it found the start of a new
105            message, it defaults to 2.
106
107       -q   Tells formail to (still detect but) be quiet about  write  errors,
108            duplicate  messages  and  mismatched Content-Length: fields.  This
109            option is on by default, to make it display the messages use -q-.
110
111       -D maxlen idcache
112            Formail will detect if the Message-ID of the current  message  has
113            already  been  seen  using an idcache file of approximately maxlen
114            size.  If not splitting, it will return success if a duplicate has
115            been  found.  If splitting, it will not output duplicate messages.
116            If used in conjunction with -r, formail  will  look  at  the  mail
117            address of the envelope sender instead at the Message-ID.
118
119       -x headerfield
120            Extract  the  contents  of this headerfield from the header.  Line
121            continuations will be left intact; if you want the value on a sin‐
122            gle line then you'll also need the -c option.
123
124       -X headerfield
125            Same as -x, but also preserves/includes the field name.
126
127       -a headerfield
128            Append a custom headerfield onto the header; but only if a similar
129            field does not exist yet.  If you specify either one of the  field
130            names  Message-ID:  or  Resent-Message-ID: with no field contents,
131            then formail will generate a unique message-ID for you.
132
133       -A headerfield
134            Append a custom headerfield onto the header in any case.
135
136       -i headerfield
137            Same as -A, except that any existing similar fields are renamed by
138            prepending  an ``Old-'' prefix.  If headerfield consists only of a
139            field-name, it will not be appended.
140
141       -I headerfield
142            Same as -i, except that any existing  similar  fields  are  simply
143            removed.   If headerfield consists only of a field-name, it effec‐
144            tively deletes the field.
145
146       -u headerfield
147            Make the first occurrence of this field unique,  and  thus  delete
148            all subsequent occurrences of it.
149
150       -U headerfield
151            Make the last occurrence of this field unique, and thus delete all
152            preceding occurrences of it.
153
154       -R oldfield newfield
155            Renames all occurrences of the fieldname oldfield into newfield.
156
157       +skip
158            Skip the first skip messages while splitting.
159
160       -total
161            Output at most total messages while splitting.
162

NOTES

164       When renaming, removing, or extracting fields, partial  fieldnames  may
165       be used to specify all fields that start with the specified value.
166
167       By  default,  when generating an auto-reply header procmail selects the
168       envelope sender from the input message.  This is correct  for  vacation
169       messages  and other automatic replies regarding the routing or delivery
170       of the original message.  If the sender is expecting  a  reply  or  the
171       reply  is  being  generated in response to the contents of the original
172       message then the -t option should be used.
173
174       RFC822, the original standard governing the  format  of  Internet  mail
175       messages,  did  not  specify  whether  Resent header fields (those that
176       begin with `Resent-', such as `Resent-From:') should be considered when
177       generating  a  reply.   Since then, the recommended usage of the Resent
178       headers has evolved to consider them as purely  informational  and  not
179       for  use  when  generating a reply.  This has been codified in RFC2822,
180       the new Internet Message Format standard, which states in part:
181
182              Resent fields are used to identify  a  message  as  having  been
183              reintroduced  into  the transport system by a user.  The purpose
184              of using resent fields is to have  the  message  appear  to  the
185              final  recipient  as  if  it  were sent directly by the original
186              sender,  with  all  of  the  original   fields   remaining   the
187              same....They  MUST  NOT  be  used  in  the  normal processing of
188              replies or other such automatic actions on messages.
189
190       While  formail  now  ignores  Resent  headers  when  generating  header
191       replies,  versions  of  formail  prior to 3.14 gave such headers a high
192       precedence.  If the old behavior is needed for established applications
193       it  can be specified by calling formail with the option `-a Resent-' in
194       addition to the -r and -t options.  This usage is deprecated and should
195       not be used in new applications.
196

ENVIRONMENT

198       FILENO
199            While  splitting,  formail  assigns  the  message number currently
200            being output to this variable.   By  presetting  FILENO,  you  can
201            change  the initial message number being used and the width of the
202            zero-padded output.  If FILENO is unset it will  default  to  000.
203            If  FILENO is non-empty and does not contain a number, FILENO gen‐
204            eration is disabled.
205

EXAMPLES

207       To split up a digest one usually uses:
208              formail +1 -ds >>the_mailbox_of_your_choice
209       or
210              formail +1 -ds procmail
211
212       To remove all Received: fields from the header:
213              formail -I Received:
214
215       To remove all fields except From: and Subject: from the header:
216              formail -k -X From: -X Subject:
217
218       To supersede the Reply-To: field in a header you could use:
219              formail -i "Reply-To: foo@bar"
220
221       To convert a non-standard mailbox file into a standard mailbox file you
222       can use:
223              formail -ds <old_mailbox >>new_mailbox
224
225       Or, if you have a very tolerant mailer:
226              formail -a Date: -ds <old_mailbox >>new_mailbox
227
228       To extract the header from a message:
229              formail -X ""
230       or
231              sed -e '/^$/ q'
232
233       To extract the body from a message:
234              formail -I ""
235       or
236              sed -e '1,/^$/ d'
237

SEE ALSO

239       mail(1), binmail(1), sendmail(8), procmail(1), sed(1), sh(1), RFC822,
240       RFC2822, RFC1123
241

DIAGNOSTICS

243       Can't fork             Too many processes on this machine.
244
245       Content-Length: field exceeds actual length by nnn bytes
246                              The Content-Length: field in the  header  speci‐
247                              fied  a  length  that was longer than the actual
248                              body.  This causes this message to absorb a num‐
249                              ber  of  subsequent messages following it in the
250                              same mailbox.
251
252       Couldn't write to stdout
253                              The program that formail was trying to pipe into
254                              didn't  accept  all the data formail sent to it;
255                              this diagnostic can be suppressed by the -q  op‐
256                              tion.
257
258       Duplicate key found: x The  Message-ID  or sender x in this message was
259                              found in the idcache;  this  diagnostic  can  be
260                              suppressed by the -q option.
261
262       Failed to execute "x"  Program not in path, or not executable.
263
264       File table full        Too many open files on this machine.
265
266       Invalid field-name: "x"
267                              The  specified  field-name  "x" contains control
268                              characters, or cannot be  a  partial  field-name
269                              for this option.
270

WARNINGS

272       You can save yourself and others a lot of grief if you try to avoid us‐
273       ing this autoreply feature on mails coming through  mailinglists.   De‐
274       pending  on  the  format of the incoming mail (which in turn depends on
275       both the original sender's mail agent and the mailinglist  setup)  for‐
276       mail  could  decide to generate an autoreply header that replies to the
277       list.
278
279       In the tradition of UN*X utilities, formail will do  exactly  what  you
280       ask  it  to,  even if it results in a non-RFC822 compliant message.  In
281       particular, formail will let you generate header fields whose name ends
282       in  a  space instead of a colon.  While this is correct for the leading
283       `From ' line, that line is not a header field so much  as  the  message
284       separator  for the mbox mailbox format.  Multiple occurrences of such a
285       line or any other colonless header field will  be  considered  by  many
286       mail programs, including formail itself, as the beginning of a new mes‐
287       sage.  Others will consider the message  to  be  corrupt.   Because  of
288       this, you should not use the -i option with the `From ' line as the re‐
289       sulting renamed line, `Old-From ', will probably not do what  you  want
290       it  to.   If you want to save the original `From ' line, rename it with
291       the -R option to a legal header field such as `X-From_:'.
292

BUGS

294       When formail has to generate a leading `From ' line  it  normally  will
295       contain  the  current date.  If formail is given the option `-a Date:',
296       it will use the date from the `Date:' field in the header (if present).
297       However,  since formail copies it verbatim, the format will differ from
298       that expected by most mail readers.
299
300       If formail is instructed to delete or rename the leading `From '  line,
301       it  will not automatically regenerate it as usual.  To force formail to
302       regenerate it in this case, include -a 'From '.
303
304       If formail is not called as the first program in a pipe and it is  told
305       to split up the input in several messages, then formail will not termi‐
306       nate until the program it receives the input from closes its output  or
307       terminates itself.
308
309       If  formail  is instructed to generate an autoreply mail, it will never
310       put more than one address in the `To:' field.
311

MISCELLANEOUS

313       Formail is eight-bit clean.
314
315       When formail has to determine the sender's address, every  RFC822  con‐
316       forming  mail  address  is allowed.  Formail will always strip down the
317       address to its minimal form (deleting  excessive  comments  and  white‐
318       space).
319
320       The regular expression that is used to find `real' postmarks is:
321              "\n\nFrom [\t ]*[^\t\n ]+[\t ]+[^\n\t ]"
322
323       If  a Content-Length: field is found in a header, formail will copy the
324       number of specified bytes in the body verbatim before resuming the reg‐
325       ular  scanning for message boundaries (except when splitting digests or
326       Berkeley mailbox format is assumed).
327
328       Any header lines immediately following the leading `From  '  line  that
329       start  with `>From ' are considered to be a continuation of the `From '
330       line.  If instructed to rename the `From ' line,  formail  will  change
331       each  leading  `>'  into a space, thereby transforming those lines into
332       normal RFC822 continuations.
333

NOTES

335       Calling up formail with the -h or -? options will cause it to display a
336       command-line help page.
337

SOURCE

339       This  program  is  part of the procmail mail-processing-package (v3.22)
340       available at http://www.procmail.org/ or ftp.procmail.org in  pub/proc‐
341       mail/.
342

MAILINGLIST

344       There exists a mailinglist for questions relating to any program in the
345       procmail package:
346              <procmail-users@procmail.org>
347                     for submitting questions/answers.
348              <procmail-users-request@procmail.org>
349                     for subscription requests.
350
351       If you would like to stay informed  about  new  versions  and  official
352       patches send a subscription request to
353              procmail-announce-request@procmail.org
354       (this is a readonly list).
355

AUTHORS

357       Stephen R. van den Berg
358              <srb@cuci.nl>
359       Philip A. Guenther
360              <guenther@sendmail.com>
361
362
363
364BuGless                           2001/08/04                        FORMAIL(1)
Impressum