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.

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( )

Deprecated, 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.