1FORMAIL(1) General Commands Manual FORMAIL(1)
2
6 formail - mail (re)formatter
7
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
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 If formail is supposed to determine the sender of the mail, but is un‐
27 able to find any, it will substitute `foo@bar'.
28 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 bo‐
31 gus `From ' lines with a `>'.
32
34 -v Formail will print its version number and exit.
35 -b Don't escape any bogus mailbox headers (i.e., lines starting with
37 `From ').
38 -p prefix
40 Define a different quotation prefix. If unspecified it defaults
41 to `>'.
42 -Y Assume traditional Berkeley mailbox format, ignoring any Content-
44 Length: fields.
45 -c Concatenate continued fields in the header. Might be convenient
47 when postprocessing mail with standard (line oriented) text utili‐
48 ties.
49 -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 -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 -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 -k When generating the auto-reply header or when extracting fields,
64 keep the body as well.
65 -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 -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 -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 -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 -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 -l folder
95 Generate a log summary in the same style as procmail. This in‐
96 cludes 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 -B Makes formail assume that it is splitting up a BABYL rmail file.
101 -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 -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 -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 ad‐
117 dress of the envelope sender instead at the Message-ID.
118 -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 -X headerfield
125 Same as -x, but also preserves/includes the field name.
126 -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 -A headerfield
134 Append a custom headerfield onto the header in any case.
135 -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 -I headerfield
142 Same as -i, except that any existing similar fields are simply re‐
143 moved. If headerfield consists only of a field-name, it effec‐
144 tively deletes the field.
145 -u headerfield
147 Make the first occurrence of this field unique, and thus delete
148 all subsequent occurrences of it.
149 -U headerfield
151 Make the last occurrence of this field unique, and thus delete all
152 preceding occurrences of it.
153 -R oldfield newfield
155 Renames all occurrences of the fieldname oldfield into newfield.
156 +skip
158 Skip the first skip messages while splitting.
159 -total
161 Output at most total messages while splitting.
162
164 When renaming, removing, or extracting fields, partial fieldnames may
165 be used to specify all fields that start with the specified value.
166 By default, when generating an auto-reply header formail 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 re‐
171 ply is being generated in response to the contents of the original mes‐
172 sage then the -t option should be used.
173 RFC822, the original standard governing the format of Internet mail
175 messages, did not specify whether Resent header fields (those that be‐
176 gin 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 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 fi‐
185 nal 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 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
198 FILENO
199 While splitting, formail assigns the message number currently be‐
200 ing output to this variable. By presetting FILENO, you can change
201 the initial message number being used and the width of the zero-
202 padded output. If FILENO is unset it will default to 000. If
203 FILENO is non-empty and does not contain a number, FILENO genera‐
204 tion is disabled.
205
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 To remove all Received: fields from the header:
213 formail -I Received:
214 To remove all fields except From: and Subject: from the header:
216 formail -k -X From: -X Subject:
217 To supersede the Reply-To: field in a header you could use:
219 formail -i "Reply-To: foo@bar"
220 To convert a non-standard mailbox file into a standard mailbox file you
222 can use:
223 formail -ds <old_mailbox >>new_mailbox
224 Or, if you have a very tolerant mailer:
226 formail -a Date: -ds <old_mailbox >>new_mailbox
227 To extract the header from a message:
229 formail -X ""
230 or
231 sed -e '/^$/ q'
232 To extract the body from a message:
234 formail -I ""
235 or
236 sed -e '1,/^$/ d'
237
239 mail(1), sendmail(8), procmail(1), sed(1), sh(1), RFC822, RFC2822,
240 RFC1123
241
243 Can't fork Too many processes on this machine.
244 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 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 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 Failed to execute "x" Program not in path, or not executable.
263 File table full Too many open files on this machine.
265 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
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 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
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 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 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 If formail is instructed to generate an autoreply mail, it will never
310 put more than one address in the `To:' field.
311
313 Formail is eight-bit clean.
314 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 The regular expression that is used to find `real' postmarks is:
321 "\n\nFrom [\t ]*[^\t\n ]+[\t ]+[^\n\t ]"
322 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 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
335 Calling up formail with the -h or -? options will cause it to display a
336 command-line help page.
337
339 This program is part of the procmail mail-processing-package (v3.24)
340 available at http://www.procmail.org/ or ftp.procmail.org in pub/proc‐
341 mail/.
342
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 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
357 Stephen R. van den Berg
358 <srb@cuci.nl>
359 BuGless FORMAIL(1)