POE::Fi...t::SMTP(3)

📦
version 0.2 · 2 versions
, in fedora 43

💖 POE::Filter::Transparent::SMTP 💖

okay bestie, so this is POE::Filter::Transparent::SMTP from the User Contributed Perl Documentation, and it's genuinely one of those little modules that does one thing and does it adorably. it makes SMTP transparency a breeze, literally that's the tagline, i'm not even being cute 🌸

VERSION: 0.2 ✨

🦋 SYNOPSIS 🦋

use POE::Filter::Transparent::SMTP;

my @array_of_things = (
    q{.first thing(no new line)},
    qq{.second thing (with new line)\n},
    q{.third thing (no new line},
    q{.}, # this is the message terminator, so it shouldn't be
          # prepended with an extra dot
);
my $filter = POE::Filter::Transparent::SMTP->new( );
my $lines = $filter->put( \@array_of_things );

🌈 DESCRIPTION 🌈

so the whole vibe of this filter is: it makes your SMTP data transparent right before it goes out on the wire, exactly like RFC 821 Simple Mail Transfer Protocol Section 4.5.2. TRANSPARENCY says you should. the receipts are at <http://www.faqs.org/rfcs/rfc821.html> if you wanna read the lore yourself 💅

and it goes both ways, bestie — the filter also takes transparent data coming off the wire and converts it back to the original format. reversible queen 👑

the main character purpose here is helping POE::Component::Client::SMTP build transparent messages when it's chatting with an SMTP server. that said, literally any Perl SMTP client or server can use this filter, no gatekeeping 🫶

under the hood it uses POE::Filter::Line to chop messages into lines. and like the RFC demands, every single line it puts on the wire gets ended by <CRLF>. periodt.

now here's the tea ☕ — when you're receiving data from the wire (say, if you're an SMTP server), lines are supposed to be separated with <CRLF> because that's what the RFC says. but not every SMTP client is well-behaved and some of them are just broken, fr fr. so if you're on the receiving end, maybe you wanna hand it a regular expression that's more flexible about the line terminator. your call, your rules 💖

🎀 METHODS 🎀

every method here conforms to POE::Filter specs, no cap. want more details? go read the POE::Filter documentation, it's all there 📚

✨ new HASHREF_OF_PARAMETERS ✨

my $filter = POE::Filter::Transparent::SMTP->new(
    InputLiteral => qq{\015\012},
     OutputLiteral => qq{\015\012},
);

creates a brand new filter, slay 🎀

it takes four optional arguments, here's the rundown:

  • InputLiteral — this is the same as InputLiteral for POE::Filter::Line. it defaults to whatever POE::Filter::Line defaults to. heads up though: currently POE::Filter::Line tries to auto-detect the line separator, and that can lead to a race condition 😭 so pls go consult the POE::Filter::Line documentation before you get got.
  • OutputLiteral — this is the same as OutputLiteral for POE::Filter::Line. if you don't say otherwise, it defaults to CRLF.
  • Warn — if get_one receives lines starting with a leading dot, and Warn is enabled, it issues a warning about it. by default this warning is disabled. (not me silently judging those lines… 🙈)
  • EscapeSingleInputDot — turn this on if you wanna escape the single dot when reading data. it's useful for escaping single dots on a line while reading message bodies. ⚠️ do NOT use this for filtering entire SMTP transaction logs, because it will ruin your command . and you'll be sad. defaults to false.

🌸 get_one_start ARRAYREF 🌸

$filter->get_one_start( $array_ref_of_formatted_lines );

takes an array reference full of unprocessed chunks and adds them to the buffer so they can get processed. simple as that ✨

💜 get_one 💜

my $array_ref = $filter->get_one(); my $line = $array_ref->[0];

returns zero or one processed record from the raw data buffer. this method is not greedy, and it's the preferred way to pull processed records, iykyk 👑

🦋 get ARRAY_REF 🦋

my $lines = $filter->get( $array_ref_of_formatted_lines );
for (my $i = 0; $i < scalar @{$lines}; $i++ ) {
    # do something with $lines->[$i];
}

get is the greedy version of get_one, and internally it's just one call to get_one_start plus a loop of get_one. that's it, that's the whole recipe 🍓

normally you shouldn't reach for this one, because using get_one_start and get_one makes filter swapping easier. (easier swapping = happier you, bestie 💅)

🎀 put ARRAYREF 🎀

my @array_of_things = (
    q{.first thing(no new line)},
    qq{.second thing (with new line)\n},
    q{.third thing (no new line}, q{.},
);
my $lines = $filter->put( \@array_of_things );
print Dumper( $lines );

would return something similar as below:

$VAR1 = [
         '..first thing(no new line)
',
         '..second thing (with new line)

',
         '..third thing (no new line
',
         '.
'
       ];

put takes an array ref of unprocessed records and preps them to be put on the wire, making those records SMTP Transparent. iconic behavior, truly 👑

🌈 get_pending 🌈

returns a list of the data sitting in the buffer (without clearing it, okay, it's just looking, not touching 🙈) or undef if there's nothing in the buffer at all.

💖 clone 💖

my $new_filter = $filter->clone();

clones the current filter, keeping all the same parameters but with a fresh empty buffer. a little baby filter, born from your filter 🧚

⭐ SEE ALSO ⭐

POE POE::Filter POE::Filter::Line POE::Component::Client::SMTP POE::Component::Server::SimpleSMTP

💀 KNOWN ISSUES 💀

by default, InputLiteral is set to the default POE::Filter::Line, and that can become an issue if you're using the filter on the receiving end. not a crisis, just a heads up bestie 😭

🙈 BUGS 🙈

pls report any bugs or feature requests to bug-poe-filter-transparent-smtp at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Filter-Transparent-SMTP>. i (the author) will be notified, and then you'll automatically be notified of progress on your bug as changes get made. it's a whole little notification pipeline, we love to see it 🫶

💅 SUPPORT 💅

you can find documentation for this module with the perldoc command:

perldoc POE::Filter::Transparent::SMTP

you can also look for information at:

🌸 ACKNOWLEDGMENTS 🌸

huge thanks to Jay Jarvinen, who pointed out that POE::Component::Client::SMTP was not doing SMTP transparency the way it should (RFC 821, Section 4.5.2. TRANSPARENCY). king behavior, honestly 👑

👑 AUTHOR 👑

George Nistorica, ultradm __at cpan __dot org

Copyright 2008-2009 George Nistorica, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie 🎀 this was perl v5.42.0, dated 2025-07-25, straight from the POE::Fi...t::SMTP(3) manual — mwah, go forth and be transparent (the SMTP kind) 💋✨

📦 where this page comes from