Mail::Qmail::Queue::Send(3)

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.