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)