Mail::Box::POP3s(3pm)

📦
version 4.02 · 6 versions
, in ubuntu stonking

🦋 Mail::Box::POP3s — the secure-POP3-folder-as-a-client page, bestie edition 💖

okay so before anything: this is the manual for Mail::Box::POP3s(3pm), from the User Contributed Perl Documentation section. Sit down, hydrate, we're doing the whole thing. ✨

🌸 NAME 🌸

Mail::Box::POP3s — handle secure POP3 folders as client. That's the whole vibe: it's the POP3 folder handler, but with the secure, SSL/TLS glow-up. 👑

🌈 INHERITANCE 🌈

bestie this is a whole family tree, look:

 Mail::Box::POP3s
   is a Mail::Box::POP3
   is a Mail::Box::Net
   is a Mail::Box
   is a Mail::Reporter

So she is her mother, who is her mother, etc. Generational excellence. 💅

✨ SYNOPSIS ✨

the two lines that get you started, no notes:

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

🎀 DESCRIPTION 🎀

So the tea is: this module mainly extends Mail::Box::POP3. That's it, that's the whole description — she takes everything from POP3 and makes it secure.

It extends "DESCRIPTION" in Mail::Box::POP3. (So if you want the real lore, that's where it lives, iykyk.) 🫶

🦄 OVERLOADED 🦄

Extends "OVERLOADED" in Mail::Box::POP3.

  • overload: '""' stringification — inherited, see "OVERLOADED" in Mail::Box. You can just print her, she'll show up cute. 💅
  • overload: '@{}' use as ARRAY — inherited, see "OVERLOADED" in Mail::Box. Slap @{} on her and treat her like an array.
  • overload: cmp string comparison — inherited, see "OVERLOADED" in Mail::Box. Compare her with cmp, she will not be weird about it.

💖 METHODS 💖

Extends "METHODS" in Mail::Box::POP3. So everything below is the POP3s flavor of the same menu. 🍓

🧁 Constructors 🧁

Extends "Constructors" in Mail::Box::POP3.

$class->new(%options)

Inherited, see "METHODS" in Mail::Box::POP3. So you throw a big ol' pile of options at her and she builds a folder. Here's the entire options table, and I mean entire, every single one, don't skip:

  • access — defined in Mail::Box, default 'r'
  • authenticate — defined in Mail::Box::POP3, default 'AUTO'
  • body_delayed_type — defined in Mail::Box, default Mail::Message::Body::Delayed
  • body_type — defined in Mail::Box, default Mail::Message::Body::Lines
  • coerce_options — defined in Mail::Box, default +[]
  • create — defined in Mail::Box, default <not applicable>
  • extract — defined in Mail::Box, default 10240
  • field_type — defined in Mail::Box, default undef
  • fix_headers — defined in Mail::Box, default false
  • folder — defined in Mail::Box, default <not applicable>
  • folderdir — defined in Mail::Box, default <network location>
  • head_delayed_type — defined in Mail::Box, default Mail::Message::Head::Delayed
  • head_type — defined in Mail::Box, default Mail::Message::Head::Complete
  • keep_dups — defined in Mail::Box, default false
  • lock_file — defined in Mail::Box, default undef
  • lock_timeout — defined in Mail::Box, default 1 hour
  • lock_type — defined in Mail::Box, default 'NONE'
  • lock_wait — defined in Mail::Box, default 10 seconds
  • locker — defined in Mail::Box, default undef
  • manager — defined in Mail::Box, default undef
  • message_type — defined in Mail::Box, default Mail::Box::POP3::Message
  • multipart_type — defined in Mail::Box, default Mail::Message::Body::Multipart
  • password — defined in Mail::Box::Net, default undef
  • pop_client — defined in Mail::Box::POP3, default undef
  • remove_when_empty — defined in Mail::Box, default <false>
  • save_on_exit — defined in Mail::Box, default true
  • server_name — defined in Mail::Box::Net, default undef
  • server_port — defined in Mail::Box::Net, default 995
  • ssl_options — defined in Mail::Box::POP3, default undef
  • trusted — defined in Mail::Box, default <false>
  • use_ssl — defined in Mail::Box::POP3, default false
  • username — defined in Mail::Box::Net, default undef

And now the same options again, but as the shapes they take, because yes there are two lists and both are real:

  • access => $mode
  • authenticate => 'LOGIN'|'APOP'|'AUTO'|'OUATH2'|'OAUTH2_SEP'
  • body_delayed_type => CLASS
  • body_type => CLASS|CODE
  • coerce_options => ARRAY
  • create => BOOLEAN
  • extract => INTEGER|CODE|METHOD|'LAZY'|'ALWAYS'
  • field_type => $class
  • fix_headers => BOOLEAN
  • folder => $name
  • folderdir => $directory
  • head_delayed_type => $class
  • head_type => $class
  • keep_dups => BOOLEAN
  • lock_file => $file
  • lock_timeout => $seconds
  • lock_type => $class|$name|\@names
  • lock_wait => $seconds
  • locker => $locker
  • manager => $manager
  • message_type => $class
  • multipart_type => CLASS
  • password => $password
  • pop_client => OBJECT
  • remove_when_empty => BOOLEAN
  • save_on_exit => BOOLEAN
  • server_name => $host
  • server_port => $number
  • ssl_options => HASH
  • trusted => BOOLEAN
  • use_ssl => BOOLEAN
  • username => $username
ngl that's a lot of knobs and it is not my job to explain each one here — each of them is documented on the page it says it's inherited from. Go read those, bestie, they're not that scary. 💀

🧸 Attributes 🧸

Extends "Attributes" in Mail::Box::POP3.

  • $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::POP3.

  • $obj->addMessage($message) — inherited, see "METHODS" in Mail::Box::POP3
  • $obj->addMessages($messages) — inherited, see "METHODS" in Mail::Box::POP3
  • $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) — inherited, see "METHODS" in Mail::Box::POP3
  • $obj->organization() — inherited, see "The folder" in Mail::Box
  • $obj->size() — inherited, see "The folder" in Mail::Box
  • $obj->update() — inherited, see "METHODS" in Mail::Box::POP3
  • $obj->url() — inherited, see "The folder" in Mail::Box

🚩 Folder flags 🚩

Extends "Folder flags" in Mail::Box::POP3.

  • $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::POP3.

  • $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

the full signature, wrapped exactly like the original wraps it:

$obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
!$label|$filter> )
  • $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::POP3.

  • $any->listSubFolders(%options) — inherited, see "METHODS" in Mail::Box::POP3
  • $any->nameOfSubFolder( $subname, [$parentname] ) — inherited, see "Sub-folders" in Mail::Box
  • $obj->openRelatedFolder(%options) — inherited, see "Sub-folders" in Mail::Box
  • $obj->openSubFolder(%options) — inherited, see "METHODS" in Mail::Box::POP3
  • $any->topFolderWithMessages() — inherited, see "Sub-folders" in Mail::Box

🔧 Internals 🔧

Extends "Internals" in Mail::Box::POP3.

  • $obj->coerce($message, %options) — inherited, see "Internals" in Mail::Box
  • $any->create($folder, %options) — inherited, see "METHODS" in Mail::Box::POP3
  • $obj->determineBodyType($message, $head) — inherited, see "Internals" in Mail::Box
  • $class->foundIn( [$foldername], %options ) — inherited, see "Internals" in Mail::Box
  • $obj->getHead($message) — inherited, see "Internals" in Mail::Box::POP3
  • $obj->getHeadAndBody($message) — inherited, see "Internals" in Mail::Box::POP3
  • $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] ) — inherited, see "Internals" in Mail::Box
  • $obj->locker() — inherited, see "Internals" in Mail::Box
  • $obj->popClient(%options) — inherited, see "Internals" in Mail::Box::POP3
  • $obj->read(%options) — inherited, see "Internals" in Mail::Box
  • $obj->readMessages(%options) — inherited, see "Internals" in Mail::Box
  • $obj->storeMessage($message) — inherited, see "Internals" in Mail::Box
  • $obj->toBeThreaded($messages) — inherited, see "Internals" in Mail::Box
  • $obj->toBeUnthreaded($messages) — inherited, see "Internals" in Mail::Box
  • $obj->updateMessages(%options) — inherited, see "Internals" in Mail::Box
  • $obj->write(%options) — inherited, see "Internals" in Mail::Box
  • $obj->writeMessages(%options) — inherited, see "Internals" in Mail::Box::POP3

🌟 Other methods 🌟

Extends "Other methods" in Mail::Box::POP3.

  • $any->timespan2seconds($time) — inherited, see "Other methods" in Mail::Box

😭 Error handling 😭

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

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

🧹 Cleanup 🧹

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

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

🔥 DETAILS 🔥

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

🚨 DIAGNOSTICS 🚨

okay bestie, this is the part where the module yells at you. every single one of these is a real message it can throw, so let's go through them one by one, no skipping 💅

  • Error: Cannot find head back for $id on POP3 server $name. — the server was like "yep, I totally have this message," but then when we asked for its headers, it returned literally not one single line. did the message get destroyed?? who knows 😭 cast by getHeadAndBody().
  • Error: Cannot read body for $id on POP3 server $name. — we got the headers off the server just fine, but the body is giving lost-in-the-void. did the message get destroyed somewhere between reading the header and reading the body? cast by getHeadAndBody().
  • Error: Folder $name is opened read-only — you can't write to this folder unless you opened it for write or append with new(access), or unless the "force" option is set "true". no keyboard access, no touchy ✋ cast by write().
  • Warning: Message $id on POP3 server $name disappeared. — the server was acting like this message existed earlier, but now it has absolutely zero information about it anymore. it ghosted us fr fr 👻 cast by getHeadAndBody().
  • Warning: POP3 folders cannot be deleted. — every user has exactly ONE POP3 folder per server, and it's the server's administrator who creates and deletes it, not you. so no, you can't delete it. cast by delete().
  • Error: cannot create POP3 client for $name. — the connection to the POP3 server could not be established. there may be more related error messages floating around about the failure, so peek at those too. cast by popClient().
  • Warning: changes not written to read-only folder $name. — you opened the folder read-only (which, fun fact, is the default set by new(access)), you made modifications anyway, and now you wanna 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. — serious one: the specific $package (or one of its superclasses) does not implement this method even though it really should. this means some other related classes do implement it, but this class right here does not. probably go investigate and probably tell the author of the package. cast by notImplemented().
  • Error: copying failed for one message. — for some reason — disk full, removed by an external process, read-protection, whatever — it's impossible to copy one of the messages. the copying will still proceed for all the other messages though. cast by copyTo().
  • Error: destination folder $name is not writable. — the folder you're copying messages to is not opened with write access (check out new(access)). this has nothing to do with the write permission on the folder that your operating system controls, so don't get it twisted. cast by copyTo().
  • Warning: different messages with id $msgid. — we found the same message id more than once inside the same folder, but the content of the messages looks different. this should not be possible: every message must be unique. cast by messageId().
  • Error: invalid timespan '$span'. — that string does not follow the strict rules of the time span syntax that's permitted as a parameter. cast by timespan2seconds().
  • Warning: message $id disappeared from POP3 server $name. cast by getHead().
  • Warning: message-id '$msgid' does not contain a domain. — per the RFCs, message-ids need a unique random part, then an "@", then a domain name. this is done to avoid creating two messages with the same id. the warning pops up 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 the client back to the server, so 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. you're warmly invited to extend the implementation with writing though 🫶 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 the 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. slay 💅

and that's a wrap bestie 🎀 this page was brought to you by Mail-Box-POP3 version 4.02, built April 10, 2026, and it went out into the world on 2026-05-09 riding along with perl v5.40.1. go read your mail, you icon 🌸🦋💖

📦 where this page comes from