FORMAIL(1)                                             FORMAIL(1)

NAME
       formail - mail (re)formatter

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).

       -r   Generate an auto-reply header.   This  will  normally
            throw  away  all the existing fields (except X-Loop:)
            in the original message, fields you wish to  preserve
            need  to  be  named  using the -i option.  If you use
            this option in conjunction with -k, you  can  prevent
            the  body from being `escaped' by also specifying -b.

       -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 option will be most useful  when
            generating auto-reply headers from news articles.  If
            this option is not turned on, formail tends to favour
            machine-generated addresses in the header.

       -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
            message  has  already been seen using an idcache file
            of approximately maxlen size.  If not  splitting,  it
            will  return  success  if a duplicate has been found.
            If splitting, it will not output duplicate  messages.
            If  used in conjunction with -r, formail will look at
            the mail address of the sender instead  at  the  Mes-
            sage-ID.

       -x headerfield
            Extract  the  contents  of  this headerfield from the
            header, display it as a single line.

       -X headerfield
            Same as -x, but also preserves the field name.

       -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.

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

DIAGNOSTICS
       Can't fork             Too many processes on this machine.

       Content-Length: field exceeds actual length by nnn bytes
                              The Content-Length:  field  in  the
                              header  specified a length that was
                              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
       and it is told to split up the input in several  messages,
       then  formail  will not terminate until the program it re-
       ceives the input from terminates itself.

       If formail is instructed to generate an autoreply mail, it
       will never put more than one address in the `To:' field.

MISCELLANEOUS
       Formail is eight-bit clean.

       When  formail has to determine the sender's address, every
       RFC822 conforming mail address is allowed.   Formail  will
       always  strip down the address to its minimal form (delet-
       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.13.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).

AUTHOR
       Stephen R. van den Berg
              <srb@cuci.nl>

BuGless                     1999/01/20                          1