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

💌 Mail::Server::IMAP4::List

okay bestie, gather round 💖 this is the Mail::Server::IMAP4::List page from the User Contributed Perl Documentation — it's the lil module that handles all your folder-related IMAP4 answers. she's giving backend baddie, she's giving "I answer LIST requests and I do it flawlessly," and honestly? she ate. 🎀

---

✨ NAME ✨

Mail::Server::IMAP4::List — folder related IMAP4 answers 🌸

---

✨ SYNOPSIS ✨

  my $imap = Mail::Server::IMAP4::List->new(
    folders   => $folders,   # Mail::Box::Identity
    inbox     => $inbox,     # Mail::Box
    delimiter => '#'
  );

  my $imap = Mail::Server::IMAP4::List->new(user => $user);
  print $imap->list(...);        # for LIST command

---

✨ DESCRIPTION ✨

not me opening this section and it's literally just… empty 🙈 like the original authors said "the vibe explains itself" and moved straight on to METHODS. lowkey iconic of them, honestly. everything you need is down there 👇

---

✨ METHODS ✨

🧚 Constructors

$class->new(%options)

Create a (temporary) object to handle the LIST requests for a certain user, based upon a set of folders. fr fr, she does not open your folders to answer these questions — the data is kept by Mail::Box::Identity and Mail::Box::Collection objects, so it's giving fast, it's giving efficient, it's giving no unnecessary drama. 👑

 -Option   --Default
  delimiter  '/'
  folders    <from user>
  inbox      <from user>
  user       undef

• delimiter => STRING|CODE — either the constant delimiter, or a code reference that gets a folder name passed to it and should return the delimiter string used in that name. ⚠️ if that folder name is empty, you must report the default delimiter. peek at delimiter() for an example, bestie.
• folders => OBJECT — you gotta specify either a set of folders explicitly or via the user. Some Mail::Box::Identity OBJECT is needed. no object, no vibes. 💅
• inbox => BOOLEAN — for now this is only used to see whether there's an inbox, so a truth value will do. this may change in the future (iykyk 👀). by default, the flag is set if the "user" inbox is defined.
• user => OBJECT — a Mail::Box::Manage::User OBJECT, representing the user whose folders must get reported.

🌸 Attributes

• $obj->delimiter( [$foldername] ) — returns the delimiter string. the foldername is only required when a CODE reference was specified at initiation. simple as that, periodt.

» example: setting-up an IMAP4 delimiter 🦋

  sub delim($)
  {   my $path = shift;
      my ($delim, $root)
        = $path =~ m/^(#news\.)/ ? ('.', $1)
        : $path =~ m!^/!         ? ('/', '/')
        :                          ('/', '');

      wantarray ? ($delim, $root) : $delim;
  }

  my $list = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
  print $list->delimiter('abc/xyz');      # returns a / (slash) and ''
  print $list->delimiter('#news.feed');   # returns a . (dot)   and $news.
  print $list->delimiter('');             # returns default delimiter

• $obj->folders() — returns the Mail::Box::Identity of the toplevel folder. the main character folder, if you will. 👑
• $obj->inbox() — returns the Mail::Box or filename of the INBOX. 📬
• $obj->user() — returns the Mail::Box::Manage::User object, if defined.

💅 IMAP Commands

$obj->list($base, $pattern)

IMAP's LIST command. heads up bestie: the request must be partially decoded, and the answer will need to be encoded. don't skip that step, it's not optional. 😭

» example: using IMAP list ✨

  my $imap  = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
  local $"  = ';';

  my @lines = $imap->list('', '');  # returns the default delimiter
  print ">@{$lines[0]}<";           #  >(\Noselect);/;<

  my @lines = $imap->list('#news',''); # specific delimiter
  print ">@{$lines[0]}<";           #  >(\Noselect);.;<

  my @lines = $imap->list('top/x/', '%');
  print ">@$_<," foreach @lines;    #  >();/;/tmp/x/y<,>(\Marked);/;/tmp/x/z<

---

🔍 DETAILS 🔍

See 👇

• RFC2060: "Internet Message Access Protocol IMAP4v1" — sections 6.3.8 (LIST question) and 7.2.2 (LIST answer). go read the source, bestie, it's giving homework but the good kind. 📚

---

🌈 SEE ALSO 🌈

This module is part of Mail-Box-IMAP4 version 4.01, built on December 13, 2025. Website: http://perl.overmeer.net/CPAN/ — go say hi to the perl.overmeer.net girlies 🫶

---

👑 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. slay, legally speaking. 💜

---

okay and that's the whole page!! this one shipped as perl v5.40.1, dated 2026-01-21, and it's filed under Mail::...4::List(3pm) — thanks for coming to my ted talk, mwah 💋✨🎀