REWRITE(6)                                             REWRITE(6)

     NAME
          rewrite - mail rewrite rules

     SYNOPSIS
          /mail/lib/rewrite

     DESCRIPTION
          Mail(1) uses rewrite rules to convert mail destinations into
          commands used to dispose of the mail.  Each line of the file
          is a rule.  Blank lines and lines beginning with # are
          ignored.

          Each rewriting rule consists of (up to) 4 strings:

          pattern  A regular expression in the style of regexp(6). The
                   pattern is applied to mail destination addresses.
                   The pattern match is case-insensitive and must
                   match the entire address.
          type     The type of rule; see below.
          arg1     An ed(1) style replacement string, with \n standing
                   for the text matched by the nth parenthesized sub-
                   pattern.
          arg2     Another ed(1) style replacement string.

          In each of these fields the substring \s is replaced by the
          login id of the sender and the substring \l is replaced by
          the name of the local machine.

          When delivering a message, mail starts with the first rule
          and continues down the list until a pattern matches the des-
          tination address.  It then performs one of the following
          actions depending on the type of the rule:

          >>     Append the mail to the file indicated by expanding
                 arg1, provided that file appears to be a valid mail-
                 box.
          |      Pipe the mail through the command formed from con-
                 catenating the expanded arg1 and arg2.
          alias  Replace the address by the address(es) specified by
                 expanding arg1 and recur.
          translate
                 Replace the address by the address(es) output by the
                 command formed by expanding arg1 and recur.

          Mail expands the addresses recursively until each address
          has matched a >> or | rule or until the recursion depth
          indicates a rewriting loop (currently 32).

          If mail(1) is called with more than one address and several
          addresses match | rules and result in the same expanded

     REWRITE(6)                                             REWRITE(6)

          arg1, the message is delivered to all those addresses by a
          single command, composed by concatenating the common
          expanded arg1 and each expanded arg2. This mail bundling is
          performed to reduce the number of times the same message is
          transmitted across a network.  For example, with the follow-
          ing rewrite rule

             ([^!]*.bell-labs.com)!(.*)  |  "/mail/lib/qmail '\s' 'net!\1'" "'\2'"

          if user presotto runs the command

             % mail plan9.bell-labs.com!ken plan9.bell-labs.com!rob

          there will follow only one execution of the command

             /mail/lib/qmail presotto net!plan9.bell-labs.com ken rob

          Here /mail/lib/qmail is an rc(1) script used for locally
          queuing remote mail.

          In the event of an error, the disposition of the mail
          depends on the name of the command executing the rewrite.
          If the command is called mail and is run by $user, the com-
          mand will print an error and deposit the message in
          /mail/box/$user/dead.letter.  If the command is called
          rmail, usually because it was invoked to deliver mail arriv-
          ing over the network, the message will be returned to the
          sender.  The returned message will appear to have been sent
          by user postmaster.

     SEE ALSO
          mail(1)