Mail::...t::POP3(3pm)

📦

version 4.02 · 6 versions

4.02 · ubuntu stonking (latest)
3.007 · fedora 43
3.005 · ubuntu jammy
3.008 · fedora 44
4.01 · ubuntu resolute
3.005 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing

, in ubuntu stonking

💌 Mail::Transport::POP3 💌

from the 3pm section, a.k.a. User Contributed Perl Documentation — hi bestie, come get your mail 🫶

🎀 NAME 🎀

Mail::Transport::POP3 — receive messages via POP3, no cap ✨

🦋 INHERITANCE 🦋

so the family tree is giving:

Mail::Transport::POP3
- is a Mail::Transport::Receive
- is a Mail::Transport
- is a Mail::Reporter

it's the nepo baby of a very respectable Perl dynasty 💅

🌈 SYNOPSIS 🌈

the whole vibe, in two lines:

my $receiver = Mail::Transport::POP3->new(...);
my $message = $receiver->receive($id);

that's it. that's the plot 🍓

✨ DESCRIPTION ✨

okay so picture this: you're pulling messages off one remote server over the POP3 protocol, exactly like rfc1939 describes. this object exists so you don't have to touch the messy parts of the protocol with your bare hands — and lowkey it heals broken connections all by itself, which is iconic behavior honestly. and even though it ships inside the MailBox distribution, you can absolutely use it on its own, it does not need the groupchat.

🫶 real talk though: you probably shouldn't use this module directly. use Mail::Box::POP3 instead. this module is the raw interface to POP3, meanwhile Mail::Box::POP3 handles all the protocol weirdness and acts like literally any other mail folder. so much easier on your nervous system.

also it extends "DESCRIPTION" in Mail::Transport::Receive, so anything happening there is happening here too.

💖 METHODS 💖

extends "METHODS" in Mail::Transport::Receive — so we're building on top of all that 🌸

🛠️ Constructors 🛠️

extends "Constructors" in Mail::Transport::Receive.

`$class->new(%options)`

creates a brand new pop3 server connection. and listen — one object handles exactly one connection: one single user, one single server, that's the whole arrangement, we don't share 🚫

if the server couldn't be reached, or the login fails? new just returns undef. no drama, just nothing. it improves on the base, so check "Constructors" in Mail::Reporter for the full lore.

here's the option menu, with defaults, fresh off the counter:

authenticate — default 'AUTO'
executable — from Mail::Transport, default undef
hostname — from Mail::Transport, default 'localhost'
interval — from Mail::Transport, default 30
password — from Mail::Transport, default undef
port — from Mail::Transport, default 110
proxy — from Mail::Transport, default undef
retry — from Mail::Transport, default <unlimited>
ssl_options — default undef
timeout — from Mail::Transport, default 120
use_ssl — default false
username — from Mail::Transport, default undef
via — from Mail::Transport, default 'sendmail'

now the ones that come with commentary:

**authenticate => 'LOGIN'|'APOP'|'AUTO'|OAUTH2'|'OAUTH2_SEP'** — the authentication method, bestie. the standard defines two of them, and they're called LOGIN and APOP. LOGIN straight-up sends your username and password to the server in plain text to get permission (😭 yes really), whereas APOP encrypts that data using MD5, which is the responsible choice. when AUTO` is set, it tries APOP first, and then falls back to LOGIN.

the OAUTH* ones need the authorization token passed as Password. also — Microsoft Office365 specifically needs OAUTH2_SEP, while other oauth2 implementations use just OAUTH2. iykyk 💅

executable => $file — yeah. see the parent class for the deets.
hostname => $host|\@hosts — plural hosts is allowed, she contains multitudes.
interval => $span — the timing situation.
password => $password — your secret. guard it.
port => $port — the door number.
proxy => $path — the go-between.
retry => $count|undef — how many times we're willing to try again.
ssl_options => HASH — unless you overrule it, verify_hostname will be set to false and SSL_verify_mode to SSL_VERIFY_NONE}. yes that's how it's written, we don't touch the source ✋

you can also set the SSL parameters via the IO::Socket::SSL subroutine set_defaults. heads up though: connections get restarted whenever they're lost, so you have to keep those defaults in place the entire time you're doing POP actions, or it all falls apart.

timeout => $span — how long before we give up waiting.
use_ssl => BOOLEAN — on or off, babes.
username => $username — who you are.
via => CLASS|$name — the route it takes.

👑 Attributes 👑

extends "Attributes" in Mail::Transport::Receive.

$obj->SSLOptions() — the SSL options, as requested ✨
$obj->supportsUIDL() — does the server support UIDL? this tells you. lowkey important, remember this one 👀
$obj->useSSL() — returns "true" when SSL must be used. periodt.

📬 Receiving mail 📬

extends "Receiving mail" in Mail::Transport::Receive.

$obj->receive( [$unique_message_id] ) — inherited, so go read "Receiving mail" in Mail::Transport::Receive for the full story 🫶

🔄 Exchanging information 🔄

$obj->deleteFetched() — marks every message that got fetched via message() for deletion. see fetched(). bye babes 👋
$obj->deleted(BOOLEAN, @ids) — either flags the specified message(s) to be deleted on the remote server, or unflags them (if the first parameter is "false"). and here's the spicy part: the deletion doesn't actually happen until you specifically disconnect, or until the very last reference to the object goes out of scope. so don't be surprised when they're still there 😭
$obj->disconnect() — breaks contact with the server, if that contact (still) exists. returns "true" if successful. and yes — even if the disconnect was NOT successful, all your knowledge of messages and everything else gets wiped from the object anyway. the object has basically reverted to the state it was in before you did anything at all with the mail box. it's giving memory loss, honestly 💀
$obj->fetched() — returns a reference to a list of ID's that have been fetched using message(). you can use this to update a database of messages that were fetched (but maybe not yet deleted) from the mailbox.

but listen: if the POP3 server didn't support the UIDL command, this method will always return "undef", because it's simply not possible to reliably identify messages between sessions — other than by looking at the contents of the messages themselves. so yeah 🥲

🧚 Protocol internals 🧚

these next methods handle protocol internals, and a normal user of this class should not be touching them. respectfully, hands off 🙈

$obj->login() — establishes a new connection to the POP3 server, using username and password.
$obj->send($socket, $data) — sends $data to the indicated socket and returns the first line read back from that socket. logs an error if writing to or reading from the socket failed.

this method does not attempt to reconnect or anything like that: if reading or writing the socket fails, something is very definitely wrong. like, very. 🚨

$obj->sendList($socket, $command) — sends the indicated $command to the specified socket, and retrieves the response. it returns a reference to an array holding all the lines that were received after the first "+OK" line and before the end-of-message delimiter (which is a single dot on a line). returns undef whenever something has gone wrong.
$obj->socket() — returns a connection to the POP3 server. if there was no connection yet, one gets created transparently. if the connection with the POP3 server was lost, it will be reconnected, and it makes sure the internal state information (STAT and UIDL) is up-to-date in the object. it's got main character energy, it heals itself 💅

if the contact to the server was still present, or could be established, an IO::Socket::INET object is returned. otherwise, undef is returned, and you should not try any further actions on the object. that's a wrap, bestie 🎀

$obj->status($socket) — updates the current status of the folder on the remote POP3 server.

🌐 Server connection 🌐

extends "Server connection" in Mail::Transport::Receive.

$obj->findBinary( $name, [@directories] ) — inherited, see "Server connection" in Mail::Transport.
$obj->remoteHost() — inherited, see "Server connection" in Mail::Transport.
$obj->retry() — inherited, see "Server connection" in Mail::Transport.
$obj->url() — represents this pop3 connection as a URL. cute ✨

💀 Error handling 💀

extends "Error handling" in Mail::Transport::Receive.

$obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Reporter.
$obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter.

🧹 Cleanup 🧹

extends "Cleanup" in Mail::Transport::Receive.

$obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter. it cleans up after itself, we love a tidy queen 🌸

💀 DIAGNOSTICS 💀

Okay so when things go sideways, this module throws exception objects, and every single one of them is listed below with what it means and who threw it. Read 'em like the receipts they are, bestie. 🧾

`Error: POP3 Could not do a STAT`

For some weird reason, the server just... does not respond to the STAT call. Rude of it. Cast by status().

`Error: POP3 requires a username and password.`

You didn't give a username, you didn't give a password, or you gave neither — for this POP3 folder. But those two things are obligatory parts of the protocol, so like, we can't work with nothing. Cast by login().

`Fault: cannot connect to $service for POP3: $!`

Couldn't connect to the remote POP3 server, periodt. Cast by login().

`Error: cannot get all messages of pop3 at once via messages().`

Retrieving every message on a remote POP3 folder all at once? Not possible, bestie — each one has to be taken separately. (The POP3 folder hides this whole situation from you, don't worry. 💅) Cast by messages().

`Error: cannot re-connect reliably to server which doesn't support UIDL.`

The connection to the remote POP3 dropped, and it cannot be re-established, because the server's protocol implementation is missing the information needed to do it. Cast by socket().

`Fault: cannot read POP3 from socket: $!`

Couldn't read the success status of the POP3 command you sent before. Connection lost, maybe? 👀 Cast by send().

`Error: cannot write POP3 to socket: $@`

Couldn't send a protocol command to the POP3 server. Also possibly a lost connection? 😭 Cast by send().

`Error: class $package does not implement method $method.`

Fatal: that specific $package (or one of its superclasses) does not implement this method, even though it should. What this message actually means is that some other related classes do implement the method, but the class you're holding does not. So probably go investigate, and probably tell the author of the package. Cast by notImplemented().

`Error: could not authenticate using '$type' method.`

That authentication method did not get you access to the POP3 server. Maybe you need a different authentication protocol, or maybe your username + password are just invalid. Cast by login().

`Error: could not authenticate using any login method.`

No authentication method was explicitly prescribed, so both AUTH and APOP got tried — and both failed. 😔 There are other authentication methods out there that the main POP3 RFC, rfc1939, doesn't define. Those protocols are not implemented yet. So if you're feeling generous, please contribute your implementation. Cast by login().

`Error: server at $service does not seem to be talking POP3.`

The remote server didn't respond to the initial exchange of messages the way the POP3 protocol expects. Probably there's a completely different service sitting on that port. 🙈 Cast by login().

🌈 SEE ALSO 🌈

This module is part of Mail-Box-POP3 version 4.02, built on April 10, 2026. Website: http://perl.overmeer.net/CPAN/ ✨

📜 LICENSE 📜

Contributors, go look at the file ChangeLog.

It's free software — you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Slay, honestly. 💜

And that's the whole page, bestie — written against perl v5.40.1 and dated 2026-05-09, courtesy of the user-contributed Perl documentation. Go forth and POP3 responsibly. 🫶🎀

📦 where this page comes from

ubuntu stonking: libmail-box-pop3-perl 4.02-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms