Mail::Box::Net(3pm)

📦
version 4.02 · 9 versions
, in ubuntu stonking

💖 Mail::Box::Net 💖

okay so this is Mail::Box::Net, from the User Contributed Perl Documentation (section 3pm), and bestie… it's the module for when your folders aren't chilling on your own disk but live somewhere remote. it's mostly a superclass, so no cap, you don't use it directly. buckle up, this is part one of two 🎀

✨ NAME ✨

Mail::Box::Net — handle folders which are stored remote.

like… the folder exists, but somewhere else. on a server. far away. iconic 🌐

🦋 INHERITANCE 🦋

 Mail::Box::Net
   is a Mail::Box
   is a Mail::Reporter

 Mail::Box::Net is extended by
   Mail::Box::IMAP4
   Mail::Box::POP3

so it's a Mail::Box, which is a Mail::Reporter (the whole family tree, we love a lineage 👑), and then Mail::Box::IMAP4 and Mail::Box::POP3 build on top of it. main character energy all around.

🌸 SYNOPSIS 🌸

  # Do not instantiate this object directly

that's it. that's the whole synopsis. do not make one of these yourself, bestie, it's giving "abstract base class" and the subclasses handle the actual protocol stuff 💅

🫶 DESCRIPTION 🫶

at the moment, this object is extended by:

  • Mail::Box::POP3 — implements the POP3 protocol.
  • Mail::Box::IMAP4 — implements the IMAP4 protocol.

Extends "DESCRIPTION" in Mail::Box.

🔥 OVERLOADED 🔥

Extends "OVERLOADED" in Mail::Box.

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

🎀 Constructors 🎀

Extends "Constructors" in Mail::Box.

$class->new(%options)

inherited, see "Constructors" in Mail::Box.

here's the whole vibe table of what you can pass in — option, where it's defined, and its default. no skipping, we list every single one:

  • access — defined in Mail::Box — default 'r'
  • 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 false
  • 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 '/'
  • 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 <folder-class>::Message
  • multipart_type — defined in Mail::Box — default Mail::Message::Body::Multipart
  • password — default undef
  • remove_when_empty — defined in Mail::Box — default <false>
  • save_on_exit — defined in Mail::Box — default true
  • server_name — default undef
  • server_port — default undef
  • trusted — defined in Mail::Box — default <false>
  • username — default undef

and now the same options again but with the actual tea ☕ — the ones that matter here are password, server_name, server_port and username, because remote:

  • access => $mode
  • 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 — the $password which is required to contact the remote server. 🔐
  • remove_when_empty => BOOLEAN
  • save_on_exit => BOOLEAN
  • server_name => $host — the name of the $host which contains the remote mail server. 🌐
  • server_port => $number — port $number in use by the server application. 🔌
  • trusted => BOOLEAN
  • username => $username — the username which is to be used for the remote server. 🫶

🌈 Attributes 🌈

Extends "Attributes" in Mail::Box.

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

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

🌸 Folder flags 🌸

Extends "Folder flags" in Mail::Box.

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

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

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

💅 Internals 💅

Extends "Internals" in Mail::Box.

  • $obj->coerce($message, %options) — inherited, see "Internals" in Mail::Box
  • $any->create($folder, %options) — create a new folder on the remote server. improves base, see "Internals" in Mail::Box ✨
 -Option   --Defined in--Default
  folderdir  Mail::Box   undef
  • folderdir => $directory
  • $obj->determineBodyType($message, $head) — inherited, see "Internals" in Mail::Box
  • $class->foundIn( [$foldername], %options ) — inherited, see "Internals" in Mail::Box
  • $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] ) — inherited, see "Internals" in Mail::Box
  • $obj->locker() — inherited, see "Internals" in Mail::Box
  • $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

⭐ Other methods ⭐

Extends "Other methods" in Mail::Box.

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

😭 Error handling 😭

Extends "Error handling" in Mail::Box.

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

🧚 Cleanup 🧚

Extends "Cleanup" in Mail::Box.

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

🍓 DETAILS 🍓

Extends "DETAILS" in Mail::Box.

💜

💀 DIAGNOSTICS 💀

okay bestie, listen 👂 — these are the messages this module will throw at you when the vibe check fails. Read them, learn them, love them, because they're your map to Whatever Went Wrong™.

  • Error: Folder $name is opened read-only — so you're tryna write to a folder that's living its read-only truth 🙅♀️. You can't do that unless you opened it to write or append through new(access), or you set the "force" option to "true". Cast by write(). Periodt.
  • Warning: changes not written to read-only folder $name. — the classic. You opened the folder read-only (which is literally the default set by new(access)), you made a bunch of lil modifications, and now you wanna close it? Girl. 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, no cap 😭. That specific $package (or one of its superclasses) just doesn't implement this method where it's supposed to. What this means: other related classes do implement it, but the class in your hands does not. You should probably investigate this, and probably slide into the author of the package's DMs about it. Cast by notImplemented().
  • Error: copying failed for one message. — for some reason — disk full, an external process yeeted it, read-protection, whatever — one of the messages could not be copied. Copying is gonna keep going for the other messages though, so not all is lost 💅. Cast by copyTo().
  • Error: destination folder $name is not writable. — the folder you're copying messages to isn't opened with write access (peep new(access)). And no, this has nothing to do with write permission to the folder controlled by your operating system, so don't come at me with ls -l receipts 📋. Cast by copyTo().
  • Warning: different messages with id $msgid. — the message id showed up more than once inside the same folder, but the content of those messages looks different. This should not be possible: each message must be unique, bestie. Something is sus. Cast by messageId().
  • Warning: folder $name not deleted: not writable. — folder's gotta be opened with write access via new(access) or removing it gets refused. So yeah, you might have write-access per the operating system, but that will not automatically mean this "delete" method lets you do it. And the reverse remark is valid as well 🔁. Cast by delete().
  • 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 '$msgid' does not contain a domain. — per the RFCs, message-ids need a unique random part, then an "@", then a domain name. This exists to avoid creating two messages with the same id. The warning pops up when the "@" is missing from the string. Cast by messageId().
  • Warning: the term 'hostname' is confusing wrt folder. You probably need 'server_name'. — cast by new().
  • Error: unknown value to folder->close(write => $when). — cast by close().
  • Error: you cannot add a message which is already part of a folder to a new one. Please use moveTo or copyTo. — cast by addMessage(). Like, the message already has a home 🏠, don't try to give it a second one. moveTo or copyTo, bestie, pick one.

🔍 SEE ALSO

This module is part of Mail-Box version 4.02, built on April 10, 2026.

Website: http://perl.overmeer.net/CPAN/

Go lurk, it's iconic 🦋

📜 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.

and that's a wrap, bestie 🎀✨ you just read Mail::Box::Net(3pm) from Mail-Box 4.02, built April 10, 2026, shipped with perl v5.40.1 and stamped 2026-05-09. go forth and handle your mail folders, you absolute legend 👑💅

📦 where this page comes from