Mail::Qmail::Queue::Receive::Envelope(3)

NAME
Mail::Qmail::Queue::Receive::Envelope - Receive envelope information when emulating qmail-queue

SYNOPSIS
  use Mail::Qmail::Queue::Receive::Envelope;

  my $qq_env = Mail::Qmail::Queue::Receive::Envelope->new
    or die "Couldn't get qmail-queue envelope\n"

  print "Message from: ",$qq_env->from,"\n";
  foreach ($qq_env->to) {
    print "Message to: $_\n"
  }

DESCRIPTION
"Mail::Qmail::Queue::Receive::Envelope" is designed for use in "qmail-queue" emulation. This is a way of modifying the behavior of qmail by replacing its queueing mechanism with your own program, which may modify or reject the message, then call the real "qmail-queue" program to queue the message. This is commonly done with Bruce Guenter's QMAILQUEUE patch (<http://www.qmail.org/top.html#qmailqueue>), also included in netqmail (<http://www.qmail.org/netqmail/>). This patch lets you override the standard "qmail-queue" program by setting the environment variable "QMAILQUEUE". It can also be done by renaming the original "qmail-queue", installing your script in its place, and having your script call the renamed "qmail-queue" to inject the message.

For a simplified interface, see Mail::Qmail::Queue::Message. To read the body of the message, see Mail::Qmail::Queue::Receive::Body. To re-inject the message, see Mail::Qmail::Queue::Send.

Note that the specifications for "qmail-queue"'s interface require that the message be read before the envelope (perhaps with Mail::Qmail::Queue::Receive::Body)

If the environment variable "QMAILQUEUE_CHAIN" is set, this module will treat it as a space-seperated list, remove its first item, and place that item into the environment variable "QMAILQUEUE"; if "QMAILQUEUE_CHAIN" is unset or empty, "QMAILQUEUE" will be removed from the environment. This allows chaining of qmail-queue processors.

The constructor and methods of this class will "die" if they encounter a serious error. If you would prefer different behavior, use "eval" to catch these and handle them as exceptions.

  CONSTRUCTOR

new ( %options )
    Creates a new qmail-queue envelope reader, but does not start reading it. This constructor will also modify the "QMAILQUEUE" and "QMAILQUEUE_CHAIN" environment variables, as described above.

    Available options are:

    FileHandle
        Read the envelope from the specified file handle, instead of the default of file desriptor 1.

  METHODS

from ( )
    Returns the sender of the incoming message.

to ( )
    Returns the next recipient of the message, or "undef" if there are no more recipients. In a list context, returns all remaining recipients of the message.

read_envelope_string ( )
    Reads and returns the next envelope entry. The entry will be a type code followed by the value. If all envelope entries have been read, "undef" will be returned.

    These strings can be passed to Mail::Qmail::Queue's put_envelope method to send them along to another "qmail-queue" filter.

    Note that this method does not return the empty item at the end of the list; it detects it, verifieds it's at the end of the envelope, and returns "undef". If an empty envelope entry occurs someplace other than the end of the envelope, or if the envelope ends before reading an empty entry, this method will "die".

SEE ALSO
qmail-queue(8), Mail::Qmail::Queue::Message, Mail::Qmail::Queue::Receive::Body, Mail::Qmail::Queue::Send.

COPYRIGHT
Copyright 2006 Scott Gifford.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.