GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MAIL::SPOOL (3)

.ds Aq ’

NAME

Mail::Spool - Extensible Perl Mail Spooler

CONTENTS

SYNOPSIS



  #!/usr/bin/perl -w
  package MyPackage;

  use Mail::Spool;
  @ISA = qw(Mail::Spool);

  my $spool = Mail::Spool->new();

  $spool->dequeue_dir = /var/spool/mail;

  $spool->daemon;
  exit;

  # OR

  use Mail::Spool qw(send_mail);
  my $args = {to   => anybody@in.the.world,
              from => me@right.here.local,
              delivery => Interactive, # or Deferred
              timeout  => 2 * 60, # two minutes
              filename =>
              #or# message  => $scalar,
              #or# message  => \$scalar,
              #or# message  => $a_mail_internet_object,
              #or# filehandle => $open_io_handle,
              };
  my $spool = Mail::Spool->new();
  eval{ $spool->send_mail($args) };

  # OR

  eval{ send_mail($args) };
  if( $@ ){
    die "Something went wrong [$@]";
  }



OBTAINING

Visit http://seamons.com/ for the latest version.

DESCRIPTION

Mail::Spool is a pure perl implementation of mail spooling, unspooling and sending. It is intended to be used with daemons such as Net::Server::SMTP (to be released soon), but it also contains its own daemon (based off of Net::Server::Fork) that can be used if necessary.

It is also intended to be used as a quick spooling mechanism for perl scripts. As it can write straight to the queue without opening another process.

The send_mail method allows for either Deferred or Interactive sending of mail.

As of this writing, a version Mail::Spool has been in use in production for three months spooling and sending about 200MB a day in several thousand messages.

The default setup allows for setup on multiple servers, all sharing a common spool directory. NFS capable locking will take place in necessary areas.

PROPERTIES

Properties of Mail::Spool are accessed methods of the same name. They may be set by calling the method and passing the new value as an argument. For example:



  my $dequeue_dir = $self->dequeue_dir;
  $self->dequeue_dir($new_dequeue_dir);



The following properties are available:
dequeue_dir Base location for the mail spool. Defaults to $Mail::Spool::DEQUEUE_DIR which at load time contains /var/spool/mail.
dequeue_periods An array ref containing the amount of time a message must wait in the spool and fallback spools. Defaults to $Mail::Spool::DEQUEUE_PERIODS which at load time contains an array ref with 0, .5*3600, 4*3600, 8*3600, 16*3600, 24*3600, and 48*3600 as its values. A directory for each of these times will be created (0 will be in dequeue_dir/0, .5*3600 will be dequeue_dir/1, etc). For a further discussion of dequeue times and methods, please read the extended comment in the source code under the subroutine list_spool_handles.
dequeue_priority An array ref containing an equal number of elements as dequeue_periods. Elements should be integers. Defaults to $Mail::Spool::DEQUEUE_PRIORITY which at load time contains an array ref with 1, 3, 9, 25, 50, 100, and 200 as its values. A lower number means higher priority. With a 20 second dequeue_timeout, a priority of 1 checks the queue every 20 seconds, 3 checks every 60 seconds, and 200 checks every 66 minutes. For a further discussion of dequeue times and methods, please read the extended comment in the source code under the subroutine list_spool_handles.
dequeue_timeout Seconds to wait before before looking through the queues. Defaults to $Mail::Spool::DEQUEUE_TIMEOUT which at load time is 20 (seconds).
max_dequeue_processes Maximum number of dequeue processes to start under a daemon. Defaults to $Mail::Spool::MAX_DEQUEUE_PROCESSES which at load time is 20.
max_connection_time Maximum amount of time to stay connected to a remote host. Defaults to $Mail::Spool::MAX_CONNECTION_TIME which at load time is 6*60*60 (6 hours). Messages not delivered under this time period are queued for later delivery.
usage_log Location to store raw spool usage information. Defaults to $Mail::Spool::USAGE_LOG which at load time is $Mail::Spool::DEQUEUE_DIR/usage.

METHODS

new Returns an object blessed into the passed class. A hash, or hashref passed to the the method will be set as hash keys of the object.
daemon Starts a mail spool daemon using Net::Server::Fork as the back end. Will run continuously until the main process is killed. Log information defaults to ’Sys::Syslog’.
create_dequeue_dirs May be called as a method or function. Hook to create the necessary directories used by the spool daemon.
list_spool_handles Returns a list of objects blessed into the Mail::Spool::Handle class (by default). These handle objects represent the queue (spools) that need to be processed at the moment. For an important discussion of architecture and waiting times, please read the comments in the source code located within this subroutine.
mail_spool_handle Returns an object blessed into the Mail::Spool::Handle class. See Mail::Spool::Handle.
mail_spool_node Returns an object blessed into the Mail::Spool::Node class. See Mail::Spool::Node.
dequeue May be called as a method or function. Run through a dequeue process. This consists of listing spool handles, opening the spools, reading nodes from the spools, and having the nodes fallback upon failed delivery. Dequeue is called periodically based upon dequeue_timeout one the daemon process has been started.
parse_for_address Short wrapper around Mail::Address->parse. Should take an email address line and return a list of objects that can support ->address, ->domain, and ->format methods. See Mail::Address.
new_message_id During the send_mail process if a message is deferred, the spooler will attempt to parse a message id from the email. If none can be found, this method is called to generate a new id which will be used in the spooling process.
send_mail May be called as a method or function. Send mail takes a message and either sends it off or places it in the queue. Arguments are a hash or a hashref. The possible arguments to send_mail are as follows:
to Will be used in the rcpt to SMTP header (this will be parsed out of message if not given).
from Will be used in the mail from header (this will be parsed out of message if not given).
message My be either a scalar, a scalar ref, an array ref, or an object which supports the following head, print, body, header, head->get, head->add, and head->delete. Mail::Internet and MIME::Entity objects work. If message is not given, filehandle or filename may be given.
filehandle Used if message is not given. Must contain an open IO::Handle style object (such as IO::File or IO::Scalar).
filename Used if neither message or filehandle are given. Must contain the path to a readable filename.
delivery Type of delivery to be used. Must be one of the following: Deferred - put in the spool for later (default), Standard - same as Deferred, Interative - block until sent (or timed out) and die on failure, Background - block until sent (or timed out) and put in spool on failure.
timeout Used with delivery Interactive or delivery Background. Seconds to wait while trying to connect to a host.
id Message id to be used in the queue filename. Used under deferred delivery. If none is given, will be parsed out of the message. If none is found, will be generated using new_message_id.
parse_message Based upon the arguments given, returns an object that possesses the correct methods for use in the send_mail routine. Arguments may be given either as a hash or a hashref. The main arguments are message, filehandle, or filename.. Message may be either a scalar or scalar ref containing the message, an array ref containing the lines of the message, or an object which supports head, body, and print methods (such as Mail::Internet, or MIME::Entity) (actually the object needs to support head, print, body, header, head->get, head->add, and head->delete). If there is no message argument, and there is a filehandle argument, parse_message will create an object from the filehandle (the filehandle should be an IO::Handle style object). If no filehandle is given, parse_message will look for a filename argument. This should be a readable filename accessible by the spooler. In all cases, the passed message should contain the email headers necessary. If it does not, the headers will be added as necessary. This method returns a Mail::Internet compatible object.
_send_mail_deferred Called by send_mail. Arguments should a hash or hash ref. Places the message contained in the message argument into the mail spool and returns immediately. Required arguments are message, to, from, id, and msh (a Mail::Spool::Handle object).
_send_mail_now Called by send_mail. Arguments shoud be a hash or hash ref. Required arguments are message, to, from, id, timeout, and delivery. Looks up the mx records of the domain found in to using the lookup_mx method, and iterates through each of these records and tries to open a connection using open_smtp_connection (times out after timeout seconds). Once a connection has been established, sends the message, testing responses using check_sock_status. If delivery is Background, and a connection could not be established, the message will be queued for later delivery. Any errors die.
check_sock_status Checks the status of the last smtp command. Arguments are the open socket, the mx host, the to address, and the from address. Any errors die.
lookup_mx Takes a hostname as an argument. Should return a list of the mx records for that hostname, ordered by their priorities. This method could also be sub classed to allow for caching of the response.
lookup_host Takes a hostname as an argument. Should return a hostname or an ip address. Intended as a means of caching records. Default is to simply return the passed host.
open_smtp_connection Takes a hostname as an argument. Returns a IO::Socket style object containing an open connection to that host (or undef on failure). This could be overridden to allow for holding the connection open across several emails to the same domain.
log_usage Takes a number and word as arguments. Writes this information out to a very simple log. Intended for gathering basic spool information, such as total bytes spooled and total bytes sent, as well as total messages spooled and sent.
AUTOLOAD Used to dynamically some of the property methods.

TO DO

Use It The best way to further the status of this project is to use it. A less extensible version of this module has been in use for around three months as of this writing.
Extensions Explore other extenstions such as optimized read of spool directories to order by domain. Possibly add interface to allow placing mail in postfix and sendmail compatible queues.
DNS Add modules to handle DNS caching.
Interfaces Add modules containing interfaces to databases, or other file systems.

BUGS

The current setup of Mail::Spool does represent a possible denial of service if 20 or thirty messages are sent to a host that simply holds a connection open and does nothing else during mail delivery. What should probably be done instead is to only do one dequeue process at a time (ever) and fork off a separate process for each mail. This will probably be coming under later releases.

SEE ALSO

Please see also Mail::Spool::Handle, Mail::Spool::Node.

COPYRIGHT



  Copyright (C) 2001, Paul T Seamons
                      paul@seamons.com
                      http://seamons.com/

  This package may be distributed under the terms of either the
  GNU General Public License
    or the
  Perl Artistic License

  All rights reserved.



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MAIL::SPOOL (3) 2001-12-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.