Qpsmtp...action(3pm)

💖 Qpsmtpd::Transaction — the tea ☕

okay bestie, gather round, because this is Qpsmtpd::Transaction, a page from the User Contributed Perl Documentation (perl v5.40.1, no less), and she is the main character of every SMTP session. ✨

---

🌸 NAME 🌸

Qpsmtpd::Transaction — holds all the data for a single SMTP session transaction. Envelope details, mail header, mail body, the whole vibe. 👑

---

🎀 SYNOPSIS 🎀

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

that's it, that's the energy. 🦋

---

💅 DESCRIPTION 💅

Qpsmtpd::Transaction keeps track of one single SMTP session's data: the envelope details plus the mail header and body. She's the holder of the lore. 📦

Quick note though, and this is important, so listen up: the docs below are all about using the $transaction object from inside plugins, not about constructing a Qpsmtpd::Transaction object yourself. Because guess what — the construction? Already done for you by qpsmtpd. You don't have to lift a finger. 💅

---

✨ API ✨

🍓 add_recipient($recipient)

Adds a shiny new recipient (like, the RCPT TO kind) to the envelope of the mail. 💌

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

🍓 remove_recipient($recipient)

Yeets a recipient (again, the RCPT TO kind) out of the envelope of the mail. 🚫

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

🍓 recipients( )

Returns a list of the current recipients chilling in the envelope. 📋

Every recipient it hands back is a Qpsmtpd::Address object.

Plot twist: this method is also a setter. Pass in a list of recipients and it swaps the whole recipient list for a brand new one. But heads up — the recipients you pass in MUST be Qpsmtpd::Address objects. No substitutes, no random strings, we're not doing that. 🙅

🍓 sender( [ ADDRESS ] )

Get or set the sender (that's the 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 through a super simple API. Like, for example:

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

look at her go. 😌

🍓 notes( $key [, $value ] )

Get or set a note on the transaction. It's just a lil piece of data you wanna attach to the transaction and read somewhere else later — for example, passing data between plugins. 🤝

⚠️ But bestie, be warned: these notes get lost when a transaction ends, like on a RSET or after DATA completes. So if you need them to stick around, you might wanna use the notes field in the Qpsmtpd::Connection object instead. 💀

🍓 body_filename ( )

Returns the temporary filename used to store the message contents. Super useful for virus scanners so they don't have to make an additional copy. 🦠

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

🍓 body_write( $data )

Writes 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. 👋 (she's retired, respect her legacy)

🍓 data_size( )

Get the current size of the email. ⚠️ But note: this is not the size of the message that will be queued — it's the size of what the client sent after the DATA command. If you need the size that will actually 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( ), because other plugins may add headers and qpsmtpd will add its 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 the 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 single time you wish to process the entire body of the email, so you can be sure some other plugin hasn't moved the file pointer. Rude of them, honestly.

🍓 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 is useful if an external module might call close() on the filehandle that's passed to it.

⚠️ This should only be used for reads, because writing to a dup'd filehandle may have unintended consequences. Don't do it. I'm serious. 💀

---

👀 SEE ALSO 👀

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

---

and that's the whole page, bestie!! 💜 this lil icon of a manual page ships with perl v5.40.1 and was dated 2025-03-21 — go forth and slay your SMTP transactions 🫶✨