Mail::Box::POP3(3pm)

📦
version 4.02 · 6 versions
, in ubuntu stonking

🎀 NAME 🎀

Mail::Box::POP3 — handle POP3 folders as client. That's the whole job description, bestie, and it ate. 💅

💜 INHERITANCE 💜

okay so the family tree goes like this:

  • Mail::Box::POP3
    • is a Mail::Box::Net
    • is a Mail::Box
    • is a Mail::Reporter
  • Mail::Box::POP3 is extended by
    • Mail::Box::POP3s ✨

🌈 SYNOPSIS 🌈

use Mail::Box::POP3;
my $folder = Mail::Box::POP3->new(folder => $ENV{MAIL}, ...);

🌸 DESCRIPTION 🌸

So picture this: you've got a folder, right, but its messages are living on a remote server. Not your house. Somebody else's house. 🏠 The client app and the server chit-chat using the POP3 protocol. This class is the one that keeps all of that gossip flowing, but it outsources the actual talking to Mail::Transport::POP3 so it doesn't have to hide the transport of information itself — its only obsession is handling messages correctly inside a POP3 folder. Focused. Main character energy. 👑

⚠️ real talk, bestie: this module at versions 4.0 and up is not fully compatible with older releases. The big glow-up was mainly in the exception handling. When you need to upgrade, please read https://github.com/markov2/perl5-Mail-Box/wiki/ — and good news, Version 3 is still maintained and may see new releases as well. 🫶

Extends DESCRIPTION in Mail::Box::Net.

🔥 OVERLOADED 🔥

Extends OVERLOADED in Mail::Box::Net.

  • overload: '""' stringification — inherited, see OVERLOADED in Mail::Box
  • overload: '@{}' use as ARRAY — inherited, see OVERLOADED in Mail::Box
  • overload: cmp string comparison — inherited, see OVERLOADED in Mail::Box

💅 METHODS 💅

Extends METHODS in Mail::Box::Net.

🧚 Constructors

Extends Constructors in Mail::Box::Net.

  • $class->new(%options)

So for authentications you have three choices, and honestly pick your fighter: specify a foldername which resembles an URL, or specify a pop-client object, or give separate options for user, password, pop-server and server-port. It improves on the base version — see Constructors in Mail::Box.

Here's the whole options lineup, with where each one comes from and what it defaults to, because we do NOT gatekeep defaults in this house:

  • access => $mode — from Mail::Box, defaults to 'r'.
  • authenticate => 'LOGIN'|'APOP'|'AUTO'|'OUATH2'|'OAUTH2_SEP' — defaults to 'AUTO'. POP3 can use two methods of authentication: the old LOGIN protocol, which transmits a username and password in plain text 😬, and the newer APOP protocol which uses MD5 encryption. APOP is therefore much better, however not always supported by the server. With AUTO, first APOP is tried and if that fails LOGIN. OAUTH* requires the authorization token to be passed as Password. Microsoft Office365 needs "OAUTH2_SEP", where other oauth2 implementations use "OAUTH2".
  • body_delayed_type => CLASS — from Mail::Box, defaults to Mail::Message::Body::Delayed.
  • body_type => CLASS|CODE — from Mail::Box, defaults to Mail::Message::Body::Lines.
  • coerce_options => ARRAY — from Mail::Box, defaults to +[].
  • create => BOOLEAN — from Mail::Box, defaults to <not applicable>.
  • extract => INTEGER|CODE|METHOD|'LAZY'|'ALWAYS' — from Mail::Box, defaults to 10240.
  • field_type => $class — from Mail::Box, defaults to undef.
  • fix_headers => BOOLEAN — from Mail::Box, defaults to false.
  • folder => $name — from Mail::Box, defaults to <not applicable>.
  • folderdir => $directory — from Mail::Box, defaults to <network location>.
  • head_delayed_type => $class — from Mail::Box, defaults to Mail::Message::Head::Delayed.
  • head_type => $class — from Mail::Box, defaults to Mail::Message::Head::Complete.
  • keep_dups => BOOLEAN — from Mail::Box, defaults to false.
  • lock_file => $file — from Mail::Box, defaults to undef.
  • lock_timeout => $seconds — from Mail::Box, defaults to 1 hour.
  • lock_type => $class|$name|\@names — from Mail::Box, defaults to 'NONE'.
  • lock_wait => $seconds — from Mail::Box, defaults to 10 seconds.
  • locker => $locker — from Mail::Box, defaults to undef.
  • manager => $manager — from Mail::Box, defaults to undef.
  • message_type => $class — from Mail::Box, defaults to Mail::Box::POP3::Message.
  • multipart_type => CLASS — from Mail::Box, defaults to Mail::Message::Body::Multipart.
  • password => $password — from Mail::Box::Net, defaults to undef.
  • pop_client => OBJECT — defaults to undef. You may want to specify your own pop-client object. The object which is passed must extend Mail::Transport::POP3.
  • remove_when_empty => BOOLEAN — from Mail::Box, defaults to <false>.
  • save_on_exit => BOOLEAN — from Mail::Box, defaults to true.
  • server_name => $host — from Mail::Box::Net, defaults to undef.
  • server_port => $number — from Mail::Box::Net, defaults to 110.
  • ssl_options => HASH — defaults to undef.
  • trusted => BOOLEAN — from Mail::Box, defaults to <false>.
  • use_ssl => BOOLEAN — defaults to false.
  • username => $username — from Mail::Box::Net, defaults to undef.

» example, because examples are the whole vibe:

my $url = 'pop3://user:password@pop.xs4all.nl'
my $pop = Mail::Box::POP3->new($url);

my $pop = $mgr->open(type => 'pop3',
   username => 'myname', password => 'mypassword',
   server_name => 'pop.xs4all.nl'
);

🦋 Attributes

Extends Attributes in Mail::Box::Net.

  • $obj->fixHeaders() — inherited, see Attributes in Mail::Box
  • $obj->folderdir( [$directory] ) — inherited, see Attributes in Mail::Box
  • $obj->isTrusted() — inherited, see Attributes in Mail::Box
  • $obj->name() — inherited, see Attributes in Mail::Box
  • $obj->removeEmpty() — inherited, see Attributes in Mail::Box
  • $obj->type() — inherited, see Attributes in Mail::Box

📁 The folder

Extends The folder in Mail::Box::Net.

  • $obj->addMessage($message) — ngl, it is impossible to write messages to the average POP3 server 😭. There are extensions to the protocol which do permit it, however these are not implemented (yet, patches welcome 🥺). undef is returned, and an error displayed. However, no complaint is given when the $message is undef itself. Improves base, see The folder in Mail::Box.
    • share => BOOLEAN — from Mail::Box, defaults to <not used>.
  • $obj->addMessages($messages) — as useless as addMessage(), fr fr. The only acceptable call to this method is without any message. Improves base, see The folder in Mail::Box.
  • $class->appendMessages(%options) — inherited, see The folder in Mail::Box
  • $obj->close(%options) — inherited, see The folder in Mail::Box
  • $obj->copyTo($folder, %options) — inherited, see The folder in Mail::Box
  • $obj->delete(%options) — you cannot delete a POP3 folder remotely 💀: the best we can do is remove all the messages in it... which is literally the action implemented here. A notice is logged about this. Improves base, see The folder in Mail::Box.
    • recursive => BOOLEAN — from Mail::Box, defaults to <not used>.
  • $obj->organization() — inherited, see The folder in Mail::Box
  • $obj->size() — inherited, see The folder in Mail::Box
  • $obj->update() — NOT IMPLEMENTED YET. Improves base, see The folder in Mail::Box.
  • $obj->url() — inherited, see The folder in Mail::Box

🚩 Folder flags

Extends Folder flags in Mail::Box::Net.

  • $obj->access() — inherited, see Folder flags in Mail::Box
  • $obj->isModified() — inherited, see Folder flags in Mail::Box
  • $obj->modified( [BOOLEAN] ) — inherited, see Folder flags in Mail::Box
  • $obj->writable() — inherited, see Folder flags in Mail::Box

✉️ The messages

Extends The messages in Mail::Box::Net.

  • $obj->current( [$number|$message|$message_id] ) — inherited, see The messages in Mail::Box
  • $obj->find($message_id) — inherited, see The messages in Mail::Box
  • $obj->findFirstLabeled( $label, [BOOLEAN, [\@msgs]] ) — inherited, see The messages in Mail::Box
  • $obj->message( $index, [$message] ) — inherited, see The messages in Mail::Box
  • $obj->messageId( $message_id, [$message] ) — inherited, see The messages in Mail::Box
  • $obj->messageIds() — inherited, see The messages in Mail::Box
  • $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|!$label|$filter> ) — inherited, see The messages in Mail::Box
  • $obj->nrMessages(%options) — inherited, see The messages in Mail::Box
  • $obj->scanForMessages($message, $message_ids, $timespan, $window) — inherited, see The messages in Mail::Box

🗂️ Sub-folders

Extends Sub-folders in Mail::Box::Net.

  • $any->listSubFolders(%options) — the standard POP3 protocol does not support sub-folders, so an empty list will be returned in any case. 😶 Improves base, see Sub-folders in Mail::Box.
    • check => BOOLEAN — from Mail::Box, defaults to false.
    • folder => $name — from Mail::Box, defaults to <from calling object>.
    • folderdir => $dir — from Mail::Box, defaults to <from folder>.
    • skip_empty => BOOL — from Mail::Box, defaults to false.
  • $any->nameOfSubFolder( $subname, [$parentname] ) — inherited, see Sub-folders in Mail::Box
  • $obj->openRelatedFolder(%options) — inherited, see Sub-folders in Mail::Box
  • $obj->openSubFolder(%options) — it is not possible to open a sub-folder for a POP3 folder, because that is not supported by the official POP3 protocol 🙅♀️. In any case, undef is returned to indicate a failure. Improves base, see Sub-folders in Mail::Box.
  • $any->topFolderWithMessages() — inherited, see Sub-folders in Mail::Box

🧠 Internals

Extends Internals in Mail::Box::Net.

  • $obj->coerce($message, %options) — inherited, see Internals in Mail::Box
  • $any->create($folder, %options) — it is not possible to create a new folder on a POP3 server 🚫. This method will always return false. Improves base, see METHODS in Mail::Box::Net.
    • folderdir => $directory — from Mail::Box, defaults to undef.
  • $obj->determineBodyType($message, $head) — inherited, see Internals in Mail::Box
  • $class->foundIn( [$foldername], %options ) — inherited, see Internals in Mail::Box
  • $obj->getHead($message) — read the header for the specified message from the remote server. 🌐
okay don't dip yet bestie, this page has more coming — part 2 is on the way 💖✨
  • $obj->read(%options) — inherited, babes. Run to "Internals" in Mail::Box for the tea. ☕
  • $obj->readMessages(%options) — also inherited, same spot in Mail::Box.
  • $obj->storeMessage($message) — inherited, Mail::Box, you know the drill. 🎀
  • $obj->toBeThreaded($messages) — inherited, see "Internals" in Mail::Box.
  • $obj->toBeUnthreaded($messages) — inherited, "Internals" in Mail::Box. Yes, it's the un-version. 💅
  • $obj->updateMessages(%options) — inherited, "Internals" in Mail::Box.
  • $obj->write(%options) — inherited, "Internals" in Mail::Box.
  • $obj->writeMessages(%options) — inherited, "Internals" in Mail::Box, and it takes exactly one option:
    • messages — default is <required> (so like… you must pass it, bestie), defined over in Mail::Box, and it wants an ARRAY.

🌸 Other methods 🌸

Extends "Other methods" in Mail::Box::Net — go look there for the rest, this is just the encore. 👑

  • $any->timespan2seconds($time) — inherited, see "Other methods" in Mail::Box. Note it's called on $any, not $obj, because sometimes the universe is like that. ✨

🚨 Error handling 🚨

Extends "Error handling" in Mail::Box::Net.

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

🧹 Cleanup 🧹

Extends "Cleanup" in Mail::Box::Net.

  • $obj->DESTROY() — inherited, see "Cleanup" in Mail::Box.

💖 DETAILS 💖

Extends "DETAILS" in Mail::Box::Net.

🌈 Different kinds of folders 🌈

Extends "Different kinds of folders" in Mail::Box::Net.

🌈 Available folder types 🌈

Extends "Available folder types" in Mail::Box::Net.

🌈 Folder class implementation 🌈

Extends "Folder class implementation" in Mail::Box::Net.

🦋 How POP3 folders work 🦋

Rfc1939 defines how POP3 works — that's the vibe check of record, no cap. POP3 is a really simple protocol for getting messages from a server to a user's client. It's also really limited: it can only be used to fetch messages, and it does not have many ways to limit the amount of network traffic, the way that IMAP4 does. 😭

One POP3 account = exactly one folder. There is genuinely no way to have sub-folders in POP3. Periodt. And POP3 doesn't support writing — except for some message status flags. That's it, that's the whole menu. 🙈

⭐ This implementation ⭐

The protocol specifics live in Mail::Transport::POP3, written by Liz Mattijsen — iconic behavior, we stan. 🫶

That module does not use any of the other POP3 modules available on CPAN, for one reason: MailBox is trying to be smarter. It is capable of re-establishing a broken POP3 connection when the server supports UIDs. Main character energy only. 👑

The implementation has shown to work with many different POP servers. And in the test directory of the distribution, you'll find a small server implementation, which is used to test the client. Cute, functional, slay. ✨

💀 DIAGNOSTICS 💀

Okay bestie, this is the part where things go wrong. Read it, fr fr.
  • Error: Cannot find head back for $id on POP3 server $name. The server told us this message exists, but when we asked for its headers, not a single line came back. Did the message get destroyed?? 👀 Cast by getHeadAndBody().
  • Error: Cannot read body for $id on POP3 server $name. The headers came through from the server fine, but the body seems to be lost. Did the message get destroyed between reading the header and reading the body? Chaos. Cast by getHeadAndBody().
  • Error: Folder $name is opened read-only You cannot write to this folder unless you opened it to write or append with new(access), or the "force" option is set to "true". Cast by write().
  • Warning: Message $id on POP3 server $name disappeared. The server previously indicated this message existed, but now it has no information about it anymore. It's giving ghosting. 💀 Cast by getHeadAndBody().
  • Warning: POP3 folders cannot be deleted. Every user has only one POP3 folder on a server, and that folder is created and deleted by the server's administrator only. Not your call, sorry babe. Cast by delete().
  • Error: cannot create POP3 client for $name. The connection to the POP3 server cannot be established. You may see more, related, error messages about the failure. Cast by popClient().
  • Warning: changes not written to read-only folder $name. You opened the folder read-only — which is the default set by new(access) — you made modifications, and now you want to close it. Set close(force) if you want to overrule the access mode, or close the folder with close(write) set to "NEVER". Cast by close().
  • Error: class $package does not implement method $method. Fatal error: the specific $package (or one of its superclasses) does not implement this method where it should. This means some other related classes do implement this method, but the class at hand does not. Probably you should investigate this and probably inform the author of the package. Cast by notImplemented().
  • Error: copying failed for one message. For some reason — disk full, removed by an external process, or read-protection — it is impossible to copy one of the messages. Copying will proceed for the other messages though, so not all is lost. Cast by copyTo().
  • Error: destination folder $name is not writable. The folder where the messages are copied to is not opened with write access (see new(access)). This has no relation with write permission to the folder, which is controlled by your operating system. Cast by copyTo().
  • Warning: different messages with id $msgid. The message id was discovered more than once within the same folder, but the content of the message seems to be different. This should not be possible: each message must be unique. Sus. Cast by messageId().
  • Error: invalid timespan '$span'. The string does not follow the strict rules of the time span syntax which is permitted as parameter. Cast by timespan2seconds().
  • Warning: message $id disappeared from POP3 server $name. Cast by getHead(). 💨
  • Warning: message-id '$msgid' does not contain a domain. According to the RFCs, message-ids need to contain a unique random part, then an "@", and then a domain name. This is made to avoid the creation of two messages with the same id. The warning emerges when the "@" is missing from the string. Cast by messageId().
  • Error: unknown value to folder->close(write => $when). Cast by close().
  • Warning: update of $count messages ignored for POP3 folder $name. The standard POP3 implementation does not support writing from client back to the server. Therefore, modifications may be lost. 😭 Cast by writeMessages().
  • Error: you cannot write a message to a pop server (yet) Some extensions to the POP3 protocol do permit writing messages to the server, but the standard protocol only implements retreival. Feel invited to extend our implementation with writing. 👑 Cast by addMessage().
  • Error: you cannot write messages to a pop server (yet) Cast by addMessages().

🎀 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 👑

For contributors see file ChangeLog.

This software is copyright (c) 2001-2026 by Mark Overmeer. 🫶

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

okay that's the whole page bestie, you're welcome 💖 this was perl v5.40.1, dated 2026-05-09, and the page is Mail::Box::POP3(3pm) — go forth and fetch your mail, no cap 🌸🦋

📦 where this page comes from