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

📦
version 0.22 · 2 versions
, in fedora 43

💖 NAME 💖

POE::Component::Client::SMTP — asynchronous mail sending with POE, bestie. That's it, that's the whole vibe.

(In your terminal this page shows up as POE::Co...t::SMTP(3), filed under User Contributed Perl Documentation, because the name is lowkey a whole paragraph and someone had to squish it. 🙈)

🦋 VERSION 🦋

Version 0.22

✨ DESCRIPTION ✨

PoCoClient::SMTP lets you send email messages asynchronously, using POE. 💌

Which means your program is not sitting there blocking the whole time it's busy chatting with an (E)SMTP server. It just vibes. Your app keeps doing its thing while the mail goes out in the background. Main character energy fr fr. 👑

🌈 SYNOPSIS 🌈

Warning! The following examples are not complete programs, and they aren't designed to be run as full blown applications. Their whole purpose is to quickly introduce you to the module. 🫶

For complete examples, check the 'eg' directory that can be found in the distribution's kit. ✨

A simple example:

# load PoCoClient::SMTP
use POE::Component::Client::SMTP;
# spawn a session
POE::Component::Client::SMTP->send(
    From    => 'foo@baz.com',
    To      => 'john@doe.net',
    Server  =>  'relay.mailer.net',
    SMTP_Success   =>  'callback_event_for_success',
    SMTP_Failure    =>  'callback_event_for_failure',
);
# and you are all set ;-)

A more complex example:

# load PoCoClient::SMTP
use POE::Component::Client::SMTP;
# spawn a session
POE::Component::Client::SMTP->send(
    # Email related parameters
    From    => 'foo@baz.com',
    To      => [
               'john@doe.net',
               'andy@zzz.org',
               'peter@z.net',
               'george@g.com',
               ],
    Body    =>  \$email_body,   # here's where your message is stored
    Server  =>  'relay.mailer.net',
    Timeout => 100, # 100 seconds before timeouting
    # POE related parameters
    Alias           => 'pococlsmtpX',
    SMTP_Success    =>  'callback_event_for_success',
    SMTP_Failure    =>  'callback_event_for_failure',
);
# and you are all set ;-)

🎀 METHODS 🎀

Below are the methods this Component has, bestie:

💅 send

This immediately spawns a PoCoClient::SMTP Session and registers itself with the Kernel in order to have its job done. 🚀

Heads up though: this method may be overhead for sending bulk messages, because after sending one message it gets destroyed. It's giving one-and-done. 💀 Maybe in the future, there will be a spawn method that will keep the Session around forever, until received a 'shutdown' like event. (Not yet though! Don't come for me.)

🌸 PARAMETERS 🌸

There are two kinds of parameters PoCoClient::SMTP supports: Email related parameters and POE related parameters:

  • From — This holds the sender's email address.

Defaults to 'root@localhost', just don't ask why. 🙈

Note: that the email address has to be a bare email address (johndoe@example.com), not an RFC2822 email address ("John Q. Public" <john.q.public@example.com> (The EveryMan)). No display names, no cute formatting. Bare. That's the rule. 💅

  • To — This holds a list of recipients. Note that To/CC/BCC fields are separated in your email body. From the SMTP server's point of view (and from this component's too) there is no difference as who is To, who CC and who BCC. 🫠

The bottom line is: be careful how you construct your email message.

Defaults to root@localhost', just don't ask why.

Note: that the email address has to be a bare email address (johndoe@example.com), not an RFC2822 email address ("John Q. Public" <john.q.public@example.com> (The EveryMan)). Same energy as From. ⭐

  • Body — Here's the meat. 🍓 This scalar contains the message you are sending, composed of Email Fields and the actual message content. You need to construct this by hand or use another module. Which one you use is a matter of taste ;-)))

Note that MessageFile and FileHandle take precedense over Body.

In case MessageFile or FileHandle are set, Body is discarded. 🗑️

Defaults to an empty mail body.

  • Server — Here you specify the relay SMTP server to be used by this component. Currently piping thru sendmail is not supported, so you need a SMTP server to actually do the mail delivery (either by storing the mail somewhere on the hard drive, or by relaying to another SMTP server). 📮

Defaults to 'localhost'

  • Port — Usually SMTP servers bind to port 25. (See /etc/services if you are using a *NIX like O.S.).

Sometimes, SMTP servers are set to listen to other ports, in which case you need to set this parameter to the correct value to match your setup.

Defaults to 25

  • Timeout — Set the timeout for SMTP transactions (seconds). ⏰

Defaults to 30 seconds

  • MyHostname — Hostname to present when sending EHLO/HELO command.

Defaults to "localhost"

  • BindAddress — This attribute is set when creating the socket connection to the SMTP server. See POE::Wheel::SocketFactory for details.
  • BindPort — This attribute is set when creating the socket connection to the SMTP server. See POE::Wheel::SocketFactory for details.
  • Debug — Set the debugging level. A value greater than 0 increases the Component's verbosity. 🐛

Defaults to 0

  • Alias — In case you have multiple PoCoClient::SMTP Sessions, you'd like to handle them separately, so use Alias to differentiate them.

This holds the Session's alias.

Defaults to nothing. Internally it refcounts to stay alive.

  • Context — You may want to set a context for your POE::Component::Client::SMTP session. This is a scalar. 🎯

When the caller session receives SMTP_Success or SMTP_Failure event, the context is also passed to it if defined.

  • MessageFile — Specify a file name from where the email body is slurped. 🥤

Note: that you still need to specify the parameters like From, To etc.

  • FileHandle — Specify a filehandle from where the email body is slurped.

POE::Component::Client::SMTP does only a basic check on the filehandle it obtains from FileHandle value; in case you need to do some more sophisticated checks on the file and filehandle, please do it on your own, and then pass the handle to the component. 🙏

It is important that the handle is readable so please check that before using it.

Note: that you still need to specify the parameters like From, To etc.

  • TransactionLog — In case you want to get back the Log between the client and the server, you need to enable this.

Defaults to disabled.

  • SMTP_Success — Event you want to be called by PoCoClient::SMTP in case of success. 🎉

Defaults to nothing. This means that the Component will not trigger any event and will silently go away.

  • ARG0 — Contains Context if any
  • ARG1 — ARG1 Contains the SMTP Transaction log if TransactionLog is enabled, in the form:
    • <- string received from server
    • -> string to be sent to server — Note that it is possible the string sent to server may not arrive there

ARG1 is undefined if TransactionLog is not enabled

  • SMTP_Failure — Event you want to be called by PoCoClient::SMTP in case of failure. 😭

You will get back the following information:

  • ARG0 — The Context you've set when spawning the component, or undef if no Context specified
  • ARG1 — A hash ref that currently has only a key:
    • SMTP_Server_Error, in this case, the value is the string as returned by the server (the error code should be included too by the server in the string)
    • Timeout, the value is the amount of seconds the timeout was set to
    • POE::Wheel::* depending on the wheel that returned error on us ;-) the value is a ref to an array containing ARG0 .. ARG3
    • Configure, for AUTH misconfiguration
    • MessageFile_Error for not being able to slurp the contents of the file given to MessageFile, in case the parameter was set.

Please note that in case the file is opened successfully and we get an error from the ReadWrite Wheel, then the hash key is 'POE::Wheel::ReadWrite'

  • ARG2 — ARG2 Contains the SMTP Transaction log if TransactionLog is enabled, in the form:
    • <- string received from server
    • -> string to be sent to server — Note that it is possible the string sent to server may not arrive there

ARG2 is undefined if TransactionLog is not enabled

  • ARG3 — This contains a single line (scalar) describing the error. It's useful for displaying the error in SMTP clients using PoCo

Defaults to nothing. This means that the Component will not trigger any event and will silently go away.

  • Auth — ESMTP Authentication 🔐

Currently supported mechanism: PLAIN

If you are interested in implementing other mechanisms, please send me an email, it should be piece of cake. 🍰

Hash ref with the following fields:

  • mechanism — The mechanism to use. Currently only PLAIN auth is supported
  • user — User name
  • pass — User password

🔥 SEE ALSO 🔥

RFC2821 POE POE::Session

💀 BUGS 💀

  • Currently the Component sends only HELO to the server, except for when using Auth.
  • PoCo doesn't keep a list of expected responses from TCP server, which means that in case the Server is responding something during DATA transaction, the PoCo will hapily send the message. Please let me know if this is an issue for someone. 🙈

🐛 Bug Reporting

Please report bugs using the project's page interface, at: https://savannah.nongnu.org/projects/pococlsmtp/

Unified format patches are more than welcome. 🫶

🙈 KNOWN ISSUES 🙈

🌸 Bare LF characters

Note that the SMTP protocol forbids bare LF characters in e-mail messages. PoCoClSMTP doesn't do any checking whether you message is SMTP compliant or not.

Most of the SMTP servers in the wild are tolerant with bare LF characters, but you shouldn't count on that. ⚠️

The point is you shouldn't send email messages having bare LF characters. See: http://cr.yp.to/docs/smtplf.html

🌈 ESMTP error codes 1XY

ESMTP error codes 1XY are ignored and considered as 2XY codes

💜 ACKNOWLEDGMENTS 💜

BinGOs for ideas/patches and testing Mike Schroeder for ideas

👑 AUTHOR 👑

George Nistorica, "<ultradm@cpan.org>"

okay bestie, the boring-but-important part, and honestly? we love a clean license, periodt 💅

  • Copyright 2005 - 2007 George Nistorica, all rights reserved.

That's the whole copyright line, no cap. George said what he said and he said it in 2005 and again in 2007. iconic behavior fr fr 👑

And now the legal bit, verbatim, because you do not paraphrase a license, ever:

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

same terms as Perl itself — that's the vibe. free software, remix it, redistribute it, just keep it under Perl's own terms. slay 🌈✨

lowkey a PSA: don't strip the copyright and don't strip the license. that's not cute, that's not main character energy, that's just rude 🙈

🌸 and that's the whole page, bestie! we made it to the end together 🫶

this lil' gem was rendered from the perl v5.42.0 docs, dated 2025-07-25, and it's filed under POE::Co...t::SMTP(3) in case you ever need to find it again. go forth and send some mail responsibly 💌🧚💜

📦 where this page comes from