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)