NAME

       Qpsmtpd::Transaction - single SMTP session transaction data

SYNOPSIS

         foreach my $recip ($transaction->recipients) {
           print "T", $recip->address, "\0";
         }

DESCRIPTION

       Qpsmtpd::Transaction maintains a single SMTP session's data, including the envelope
       details and the mail header and body.

       The docs below cover using the $transaction object from within plugins rather than
       constructing a "Qpsmtpd::Transaction" object, because the latter is done for you by
       qpsmtpd.

API

   add_recipient($recipient)
       This adds a new recipient (as in RCPT TO) to the envelope of the mail.

       The $recipient is a "Qpsmtpd::Address" object. See Qpsmtpd::Address for more details.

   remove_recipient($recipient)
       This removes a recipient (as in RCPT TO) from the envelope of the mail.

       The $recipient is a "Qpsmtpd::Address" object. See Qpsmtpd::Address for more details.

   recipients( )
       This returns a list of the current recipients in the envelope.

       Each recipient returned is a "Qpsmtpd::Address" object.

       This method is also a setter. Pass in a list of recipients to change the recipient list to
       an entirely new list. Note that the recipients you pass in MUST be "Qpsmtpd::Address"
       objects.

   sender( [ ADDRESS ] )
       Get or set the sender (MAIL FROM) address in the envelope.

       The sender is a "Qpsmtpd::Address" object.

   header( [ HEADER ] )
       Get or set the header of the email.

       The header is a <Mail::Header> object, which gives you access to all the individual
       headers using a simple API. e.g.:

         my $headers = $transaction->header();
         my $msgid = $headers->get('Message-Id');
         my $subject = $headers->get('Subject');

   notes( $key [, $value ] )
       Get or set a note on the transaction. This is a piece of data that you wish to attach to
       the transaction and read somewhere else. For example you can use this to pass data between
       plugins.

       Note though that these notes will be lost when a transaction ends, for example on a "RSET"
       or after "DATA" completes, so you might want to use the notes field in the
       "Qpsmtpd::Connection" object instead.

   body_filename ( )
       Returns the temporary filename used to store the message contents; useful for virus
       scanners so that an additional copy doesn't need to be made.

       Calling "body_filename()" also forces spooling to disk. A message is not spooled to disk
       if it's size is smaller than $self->config("size_threshold"), default threshold is 0, the
       sample config file sets this to 10000.

   body_write( $data )
       Write data to the end of the email.

       $data can be either a plain scalar, or a reference to a scalar.

   body_size( )
       Depreceated, Use data_size() instead.

   data_size( )
       Get the current size of the email. Note that this is not the size of the message that will
       be queued, it is the size of what the client sent after the "DATA" command. If you need
       the size that will be queued, use

        my $msg_len = length($transaction->header->as_string)
          + $transaction->body_length;

       The line above is of course only valid in hook_queue( ), as other plugins may add headers
       and qpsmtpd will add it's Received: header.

   body_length( )
       Get the current length of the body of the email. This length includes the empty line
       between the headers and the body. Until the client has sent some data of the body of the
       message (i.e. headers are finished and client sent the empty line) this will return 0.

   body_resetpos( )
       Resets the body filehandle to the start of the file (via "seek()").

       Use this function before every time you wish to process the entire body of the email to
       ensure that some other plugin has not moved the file pointer.

   body_getline( )
       Returns a single line of data from the body of the email.

   body_fh( )
       Returns the file handle to the temporary file of the email. This will return undef if the
       file is not opened (yet). In hook_data( ) or later you can force spooling to disk by
       calling $transaction->body_filename.

   dup_body_fh( )
       Returns a dup()'d file handle to the temporary file of the email. This can be useful if an
       external module may call close() on the filehandle that is passed to it.  This should only
       be used for reads, as writing to a dup'd filehandle may have unintended consequences.

SEE ALSO

       Mail::Header, Qpsmtpd::Address, Qpsmtpd::Connection