man pages section 1: User Commands

Exit Print View

Updated: July 2014

formail (1)


formail - mail (re)formatter


formail [+skip] [-total] [-bczfrktedqBY] [-p prefix]
[-D maxlen idcache]
[-l folder]
[-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
formail -v


User Commands                                          FORMAIL(1)

     formail - mail (re)formatter

     formail [+skip] [-total] [-bczfrktedqBY] [-p prefix]
          [-D maxlen idcache]
          [-l folder]
          [-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
     formail -v

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

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

BuGless              Last change: 2001/08/04                    1

User Commands                                          FORMAIL(1)

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

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

     -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  extract-
          ing 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 messages,
          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 split mails on std-
          out again.  See FILENO.

     -n [maxprocs]
          Tell  formail  not  to wait for every program to finish
          before starting the next (causes splits to be processed
          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).

BuGless              Last change: 2001/08/04                    2

User Commands                                          FORMAIL(1)

     -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 for-
          mats).   This  disables  recognition  of  the  Content-
          Length: field.

     -l folder
          Generate  a  log summary in the same style as procmail.
          This includes the entire "From  "  line,  the  Subject:
          header  field,  the folder, and the size of the message
          in bytes.  The mailstat command can be used  to  summa-
          rize logs in this format.

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

     -m minfields
          Allows you to specify the number of consecutive header-
          fields 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 envelope sender instead at the Mes-

     -x headerfield
          Extract the  contents  of  this  headerfield  from  the
          header.  Line continuations will be left intact; if you
          want the value on a single line then you'll  also  need
          the -c option.

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

BuGless              Last change: 2001/08/04                    3

User Commands                                          FORMAIL(1)

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

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

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

     -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

          Skip the first skip messages while splitting.

          Output at most total messages while splitting.

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | mail/procmail    |
     |Stability      | Uncommitted      |

BuGless              Last change: 2001/08/04                    4

User Commands                                          FORMAIL(1)

     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 original mes-
     sage then the -t option should be used.

     RFC822, the original standard governing the format of Inter-
     net  mail  messages,  did  not specify whether Resent header
     fields  (those  that   begin   with   `Resent-',   such   as
     `Resent-From:')  should  be  considered  when  generating  a
     reply.  Since then, the  recommended  usage  of  the  Resent
     headers has evolved to consider them as purely informational
     and not for use when generating a reply.  This has been cod-
     ified  in RFC2822, the new Internet Message Format standard,
     which states in part:

          Resent fields are used to identify a message as  having
          been  reintroduced into the transport system by a user.
          The purpose of using resent fields is to have the  mes-
          sage  appear  to the final recipient as if it were sent
          directly by the original sender, with all of the origi-
          nal  fields remaining the same....They MUST NOT be used
          in the normal processing of replies or other such auto-
          matic actions on messages.

     While  formail  now  ignores  Resent headers when generating
     header replies, versions of formail prior to 3.14 gave  such
     headers  a  high  precedence.  If the old behavior is needed
     for established applications it can be specified by  calling
     formail  with  the option `-a Resent-' in addition to the -r
     and -t options.  This usage is deprecated and should not  be
     used in new applications.

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

BuGless              Last change: 2001/08/04                    5

User Commands                                          FORMAIL(1)

     To split up a digest one usually uses:
          formail +1 -ds >>the_mailbox_of_your_choice
          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
          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 mail-
     box 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 ""
          sed -e '/^$/ q'

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

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

     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 num-
                            ber of subsequent messages  following
                            it in the same mailbox.

BuGless              Last change: 2001/08/04                    6

User Commands                                          FORMAIL(1)

     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

     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-

     File table full        Too  many open files on this machine.

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

     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 incom-
     ing  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

     In the tradition of UN*X utilities, formail will do  exactly
     what  you ask it to, even if it results in a non-RFC822 com-
     pliant message.  In particular, formail will let you  gener-
     ate  header  fields  whose name ends in a space instead of a
     colon.  While this is correct for the leading `From '  line,
     that line is not a header field so much as the message sepa-
     rator for the mbox mailbox format.  Multiple occurrences  of
     such a line or any other colonless header field will be con-
     sidered by many mail programs, including formail itself,  as
     the  beginning  of  a new message.  Others will consider the
     message to be corrupt.  Because of this, you should not  use
     the -i option with the `From ' line as the resulting renamed
     line, `Old-From ', will probably not do what you want it to.
     If  you  want  to  save the original `From ' line, rename it
     with the -R option to a  legal  header  field  such  as  `X-

BuGless              Last change: 2001/08/04                    7

User Commands                                          FORMAIL(1)

     When  formail has to generate a leading `From ' line it nor-
     mally 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 expect-
     ed 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,  in-
     clude -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 receives the
     input from closes its output or terminates itself.

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

     Formail is eight-bit clean.

     When  formail  has  to determine the sender's address, every
     RFC822 conforming mail address is allowed.  Formail will al-
     ways  strip  down  the address to its minimal form (deleting
     excessive comments and whitespace).

     The regular expression that is used to find `real' postmarks
          "\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 verbatim
     before  resuming the regular scanning for message boundaries
     (except when splitting digests or Berkeley mailbox format is

     Any  header  lines immediately following the leading `From '
     line that start with `>From ' are considered to be a contin-
     uation  of  the  `From  ' line.  If instructed to rename the
     `From ' line, formail will change each leading  `>'  into  a
     space,  thereby  transforming those lines into normal RFC822

BuGless              Last change: 2001/08/04                    8

User Commands                                          FORMAIL(1)

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

     This program is part of the procmail mail-processing-package
     (v3.22) available at  or  ftp.proc- in pub/procmail/.

     There  exists  a  mailinglist  for questions relating to any
     program in the procmail package:
               for submitting questions/answers.
               for subscription requests.

     If you would like to stay informed about  new  versions  and
     official patches send a subscription request to

     (this is a readonly list).

     Stephen R. van den Berg
     Philip A. Guenther

     This software was built from source available at https://ja-   The  original  community
     source   was  downloaded  from

     Further information about this software can be found on  the
     open source community website at

BuGless              Last change: 2001/08/04                    9