---
name: "Mail::Server::IMAP4::List"
section: "3pm"
platform: "linux"
package: "libmail-box-imap4-perl"
version: "3.009-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Mail::Server::IMAP4::List"
---

# Mail::Server::IMAP4::List(3pm)

folder related IMAP4 answers

## 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

## METHODS

### Constructors

- Mail::Server::IMAP4::List-\>**new**($user)

  Create a (temporary) object to handle the LIST requests for a certain user, based upon a set of folders.  The data is kept by Mail::Box::Identity and Mail::Box::Collection objects, which mean that the folders will not be opened to answer these questions.

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

  - delimiter =\> STRING\|CODE

    Either the constant delimiter, or a code reference which will get passed a folder name and should return the delimiter string used in that name. If that folder name is empty, the default delimiter must be reported. See **delimiter()** for an example.

  - folders =\> OBJECT

    You need to specify either a set of folders explicitly or via the user. Some Mail::Box::Identity OBJECT is needed.

  - inbox =\> BOOLEAN

    For now, only used to see whether there is an inbox, so a truth value will do.  This may change in the future.  By default, the flag is set if `"$user-"`inbox\> is defined.

  - user =\> OBJECT

    A Mail::Box::Manage::User OBJECT, representing the user who's 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.

  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.

- $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.  The request must be partially decoded, the answer will need to be encoded.

  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)

## SEE ALSO

This module is part of Mail-Box-IMAP4 distribution version 3.009, built on April 18, 2025. Website: *http://perl.overmeer.net/CPAN/*

## LICENSE

Copyrights 2001-2025 by \[Mark Overmeer\]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See *http://dev.perl.org/licenses/*