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

  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"
  }

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.

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.

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.

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

Copyright 2006 Scott Gifford.

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