Mail::...4::User(3pm)

📦
version 4.01 · 7 versions
, in ubuntu resolute, ubuntu stonking

💌 Mail::Server::IMAP4::User — the Perl man page, but make it make sense

User Contributed Perl Documentation · section 3pm · bestie edition ✨

okay so. you know how one (1) IMAP account can have folders? like, a LOT of folders? this module is the girlboss who keeps track of all of them for one user. it's the folder-manager of your dreams, and yes, she speaks IMAP.

🌸 NAME 🌸

Mail::Server::IMAP4::User — manage the folders of one user 💅

🧬 INHERITANCE 🧬

the family tree, and she ate:

 Mail::Server::IMAP4::User
   is a Mail::Box::Manage::User
   is a Mail::Box::Manager
   is a Mail::Reporter

✨ SYNOPSIS ✨

the whole vibe in one line, no cap:

 my $mgr = Mail::Server::IMAP4::User->new(...);

📖 DESCRIPTION 📖

this class takes a totally normal Mail::Box::Manager and adds IMAP protocol features to it. that's it, that's the girl. 💖

Extends "DESCRIPTION" in Mail::Box::Manage::User.

🛠️ METHODS 🛠️

Extends "METHODS" in Mail::Box::Manage::User.

🌷 Constructors 🌷

Extends "Constructors" in Mail::Box::Manage::User.

$class->new(%options)

Inherited, see "METHODS" in Mail::Box::Manage::User.

here's the whole options lineup, iconic behavior:

 -Option             --Defined in             --Default
  autodetect           Mail::Box::Manager       undef
  collection_type      Mail::Box::Manage::User  Mail::Box::Collection
  default_folder_type  Mail::Box::Manager       'mbox'
  delimiter            Mail::Box::Manage::User  "/"
  folder_id_type       Mail::Box::Manage::User  Mail::Box::Identity
  folder_types         Mail::Box::Manager       <all standard types>
  folderdir            Mail::Box::Manager       [ '.' ]
  folderdirs           Mail::Box::Manager       <synonym for C<folderdir>>
  identity             Mail::Box::Manage::User  <required>
  inbox                Mail::Box::Manage::User  undef
  index_filename                                $folderdir/index
  topfolder_name       Mail::Box::Manage::User  '='
  • autodetect => $type|\@types
  • collection_type => $class
  • default_folder_type => $type|CLASS
  • delimiter => STRING
  • folder_id_type => CLASS|OBJECT
  • folder_types => $typedef|\@typedefs
  • folderdir => DIRECTORY
  • folderdirs => [DIRECTORIES]
  • identity => OBJECT
  • inbox => $name
  • index_filename => FILENAME
  • topfolder_name => $name

🦋 Attributes 🦋

Extends "Attributes" in Mail::Box::Manage::User.

  • $obj->defaultFolderType() — Inherited, see "Attributes" in Mail::Box::Manager
  • $obj->delimiter() — Inherited, see "Attributes" in Mail::Box::Manage::User
  • $obj->folderTypeDefs() — Inherited, see "Attributes" in Mail::Box::Manager
  • $obj->folderTypes() — Inherited, see "Attributes" in Mail::Box::Manager
  • $obj->folderdir() — Inherited, see "Attributes" in Mail::Box::Manager
  • $obj->identity() — Inherited, see "Attributes" in Mail::Box::Manage::User
  • $obj->inbox( [$name] ) — Inherited, see "Attributes" in Mail::Box::Manage::User
  • $obj->indexFilename() — returns the filename of the index file. that's literally it. 📇
  • $obj->registerType($type, $class, %options) — Inherited, see "Attributes" in Mail::Box::Manager
  • $obj->threads( [@params] ) — Inherited, see "Attributes" in Mail::Box::Manager
  • $obj->topfolder() — Inherited, see "Attributes" in Mail::Box::Manage::User

📂 Manage open folders 📂

Extends "Manage open folders" in Mail::Box::Manage::User.

  • $obj->close($folder, %options) — Inherited, see "Manage open folders" in Mail::Box::Manager
  • $obj->closeAllFolders(%options) — Inherited, see "Manage open folders" in Mail::Box::Manager
  • $obj->isOpenFolder($folder) — Inherited, see "Manage open folders" in Mail::Box::Manager
  • $obj->open( [$foldername], %options ) — Inherited, see "Manage open folders" in Mail::Box::Manager
  • $obj->openFolders() — Inherited, see "Manage open folders" in Mail::Box::Manager

🗂️ Manage existing folders 🗂️

Extends "Manage existing folders" in Mail::Box::Manage::User.

  • $obj->folder($name) — Inherited, see "Manage existing folders" in Mail::Box::Manage::User
  • $obj->folderCollection($name) — Inherited, see "Manage existing folders" in Mail::Box::Manage::User
  • $obj->rename($oldname, $newname, %options) — Inherited, see "Manage existing folders" in Mail::Box::Manage::User

💌 Move messages to folders 💌

Extends "Move messages to folders" in Mail::Box::Manage::User.

  • $obj->appendMessage( [$folder|$foldername], $messages, %options ) — Inherited, see "Move messages to folders" in Mail::Box::Manager
  • $obj->copyMessage( [$folder|$foldername], @messages, %options ) — Inherited, see "Move messages to folders" in Mail::Box::Manager
  • $obj->moveMessage( [$folder|$foldername], @messages, %options ) — Inherited, see "Move messages to folders" in Mail::Box::Manager

🧵 Manage message threads 🧵

Extends "Manage message threads" in Mail::Box::Manage::User.

  • $obj->discoverThreads( [@folders], %options ) — Inherited, see "Manage message threads" in Mail::Box::Manager

🔧 Internals 🔧

Extends "Internals" in Mail::Box::Manage::User.

  • $obj->decodeFolderURL($url) — Inherited, see "Internals" in Mail::Box::Manager
  • $obj->toBeThreaded($folder, $messages) — Inherited, see "Internals" in Mail::Box::Manager
  • $obj->toBeUnthreaded($folder, $messages) — Inherited, see "Internals" in Mail::Box::Manager

😭 Error handling 😭

Extends "Error handling" in Mail::Box::Manage::User.

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

🧹 Cleanup 🧹

Extends "Cleanup" in Mail::Box::Manage::User.

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

👑 Manage folders 👑

$obj->create($name, %options)

makes you a brand new folder with the name you picked. you get back folder info, and she keeps it very simple. in the accidental little oopsie case where that folder already exists, you get a warning and the data of that existing folder back. improves base, see "Manage existing folders" in Mail::Box::Manage::User.

 -Option       --Defined in             --Default
  create_real    Mail::Box::Manage::User  true
  create_supers  Mail::Box::Manage::User  false
  deleted        Mail::Box::Manage::User  false
  id_options     Mail::Box::Manage::User  []
  • create_real => BOOLEAN
  • create_supers => BOOLEAN
  • deleted => BOOLEAN
  • id_options => ARRAY

$obj->delete($name, %options)

removes every sign of that folder from the file-system. messages still chilling in the folder? gone too, bestie. 😳

this one returns a "true" value when the folder got removed or when it wasn't found in the first place — so "false" means failure. remember that, it's giving trick question.

you can also delete a folder via $folder->delete, which will call this method right here. the %options, which get used for some other folder types, are just ignored here: the user's index already holds the required details. improves base, see "Manage existing folders" in Mail::Box::Manage::User.

 -Option   --Defined in        --Default
  recursive  Mail::Box::Manager  <folder's default>
  • recursive => BOOLEAN
» example: how to delete a folder
  print "no xyz (anymore)\n" if $user->delete('xyz');

$obj->folderInfo($name)

hands you a hash full of folder info. normally this is cheap to get, because it's all cached in an index file. 🎀

DO NOT modify the values you find in the hash, because that data may or may not be lost. seriously.
DO NOT trust on the existence of any field in the info: fields may get renamed, removed, or added over time. not all folder indexes will be generated by the same software release, so don't be surprised.
» example: how to get global info about a folder
  my $info = $user->folderInfo($name); # get info

🔍 DETAILS 🔍

Extends "DETAILS" in Mail::Box::Manage::User.

💖 DIAGNOSTICS 💖

okay bestie, this is the part where the module yells at you. every one of these is a real message you might see, so let's go through them one by one — no skimming, fr fr.

  • Error: Folder $name is not a Mail::Box; cannot add a message. — the folder you tried to append a message to? it's an object that is not a folder type extending Mail::Box. lowkey it's probably not even a folder at all. cast by appendMessage().
  • Error: Use appendMessage() to add messages which are not in a folder. — bestie you literally don't need to copy this message into the folder, because you are not sharing the message between folders. cast by copyMessage().
  • Warning: Use moveMessage() or copyMessage() to move between open folders. — the message is already part of a folder, and now you want it appended to a different folder. you gotta pick: copy or move. both of them will clone the message (not the body tho, because bodies are immutable 💅). cast by appendMessage().
  • Fault: cannot create folder directory $dir: $! — cast by create().
  • Error: cannot rename folder $from to $to: higher levels are missing. — unless you set create(create_supers), all higher level folders have to exist before this new one can be created. cast by rename().
  • Fault: cannot write name for folder in $file: $! — cast by create().
  • Error: class $package does not implement method $method. — this one is a fatal error, so pay attention: the specific $package (or one of its superclasses) does not implement this method where it should. what it means: some other related classes do implement this method, but the class in front of you does not. probably you should investigate this, and probably inform the author of the package. cast by notImplemented().
  • Error: failed for folder default $class: $@ — cast by open().
  • Fault: failed writing folder name to $file: $! — cast by create().
  • Warning: folder $name already exists, creation skipped. — cast by create().
  • Error: folder $name does not exist, failed opening $type. — the folder doesn't exist, and creating it is not permitted (peep open(create)) or it just didn't succeed. and when you don't have sufficient access rights to the folder (like, wrong password for POP3), this warning gets produced too. the manager tried to open a folder of the specified type. it may help to explicitly state the type of your folder with the "type" option. there will probably be another warning or error message related to this report that gives you more detail about its cause. you may also have a look at new(autodetect) and new(folder_types). cast by open().
  • Error: folder $name is already open. — you cannot ask the manager for a folder which is already open. in some older releases (before MailBox 2.049) this was permitted, but then behaviour changed, because many nasty side-effects are to be expected. for instance, a Mail::Box::update() on one folder handle would influence the second, probably unexpectedly. cast by open().
  • Error: folder $name not under top. — cast by folderCollection().
  • Warning: folder type $type is unknown, using autodetect. — the specified folder type (see open(type), possibly derived from the folder name when specified as url) is not known to the manager. this may mean you forgot to require the Mail::Box extension which implements this folder type — but probably it's a typo. usually the manager is able to figure-out which type to use by itself. cast by open().
  • Error: illegal folder URL '$url'. — the folder name was specified as URL, but not according to the syntax. see decodeFolderURL() for an description of the syntax. cast by open().
  • Error: no foldername specified to open. — open() needs a folder name as first argument (before the list of options), or with the "folder" option within that list. if no name was found, the MAIL environment variable is checked. and when even that doesn't result in a usable folder, this error shows up. it may also be caused by an accidental odd-length option list. cast by open().
  • Error: source folder for rename does not exist: $from to $to. — cast by rename().
  • Error: threader $class is not derived from $base. — cast by discoverThreads().
  • Fault: unable to remove folder {$name} — cast by delete().
  • Error: unusable threader $class: $@ — cast by discoverThreads().
  • Warning: will never create a folder $name without having write access. — you set open(create), but you only want to read the folder. create is only useful for folders which have write or append access modes (see Mail::Box::new(access)). cast by open().
  • Error: you need to pass a $base derived threader, got $class. — cast by discoverThreads().

✨ SEE ALSO ✨

this module is part of Mail-Box-IMAP4 version 4.01, built on December 13, 2025. Website: http://perl.overmeer.net/CPAN/

📜 LICENSE 📜

for contributors, see file ChangeLog.

this software is copyright (c) 2001-2025 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 the whole page, bestie!! 🌈 you made it to the end, main character energy fr. this one's from perl v5.40.1, dated 2026-01-21, and it's the Mail::...4::User(3pm) manual — go forth and open your folders responsibly 💖✨🎀

📦 where this page comes from