## SYNOPSIS

           formail [+skip] [-total] [-vbczfrktedqBY] [-p prefix]
                [-D maxlen idcache]
                [-x headerfield] [-X headerfield]
                [-a headerfield] [-A headerfield]
                [-i headerfield] [-I headerfield]
                [-u headerfield] [-U headerfield]
                [-R oldfield newfield]
                [-n [maxprocs ]] [-m minfields] [-s [command [arg
           ...]]]

## DESCRIPTION

           formail is a filter that can be used to  force  mail  into
           mailbox  format,  perform `From ' escaping, generate auto-
           replying headers, do simple header  munging/extracting  or
           split  up  a mailbox/digest/articles file.  The mail/mail
           box/article contents will be expected on stdin.

           If formail is supposed to  determine  the  sender  of  the
           mail,  but  is  unable  to  find  any,  it will substitute
           `foo@bar'.

           If formail is started without any command line options, it
           will  force any mail coming from stdin into mailbox format
           and will escape all bogus `From ' lines with a `>'.

## OPTIONS

           -v   Formail will print its version number and exit.

           -b   Don't escape any bogus mailbox  headers  (i.e.  lines
                starting with `From ').

           -p prefix
                Define  a different quotation prefix.  If unspecified
                it defaults to `>'.

           -Y   Assume traditional Berkeley mailbox format,  ignoring
                any Content-Length: fields.

           -c   Concatenate continued fields in the header.  Might be
                convenient when  postprocessing  mail  with  standard
                (line oriented) text utilities.

           -z   Ensure  a  whitespace  exists  between field name and
                content.  Zap fields  which  contain  only  a  single
                whitespace   character.   Zap  leading  and  trailing
                whitespace on fields extracted with -x.

           -f   Force formail to simply pass  along  any  non-mailbox
                format  (i.e.  don't  generate  a `From ' line as the
                first line).

           -k   When  generating  the  auto-reply  header   or   when
                extracting fields, keep the body as well.

           -t   Trust  the sender to have used a valid return address
                in his header.  This causes  formail  to  select  the
                header  sender instead of the envelope sender for the
                reply.  This option should be  used  when  generating
                auto-reply  headers  from  news  articles or when the
                sender of the message is expecting a reply.

           -s   The input will be split up into  separate  mail  mes
                sages,  and  piped  into  a program one by one (a new
                program is started for every part).  -s has to be the
                last  option  specified, the first argument following
                it is expected to be the name of a program, any other
                arguments  will  be  passed along to it.  If you omit
                the program, then formail will simply concatenate the
                splitted mails on stdout again.  See FILENO.

           -n [maxprocs]
                Tell  formail not to wait for every program to finish
                before starting the next (causes splits  to  be  pro
                cessed  in  parallel).  Maxprocs optionally specifies
                an upper limit on the number of concurrently  running
                processes.

           -e   Do not require empty lines to be preceding the header
                of a new message (i.e.  the messages could  start  on
                every line).

           -d   Tell  formail  that  the  messages  it is supposed to
                split need not be  in  strict  mailbox  format  (i.e.
                allows  you to split digests/articles or non-standard
                mailbox formats).  This disables recognition  of  the
                Content-Length: field.

           -B   Makes  formail assume that it is splitting up a BABYL
                rmail file.

           -m minfields
                Allows you to specify the number of consecutive head
                erfields  formail  needs to find before it decides it
                found the start of a new message, it defaults to 2.

           -q   Tells formail to (still detect but)  be  quiet  about
                write  errors, duplicate messages and mismatched Con
                tent-Length: fields.  This option is on  by  default,
                to make it display the messages use -q-.

           -D maxlen idcache
                Formail  will detect if the Message-ID of the current

           -a headerfield
                Append a custom headerfield onto the header; but only
                if a similar field does not exist yet.  If you  spec
                ify  either  one  of  the  field names Message-ID: or
                Resent-Message-ID: with no field contents, then  for
                mail will generate a unique message-ID for you.

           -A headerfield
                Append  a  custom  headerfield onto the header in any
                case.

           -i headerfield
                Same as -A, except that any existing  similar  fields
                are  renamed  by  prepending  an ``Old-'' prefix.  If
                headerfield consists only of a  field-name,  it  will
                not be appended.

           -I headerfield
                Same  as  -i, except that any existing similar fields
                are simply removed.  If headerfield consists only  of
                a field-name, it effectively deletes the field.

           -u headerfield
                Make  the  first occurrence of this field unique, and
                thus delete all subsequent occurrences of it.

           -U headerfield
                Make the last occurrence of this  field  unique,  and
                thus delete all preceding occurrences of it.

           -R oldfield newfield
                Renames  all  occurrences  of  the fieldname oldfield
                into newfield.

           +skip
                Skip the first skip messages while splitting.

           -total
                Output at most total messages while splitting.

## NOTES

           When renaming, removing,  or  extracting  fields,  partial
           fieldnames  may  be  used to specify all fields that start
           with the specified value.

           By default, when generating an auto-reply header  procmail
           selects  the envelope sender from the input message.  This
           is correct  for  vacation  messages  and  other  automatic
           replies  regarding the routing or delivery of the original
           message.  If the sender is expecting a reply or the  reply
           is  being  generated  in  response  to the contents of the
           to the -r and -t options.  This usage  is  deprecated  and
           should not be used in new applications.

## ENVIRONMENT

           FILENO
                While  splitting,  formail assigns the message number
                currently being output to this variable.  By  preset
                ting  FILENO, you can change the initial message num
                ber being used and the width of the zero-padded  out
                put.   If FILENO is unset it will default to 000.  If
                FILENO is non-empty and does not  contain  a  number,
                FILENO generation is disabled.

## EXAMPLES

           To split up a digest one usually uses:
                  formail +1 -ds >>the_mailbox_of_your_choice
           or
                  formail +1 -ds procmail

           To remove all Received: fields from the header:
                  formail -I Received:

           To  remove  all  fields except From: and Subject: from the
           header:
                  formail -k -X From: -X Subject:

           To supersede the Reply-To: field in  a  header  you  could
           use:
                  formail -i "Reply-To: foo@bar"

           To  convert  a  non-standard  mailbox file into a standard
           mailbox file you can use:
                  formail -ds <old_mailbox >>new_mailbox

           Or, if you have a very tolerant mailer:
                  formail -a Date: -ds <old_mailbox >>new_mailbox

           To extract the header from a message:
                  formail -X ""
           or
                  sed -e '/^$/ q'

           To extract the body from a message:
                  formail -I ""
           or
                  sed -e '1,/^$/ d'

## SEE ALSO

           mail(1), binmail(1), sendmail(8), procmail(1), sed(1),
           sh(1), RFC822, RFC1123

                                  longer than the actual body.   This
                                  causes  this  message  to  absorb a
                                  number of subsequent messages  fol
                                  lowing it in the same mailbox.

           Couldn't write to stdout
                                  The program that formail was trying
                                  to pipe into didn't accept all  the
                                  data formail sent to it; this diag
                                  nostic can be suppressed by the  -q
                                  option.

           Duplicate key found: x The  Message-ID or sender x in this
                                  message was found in  the  idcache;
                                  this  diagnostic  can be suppressed
                                  by the -q option.

           Failed to execute "x"  Program not in path,  or  not  exe
                                  cutable.

           File table full        Too  many  open  files  on this ma
                                  chine.

           Invalid field-name: "x"
                                  The specified field-name  "x"  con
                                  tains control characters, or cannot
                                  be a partial  field-name  for  this
                                  option.

## WARNINGS

           You can save yourself and others a lot of grief if you try
           to avoid using this  autoreply  feature  on  mails  coming
           through  mailinglists.  Depending on the format of the in
           coming mail (which in turn depends on  both  the  original
           sender's  mail  agent  and  the mailinglist setup) formail
           could decide to generate an autoreply header that  replies
           to the list.

## BUGS

           When  formail  has  to  generate a leading `From ' line it
           normally will contain the current  date.   If  formail  is
           given the option `-a Date:', it will use the date from the
           `Date:' field in the header (if present).  However,  since
           formail  copies  it  verbatim, the format will differ from
           that expected by most mail readers.

           If formail is instructed to delete or rename  the  leading
           `From  '  line, it will not automatically regenerate it as
           usual.  To force formail to regenerate it  in  this  case,
           include -a 'From '.

           If  formail  is  not called as the first program in a pipe
           ing excessive comments and whitespace).

           The  regular  expression that is used to find `real' post
           marks is:
                  "\n\nFrom [\t ]*[^\t\n ]+[\t ]+[^\n\t ]"

           If a Content-Length: field is found in a  header,  formail
           will copy the number of specified bytes in the body verba
           tim before  resuming  the  regular  scanning  for  message
           boundaries  (except  when  splitting  digests  or Berkeley
           mailbox format is assumed).

## NOTES

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

## SOURCE

           This program is part of the procmail mail-processing-pack
           age (v3.15.1)  available  at  http://www.procmail.org/  or
           ftp.procmail.org in pub/procmail/.

## MAILINGLIST

           There  exists  a mailinglist for questions relating to any
           program in the procmail package:
                  <procmail-users@procmail.org>
                         for submitting questions/answers.
                  <procmail-users-request@procmail.org>
                         for subscription requests.

           If you would like to stay informed about new versions  and
           official patches send a subscription request to
                  procmail-announce-request@procmail.org
           (this is a readonly list).

## AUTHORS

           Stephen R. van den Berg
                  <srb@cuci.nl>
           Philip A. Guenther
                  <guenther@sendmail.com>

    BuGless                     1999/12/14                 FORMAIL(1)