Mail::...:IMAP4s(3pm)

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

🦋 Mail::Box::IMAP4s 🦋

okay bestie, welcome to the Mail::...:IMAP4s(3pm) page from the User Contributed Perl Documentation 💅 (yes the title is literally abbreviated like that, no cap).

✨ NAME ✨

Mail::Box::IMAP4s — handle IMAP4 folders as client, with ssl connection 🔒

🌸 INHERITANCE 🌸

the family tree, and she's got generations:

Mail::Box::IMAP4s
  is a Mail::Box::IMAP4
  is a Mail::Box::Net
  is a Mail::Box
  is a Mail::Reporter

🫶 SYNOPSIS 🫶

the entire vibe, verbatim:

my $url = 'imap4s://user:passwd@host:port/INBOX';
my $url = 'imaps://user:passwd@host:port/INBOX';

use Mail::Box::IMAP4s;
my $folder = Mail::Box::IMAP4s->new(folder => $url, ...);

my $mgr    = Mail::Box::Manager->new;
my $folder = $msg->open($url, retry => 3, interval => 5);

💌 DESCRIPTION 💌

See Mail::Box::IMAP4.

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

🎀 OVERLOADED 🎀

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

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

🌱 Constructors 🌱

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

  • $class->new(%options) — inherited, see "METHODS" in Mail::Box::IMAP4

and the moment you've all been waiting for, the full option roster 👑 (three columns: option, where it's defined, and its default — nope, we're not skipping a 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
  • cache_body — defined in Mail::Box::IMAP4, default NO
  • cache_head — defined in Mail::Box::IMAP4, default NO or DELAY
  • cache_labels — defined in Mail::Box::IMAP4, default NO or DELAY
  • 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::Box::IMAP4::Head or Mail::Message::Head::Complete
  • join_connection — defined in Mail::Box::IMAP4, default true
  • 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::IMAP4::Message
  • multipart_type — defined in Mail::Box, default Mail::Message::Body::Multipart
  • password — defined in Mail::Box::Net, 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 993
  • ssl — default { SSL_verify_mode => SSL_VERIFY_NONE }
  • starttls — default false
  • transporter — defined in Mail::Box::IMAP4, default Mail::Transport::IMAP4
  • trusted — defined in Mail::Box, default <false>
  • username — defined in Mail::Box::Net, default undef

now the same squad again, with their lil signatures 🌈:

  • access => $mode
  • body_delayed_type => CLASS
  • body_type => CLASS|CODE
  • cache_body => 'NO'|'YES'|'DELAY'
  • cache_head => 'NO'|'PARTIAL'|'DELAY'
  • cache_labels => 'NO'|'WRITE'|'DELAY'
  • 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
  • join_connection => BOOLEAN
  • keep_dups => BOOLEAN
  • lock_file => $file
  • lock_timeout => $seconds
  • lock_type => CLASS|STRING|ARRAY
  • lock_wait => $seconds
  • locker => OBJECT
  • manager => $manager
  • message_type => CLASS
  • multipart_type => CLASS
  • password => $password
  • remove_when_empty => BOOLEAN
  • save_on_exit => BOOLEAN
  • server_name => $host
  • server_port => $number
  • ssl => \%config|\@pairs — parameters to initialize the SSL connection. 🔐
  • starttls => BOOLEAN
  • transporter => $object|$class
  • trusted => BOOLEAN
  • username => $username

🪞 Attributes 🪞

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

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

  • $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 "METHODS" in Mail::Box::IMAP4
  • $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::IMAP4.

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

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

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

  • $obj->body( [$body] ) — inherited, see "Internals" in Mail::Box::IMAP4
  • $obj->coerce($message, %options) — inherited, see "Internals" in Mail::Box
  • $any->create($folder, %options) — inherited, see "METHODS" in Mail::Box::Net
  • $obj->createTransporter($class, %options) — inherited, see "Internals" in Mail::Box::IMAP4
  • $obj->determineBodyType($message, $head) — inherited, see "Internals" in Mail::Box
  • $obj->fetch( <$messages|$selection>, $info ) — inherited, see "Internals" in Mail::Box::IMAP4
  • $class->foundIn( [$foldername], %options ) — inherited, see "Internals" in Mail::Box
  • $obj->getHead($message) — inherited, see "Internals" in Mail::Box::IMAP4
  • $obj->getHeadAndBody($message) — inherited, see "Internals" in Mail::Box::IMAP4
  • $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->transporter( [$object] ) — inherited, see "Internals" in Mail::Box::IMAP4
  • $obj->updateMessages(%options) — inherited, see "Internals" in Mail::Box
  • $obj->write(%options) — inherited, see "Internals" in Mail::Box::IMAP4
  • $obj->writeMessages(%options) — inherited, see "Internals" in Mail::Box::IMAP4

🍓 Other methods 🍓

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

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

🩹 Error handling 🩹

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

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

🧼 Cleanup 🧼

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

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

🔍 DETAILS 🔍

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

✨ DIAGNOSTICS ✨

okay bestie, sometimes this module is gonna yell at you, and here's the whole mood-ring of things it can say so you're never confused, k? 💅

  • Warning: cannot find head back for $id in $folder. — we did read that header earlier, but now it's giving empty vibes: the IMAP4 server just isn't handing over those header lines anymore. Cast by getHeadAndBody() 😭
  • Warning: cannot read body for $id in $folder. — we got the header from the IMAP4 server, but the body? nowhere. no cap, no reason given, just mystery. Cast by getHeadAndBody() 💀
  • Error: class $package does not implement method $method. — fatal, fr fr. That specific $package (or literally any of its superclasses) doesn't implement this method even though it should. Which means some other related classes do have it and this one just... doesn't. Investigate, bestie, and probably tell the author of the package about it. Cast by notImplemented() 🙈
  • Error: copying failed for one message. — something blocked the copy of one message. Could be disk full, the message got removed by some external process, or it's read-protected, whatever. Long story short, that one message is not going anywhere, but copying keeps going for all the rest. Cast by copyTo() ✨
  • Error: couldn't select IMAP4 folder $name. — Cast by transporter() 🌸
  • Error: destination folder $name is not writable. — the folder you're copying messages into wasn't opened with write access (peep new(access)). And lowkey this has nothing to do with filesystem write permission, that's your operating system's whole separate thing. Cast by copyTo() 🎀
  • Warning: different messages with id $msgid. — same message id showed up more than once in one folder, but the content looks different?? Which should not be possible — every message is supposed to be unique. Iconic, but in the bad way. Cast by messageId() 🦋
  • Warning: folder $name not deleted: not writable. — to remove a folder it has to be opened with write access via new(access), otherwise the removal is refused. So yeah, you might have write access per the operating system and still get blocked here — this method just doesn't care, and the reverse is true as well. Cast by delete() 💜
  • Notice: impossible to keep deleted messages in IMAP folder $name. — some folder types have a 'deleted' flag they can stash in the folder to deal with later, and they remember that even after the folder gets rewritten. IMAP4? cannot play that trick, sorry. Cast by write() ⭐
  • Error: invalid timespan '$span'. — that string just doesn't follow the strict rules of the time span syntax you're allowed to pass as a parameter. Cast by timespan2seconds() 🔥
  • Warning: message $id disappeared from $folder. — we went to grab that specific message from the server and it's just... gone. poof. Cast by getHeadAndBody() 🍓
  • Warning: message {id} disappeared from {folder}. — same situation, same gone-ness, just trying to get the specific message and it appears to be gone. 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, and that's specifically so two messages never end up with the same id. The warning shows up when the "@" is missing from the string. Cast by messageId() 🌈
  • Error: no IMAP4 transporter configured. — Cast by transporter() 🌸
  • Error: you cannot add a message which is already part of a folder to a new one. Please use moveTo or copyTo. — exactly what it says, bestie. Cast by addMessage() 👑

👀 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 🎉 the docs you just read are from perl v5.40.1, dated 2026-01-21 — yeah she's got a timestamp and a Perl version, and now you know every single one of her secrets. go forth and IMAP responsibly 💖✨

📦 where this page comes from