Signatur
Beschreibung
imap_list() fragt einen IMAP-Server nach allen verfügbaren Postfächern ab, die der Referenz und dem Suchmuster entsprechen. Die Funktion gibt ein Array mit vollständig qualifizierten Postfach-Namen zurück, die direkt für weitere IMAP-Operationen (z. B. imap_open()) genutzt werden können.
Der Parameter $reference entspricht dem Basis-Pfad auf dem Server, etwa {imap.example.com} bei Remote-Servern. Mit dem Parameter $pattern kann die Auswahl auf bestimmte Postfach-Muster eingeschränkt werden. Das Zeichen * steht dabei für beliebig viele Zeichen (rekursiv über alle Ebenen), während % nur innerhalb einer Ebene der Postfach-Hierarchie sucht.
Die Funktion eignet sich besonders dazu, dem Benutzer alle vorhandenen Ordner eines E-Mail-Kontos aufzulisten, etwa um einen Ordner-Baum in einer Webmail-Anwendung darzustellen oder automatisiert alle Unterordner eines Postfachs zu verarbeiten.
Hinweis: Ab PHP 8.1 wird der erste Parameter als IMAP\Connection-Objekt übergeben. In früheren PHP-Versionen war dies eine Ressource vom Typ resource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindung, die z. B. mit imap_open() geöffnet wurde. Ab PHP 8.1 ein IMAP\Connection-Objekt, zuvor ein resource. |
|
| $reference Pflicht | string | Der Basis-Pfad (Referenz) auf dem Server, z. B. {imap.example.com}. Gibt den Startpunkt für die Suche nach Postfächern an. |
|
| $pattern Pflicht | string | Suchmuster für Postfach-Namen. * sucht rekursiv über alle Hierarchie-Ebenen, % nur innerhalb einer Ebene. Zum Auflisten aller Postfächer kann * verwendet werden. |
Rückgabewert
{imap.example.com}INBOX). Bei einem Fehler wird false zurückgegeben.Beispiele
Alle Postfächer eines IMAP-Kontos auflisten
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}', 'user@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$postfaecher = imap_list($imap, '{imap.example.com}', '*');
if ($postfaecher === false) {
echo 'Keine Postfächer gefunden oder Fehler aufgetreten.';
} else {
echo 'Gefundene Postfächer:' . PHP_EOL;
foreach ($postfaecher as $postfach) {
echo ' ' . $postfach . PHP_EOL;
}
}
imap_close($imap);Nur Unterordner von INBOX mit % auflisten (eine Ebene)
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}', 'user@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Nur direkte Unterordner von INBOX (keine weiteren Unterebenen)
$unterordner = imap_list($imap, '{imap.example.com}', 'INBOX.%');
if ($unterordner !== false) {
echo 'Direkte Unterordner von INBOX:' . PHP_EOL;
foreach ($unterordner as $ordner) {
// Nur den Ordnernamen ohne Server-Präfix anzeigen
$name = str_replace('{imap.example.com}', '', $ordner);
echo ' ' . $name . PHP_EOL;
}
}
imap_close($imap);// Wichtig · Fallstricke
Sicherheitshinweis: Geben Sie Benutzeranmeldedaten oder den Inhalt des Rückgabewerts nicht ungefiltert an den Browser aus, da Postfach-Namen sensible Informationen enthalten können. Verwenden Sie htmlspecialchars(), wenn Postfach-Namen in HTML-Seiten ausgegeben werden sollen.
Das Muster * kann bei sehr großen Postfach-Strukturen zu langen Antwortzeiten führen. In solchen Fällen empfiehlt sich %, um die Suche auf eine Hierarchie-Ebene zu beschränken.
Die Funktion ähnelt imap_getmailboxes(), gibt jedoch nur einfache Strings statt Objekte mit zusätzlichen Attributen (z. B. Trennzeichen, Attribute) zurück. Für detailliertere Informationen sollte imap_getmailboxes() bevorzugt werden.
Ab PHP 8.1 ist die IMAP-Erweiterung nicht mehr standardmäßig enthalten und muss separat über PECL installiert werden (pecl install imap).