imap_getmailboxes — Funktion · PHP-Referenz

Signatur

imap_getmailboxes(IMAP\Connection $imap, string $reference, string $pattern): array|false

Beschreibung

imap_getmailboxes() durchsucht den IMAP-Server nach Postfächern (Mailboxen), die dem Suchmuster $pattern entsprechen, und gibt für jede gefundene Mailbox ein Objekt mit detaillierten Metadaten zurück. Im Unterschied zu imap_list(), das nur die Namen liefert, enthält das Ergebnis von imap_getmailboxes() zusätzlich die Attribute und das Trennzeichen der Hierarchieebenen.

Jedes Element des zurückgegebenen Arrays ist ein stdClass-Objekt mit den Eigenschaften name (vollständiger Postfachname), delimiter (Hierarchietrennzeichen, z. B. / oder .) und attributes (Bitmaske mit IMAP-Flags wie LATT_NOINFERIORS, LATT_NOSELECT, LATT_MARKED, LATT_UNMARKED).

Die Funktion ist besonders nützlich, wenn eine vollständige Ordnerstruktur eines Postfachs dargestellt werden soll – beispielsweise für einen Webmail-Client oder ein E-Mail-Verwaltungswerkzeug. Das Muster * findet alle Postfächer, während % nur die direkte Ebene ohne Unterordner liefert.

Seit PHP 8.1 erwartet der erste Parameter ein IMAP\Connection-Objekt statt einer Ressource. Die Funktion setzt die PHP IMAP-Erweiterung voraus, die häufig separat installiert bzw. aktiviert werden muss.

Parameter

Name	Typ	Beschreibung
$imap Pflicht	IMAP\Connection	Eine aktive IMAP-Verbindung, die zuvor mit `imap_open()` geöffnet wurde.
$reference Pflicht	string	Der Basis-Referenzpfad, von dem aus die Suche startet. Üblicherweise der Serverstring ohne Postfachname, z. B. `{imap.example.com}`.
$pattern Pflicht	string	Suchmuster für die Postfachnamen. `` sucht rekursiv alle Unterordner, `%` sucht nur die aktuelle Hierarchieebene. Kombinations-Pfade wie `INBOX.` sind ebenfalls möglich.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein Array von stdClass-Objekten zurück, von denen jedes die Eigenschaften name, delimiter und attributes enthält. 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}', 'benutzer@example.com', 'geheimesPasswort');

if ($imap === false) {
    die('Verbindung fehlgeschlagen: ' . imap_last_error());
}

$mailboxes = imap_getmailboxes($imap, '{imap.example.com:993/imap/ssl}', '*');

if ($mailboxes === false) {
    echo 'Keine Postfächer gefunden oder Fehler aufgetreten.';
} else {
    foreach ($mailboxes as $mailbox) {
        echo 'Name:       ' . $mailbox->name . PHP_EOL;
        echo 'Trennzeichen: ' . $mailbox->delimiter . PHP_EOL;
        echo 'Attribute:  ' . $mailbox->attributes . PHP_EOL;
        echo '---' . PHP_EOL;
    }
}

imap_close($imap);

Name: {imap.example.com:993/imap/ssl}INBOX Trennzeichen: / Attribute: 32 --- Name: {imap.example.com:993/imap/ssl}INBOX/Gesendet Trennzeichen: / Attribute: 32 ---

Ordnerhierarchie mit Attribut-Prüfung aufbauen

<?php
$server = '{imap.example.com:993/imap/ssl}';
$imap = imap_open($server, 'benutzer@example.com', 'geheimesPasswort');

$mailboxes = imap_getmailboxes($imap, $server, '*');

if (is_array($mailboxes)) {
    echo '<ul>' . PHP_EOL;
    foreach ($mailboxes as $mailbox) {
        // Prüfen, ob das Postfach nicht auswählbar ist (z. B. reine Containerordner)
        $noSelect = ($mailbox->attributes & LATT_NOSELECT) ? ' [nicht auswählbar]' : '';
        $noInferiors = ($mailbox->attributes & LATT_NOINFERIORS) ? ' [keine Unterordner]' : '';

        // Nur den letzten Teil des vollständigen Namens anzeigen
        $parts = explode($mailbox->delimiter, $mailbox->name);
        $shortName = htmlspecialchars(end($parts));

        echo "<li>{$shortName}{$noSelect}{$noInferiors}</li>" . PHP_EOL;
    }
    echo '</ul>' . PHP_EOL;
}

imap_close($imap);

<ul> <li>INBOX</li> <li>Gesendet [keine Unterordner]</li> <li>Papierkorb</li> </ul>

// Wichtig · Fallstricke

Sicherheitshinweis: Postfachnamen, die aus Benutzereingaben stammen und im $pattern-Parameter verwendet werden, sollten niemals ungefiltert übergeben werden, da ein Angreifer durch Wildcard-Muster ungewollte Postfachstrukturen auslesen könnte.

Deprecation: Seit PHP 8.1 ist der ursprüngliche Ressource-Typ für IMAP-Verbindungen durch IMAP\Connection-Objekte ersetzt worden. Die IMAP-Erweiterung selbst wurde in PHP 8.4 als eigenständiges PECL-Paket ausgelagert (pecl/imap) und ist nicht mehr standardmäßig im PHP-Core enthalten.

Das name-Attribut jedes zurückgegebenen Objekts enthält den vollständigen Postfachnamen inklusive Serverstring (z. B. {imap.example.com:993/imap/ssl}INBOX). Dieser vollständige Name kann direkt an imap_open() oder imap_reopen() übergeben werden.

Siehe auch

imap_open imap_list imap_lsub imap_getsubscribed imap_close