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

📦

version 4.02 · 9 versions

💖 Mail::Box::Manage::User 💖

okay bestie, welcome to Mail::Box::Manage::User (that's the 3pm manual page, it's giving Perl) — this is the lil module that takes care of a whole user's folders, and honestly? it ate. let's get into it ✨

🎀 NAME 🎀

Mail::Box::Manage::User — manages the folders of a user 🫶

🌸 INHERITANCE 🌸

the family tree, periodt:

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

Mail::Box::Manage::User is extended by
  Mail::Server::IMAP4::User

✨ SYNOPSIS ✨

here's the vibe, copy-paste ready:

use Mail::Box::Manage::User;
use User::Identity;

my $id      = User::Identity->new(...);
my $user    = Mail::Box::Manage::User->new(
  identity  => $id,
  folderdir => "$ENV{HOME}/Mail",
  inbox     => $ENV{MAIL},
);

my $inbox   = $user->open($user->inbox);
my $top     = $user->topfolder;

🦋 DESCRIPTION 🦋

okay so, Mail::Box::Manager handles a set of open folders, right? this extension is the glow-up: it adds knowledge about some related person. and at the same time, it's gonna try to cache some info about that person's folder files. lowkey efficient 💅

Extends "DESCRIPTION" in Mail::Box::Manager.

👑 METHODS 👑

Extends "METHODS" in Mail::Box::Manager.

🌈 Constructors 🌈

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

$class->new(%options) — use new(default_folder_type) to explicitly state which kind of folders you use. Improves base, see "Constructors" in Mail::Reporter.

the options table, bestie, memorize it:

 -Option             --Defined in        --Default
  autodetect           Mail::Box::Manager  undef
  collection_type                          Mail::Box::Collection
  default_folder_type  Mail::Box::Manager  'mbox'
  delimiter                                "/"
  folder_id_type                           Mail::Box::Identity
  folder_types         Mail::Box::Manager  <all standard types>
  folderdir            Mail::Box::Manager  [ '.' ]
  folderdirs           Mail::Box::Manager  <synonym for C<folderdir>>
  identity                                 <required>
  inbox                                    undef
  topfolder_name                           '='

autodetect => $type|\@types
collection_type => $class — subfolders grouped together.
default_folder_type => $type|CLASS
delimiter => STRING — the separator used in folder names. and no, it does not have to be the same as what your directory system is using, she's independent 💅
folder_id_type => CLASS|OBJECT
folder_types => $typedef|\@typedefs
folderdir => DIRECTORY
folderdirs => [DIRECTORIES]
identity => OBJECT — the main difference between Mail::Box::Manager and this class is the concept of some person (or virtual person) who's files are being administered by this object. the OBJECT is an User::Identity.

the smallest identity that will do? my $id = User::Identity->new('myname')

inbox => $name — the $name of the user's inbox.
topfolder_name => $name

🧚 Attributes 🧚

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

$obj->defaultFolderType() — inherited, see "Attributes" in Mail::Box::Manager
$obj->delimiter() — folder path delimiter
$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() — returns a User::Identity object.
$obj->inbox( [$name] ) — (set and) get the $name of the mailbox which is considered the folder for incoming mail. in many protocols, this folder is handled separately. for instance in IMAP this is the only case-insensitive folder name 👀
$obj->registerType($type, $class, %options) — inherited, see "Attributes" in Mail::Box::Manager
$obj->threads( [@params] ) — inherited, see "Attributes" in Mail::Box::Manager
$obj->topfolder() — returns the top folder of the user's mailbox storage.

💜 Manage open folders 💜

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

$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::Manager.

$obj->create($name, %options) — creates a new folder with the specified name. an folder's administrative structure (Mail::Box::Identity) is returned, but the folder is not opened.

in the accidental case that the folder already exists, a warning will be issued, and an empty list/undef returned. (yeah, accidental case, we've all been there 😭)

the %options are passed to Mail::Box::create() of your default folder type, except for the options intended for this method itself.

 -Option       --Default
  create_real    true
  create_supers  false
  deleted        false
  id_options     []

create_real => BOOLEAN — when this option is false, the pysical folder will not be created, but only the administration is updated.
create_supers => BOOLEAN — when you create a folder where upper hierarchy level are missing, they will be created as well.
deleted => BOOLEAN — the folder starts as deleted.
id_options => ARRAY — values passed to the instantiated Mail::Box::Identity. that object is very picky about the initiation values it accepts, no cap.

$obj->delete($name) — remove all signs from the folder on the file-system. messages still in the folder will be removed. this method returns a true value when the folder has been removed or not found, so ""false"" means failure.

it's also possible to delete a folder using $folder->delete, which will call this method here. OPTIONS, which are used for some other folder types, will be ignored here: the user's index contains the required details. improves base, see "Manage existing folders" in Mail::Box::Manager.

 -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->folder($name) — returns the folder description, a Mail::Box::Identity.
$obj->folderCollection($name) — returns a pair: the folder collection (Mail::Box::Collection) and the base name of $name.
$obj->rename($oldname, $newname, %options) — rename the folder with name $oldname to $newname. both names are full pathnames.

 -Option       --Default
  create_supers  false

create_supers => BOOLEAN — when you rename a folder to a place where upper hierarchy levels are missing, they will get be defined, but with the deleted flag set.

🌟 Move messages to folders 🌟

Extends "Move messages to folders" in Mail::Box::Manager.

$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::Manager.

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

🔥 Internals 🔥

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

$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::Manager.

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

🫧 Cleanup 🫧

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

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

🌈 DETAILS 🌈

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

💀 DIAGNOSTICS 💀

ok bestie, this is the part where things go sideways and the module starts yelling at you. ngl, each of these messages is basically the code telling you exactly what you did wrong, so read them like they're texts from a friend who's a little disappointed but still loves you. 🫶 Cast = which method threw it, so you know who to blame.

`Error: Folder $name is not a Mail::Box; cannot add a message.`

The folder you wanted to append that message to? It's an object that isn't a folder type extending Mail::Box. Honestly it might not even be a folder at all, like at all at all. Cast by appendMessage().

`Error: Use appendMessage() to add messages which are not in a folder.`

Girl, you do not need to copy this message into the folder, because you're not sharing the message between folders in the first place. 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 in a different folder. You have to pick a lane: copy or move — either one clones the message (but not the body, because bodies are immutable, periodt). Cast by appendMessage().

`Error: cannot create folder $name: higher levels missing.`

Unless you set create(create_supers), every higher level folder has to already exist before this new one can be born. No skipping generations. 👑 Cast by create().

`Error: cannot rename folder $from to $to: higher levels are missing.`

Same energy as above, but for renaming: unless you set create(create_supers), all higher level folders must exist before the new one can be created. Cast by rename().

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

Fatal, bestie. 💀 The specific $package (or one of its superclasses) just does not implement this method where it's supposed to. The tea here is that some other related classes do implement it — this one just doesn't. You should probably investigate and probably tell the author of the package. Cast by notImplemented().

`Error: failed for folder default $class: $@`

Cast by open(). That's it, that's the whole message. 😭

`Error: folder $name already exists.`

Cast by create(). You tried to make something that's already here. It's giving déjà vu.

`Error: folder $name does not exist, failed opening $type.`

The folder doesn't exist, and creating isn't allowed (peep open(create)) — or the creating just didn't work out. And if you don't have sufficient access rights to the folder (like, wrong password for POP3), you'll get this warning too. 🙈

The manager actually tried to open a folder of the specified type. It might help to explicitly state the type of your folder with the type option. There's probably another warning or error hanging around that's related and has more deets about the cause. You can also have a look at new(autodetect) and new(folder_types). Cast by open().

`Error: folder $name is already open.`

You can't ask the manager for a folder that's already open. In some older releases (before MailBox 2.049), this was permitted, but then behaviour changed, because way too many nasty side-effects are to be expected. For instance, a Mail::Box::update() on one folder handle would influence the second, probably unexpectedly. Messy. Cast by open().

`Error: folder $name not under top.`

Cast by folderCollection(). Short and mysterious, iykyk.

`Warning: folder type $type is unknown, using autodetect.`

The folder type you specified — see open(type), and it might be derived from the folder name when you gave it as a url — is not known to the manager. This could mean you forgot to require the Mail::Box extension that implements this folder type... but ngl it's probably a typo. 💅 Usually the manager can figure out which type to use all by itself. Cast by open().

`Error: illegal folder URL '$url'.`

The folder name was given as a URL, but it's not following the syntax. Check decodeFolderURL() for a description of the syntax. Cast by open().

`Error: no foldername specified to open.`

open() needs a folder name as its first argument (before the list of options), or with the folder option inside that list. If no name was found, the MAIL environment variable gets checked. And when even that doesn't give you a usable folder? Boom, this error. It may also be caused by an accidental odd-length option list, so double check that list, bestie. Cast by open().

`Error: source folder for rename does not exist: $from to $to.`

Cast by rename(). Can't rename what isn't there. 🦋

`Error: threader $class is not derived from $base.`

Cast by discoverThreads().

`Error: unusable threader $class: $@`

Cast by discoverThreads(). The threader is simply not threading. 💀

`Error: user manager requires an identity.`

Cast by new(). It needs to know who you are, main character. 👑

`Warning: will never create a folder $name without having write access.`

You set open(create) but you only want to read the folder. Here's the thing: create is only useful for folders that 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(). You handed it the wrong type and it's not accepting substitutions, respectfully.

🌈 SEE ALSO 🌈

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

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

🎀 LICENSE 🎀

For contributors see file ChangeLog.

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, honestly. 💖

and that's a wrap on the perl v5.40.1 version from 2026-05-09 💅 thanks for reading all the way to the end bestie, you ate that fr fr 🌸✨

📦 where this page comes from

ubuntu stonking: libmail-box-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