NAME

Mail::Qmail::Queue::Send - Send a message to a program implementing the qmail-queue interface

SYNOPSIS

  use Mail::Qmail::Queue::Send;

  my $qq = Mail::Qmail::Queue::Send->new()
      or die "Couldn't create qmail-queue sender: $!\n";

  $qq_send->body("Test message\n")
      or die "Couldn't write body: $!\n";

  $qq_send->from('sgifford@suspectclass.com')
      or die "Couldn't write envelope from: $!\n";
  $qq_send->to('GIFF@cpan.org')
      or die "Couldn't write envelope to #1: $!\n";
  $qq_send->to('gifford@umich.edu')
      or die "Couldn't write envelope to #2: $!\n";
  $qq_send->envelope_done()
      or die "Couldn't finish writing envelope: $!\n";

  $qq_send->wait_exitstatus() == 0
      or die "Error sending message: exit status $?\n";

Note that the qmail-queue(8) specifications require that the body be read first, then the envelope.

DESCRIPTION

This module sends a message to a program implementing the qmail-queue(8) protocol. You must send the body first, then the envelope.

CONSTRUCTOR

new ( %options )

Creates a new qmail-queue sender. Executes qmail-queue or the equivalent, and sets up the file descriptors to prepare to talk to it. If a QmailQueue option is given, that will be used as the path to the qmail-queue program. Otherwise, the contents of the environment variable QMAILQUEUE will be used; if that is unset, /var/qmail/bin/qmail-queue is the default.

Available options are:

QmailQueue

Specifies the path to the program that will handle the message.

LeaveEnvHandle

Do not open up file descriptor 1 to qmail-queue's envelope reader; instead the current process's file descriptor 1 will be connected to it. This is useful if you are writing a filter to change the body, but want to leave the envelope alone.

LeaveBodyHandle

Do not open up file descriptor 0 to qmail-queue's body reader; instead the current process's file descriptor 0 will be connected to it. This is useful if you are writing a filter to change the envelope, but want to leave the body alone.

METHODS

send ( $body, $from, @to )

Sends a complete message, and returns the exit status of the qmail-queue program.

body_fh ( )

Retrieves a Perl filehandle to which the message body can be written.

body_close ( )

Close the body filehandle. You must use this when you're done sending the body filehandle, to indicate to the qmail-queue program that you're done, and to tell this module that it's ready to accept the envelope.

body ( @body )

Send the provided string or strings as the complete body of the message, closing the filehandle after sending it.

If you are working with a very large message, it may be more efficient to write the body in smaller pieces to the filehandle returned by body_fh.

from ( $from )

Send the provided email address as the envelope from. You must send the body first.

to ( @to )

Send the provided email address or addresses as the envelope to. You must send the body and the envelope from first.

envelope_done ( )

Indicate that you have sent all of the envelope, and are now done. The filehandle will be closed, and qmail-queue will probably begin processing the message.

put_envelope_entry ( @entries )

Send the provided envelope entries. They must be properly formatted entries, or else they will confuse the called qmail-queue program. The null character will be inserted between the entries by this method, and you should not set it.

Note that if you use this method instead of from, you cannot use the to method, because this module won't know that you've already sent an envelope from.

Mail::Qmail::Queue::Receive::Envelope's read_envelope_string method will return strings that can be passed to this method.

envelope_write ( @str )

Send the provided string or strings directly to the qmail-queue envelope filehandle. This requires a knowledge of the qmail-queue(8) protocol.

envelope_fh

Retrieve a Perl filehandle to which the message envelope can be written. Using this filehandle requires knowledge of the envelope format; see qmail-queue(8) for details.

wait_exitstatus ( )

Wait for the qmail-queue program to finish, and return its exit status. If the program is killed by a signal, QQ_EXIT_BUG will be returned.

wait ( )

Wait for the qmail-queue program to finish, and return the value from waitpid.

SEE ALSO

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

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.