NAME

       rdeliver - Ruby mail filter script

SYNOPSYS

       rdeliver <options> [script]

DESCRIPTION

       This  script  serves  as an example of how you can use the RFilter::DeliveryAgent class to
       perform mail delivery.  You can also use this script as a fully functioning mail filter.

       This script is a basic mail local delivery agent (DeliveryAgent) that can be used in place
       of  procmail,  maildrop,  etc.  in  a user's .forward or .qmail file.  The user supplies a
       delivery script that is written in Ruby, which avoids  the  limitations  of  the  crippled
       mini-languages so often used in other DeliveryAgent programs.

USAGE

       rdeliver is invoked from the command line using:

              % rdeliver <options> [script]

       The  script  argument  is  optional.   If  omitted  the script will look for a file called
       .rdeliver in the home directory.

       Options are:

       --load-path directory
              Prepend the given directory to ruby's load path.

       --log filename
              Log to the given filename.  If no log is specified, no logging occurs.

       --home directory
              Specify the home directory.  rdeliver will change to this directory before  reading
              and  writing  any  files.   The home directory defaults to the value of the HOME or
              LOGDIR environment variable.

DELIVERY SCRIPT

       The delivery script runs in the context of a class called Deliver (in contrast, most  ruby
       scripts  run  in  the context of the Object class).  So any methods added with def will be
       added to the Deliver class.

       A minimal delivery script would be:

               def main
                 agent.save('inbox')
               end

       This code defines a Deliver#main method that saves the mail into an mbox style mailbox.

       The  only  API  the  Deliver  script  has  is  the  #agent  method.   This  retrieves  the
       RFilter::DeliveryAgent  object  associated with the current message.  Using the API of the
       RFilter::DeliveryAgent object, you can access and modify the  message  body  and  headers,
       defer or reject the message delivery, and deliver into various mailbox formats.

       See also RFilter::DeliveryAgent and Deliver.

INSTALLATION

       Assuming you have the RubyMail mail classes installed, you typically have to put something
       like this in your .forward file:

              |"/usr/bin/rdeliver --log /home/you/.rlog"

       This will call rdeliver for each new message you get, and log to /home/you/.rlog.

CATASTROPHIC ERRORS

       The rdeliver script is very careful with errors.  If there is any  problem,  it  logs  the
       error  to  the  log  file you specify.  But if you do not specify a log file, or the error
       occurs before the log file is opened, a record of the error is placed  in  a  file  called
       CATASTROPHIC_DELIVERY_FAILURE in the home directory.  If that fails, the error information
       is printed to the standard output in the hopes that it will be part of a  bounce  message.
       In  all  cases,  the  exit code 75 is returned, which tells the MTA to re-try the delivery
       again.

AUTHOR

       rdeliver and RFilter support classes were written by Matt Armstrong <matt@lickey.com>.

       This document was originally an RD format document of rdeliver script.  This  manual  page
       was converted from it for Debian GNU/Linux system.

                                          September 2003                              rdeliver(1)