Signatur
Beschreibung
imap_status() fragt den IMAP-Server nach aktuellen Statusinformationen für ein angegebenes Postfach ab. Die Funktion ist besonders nützlich, um schnell zu prüfen, ob neue oder ungelesene Nachrichten vorhanden sind, ohne das Postfach vollständig zu öffnen (imap_open()).
Das zurückgegebene stdClass-Objekt kann je nach verwendeten Flags folgende Eigenschaften enthalten: messages (Gesamtzahl der Nachrichten), recent (neu seit letzter Verbindung), unseen (ungelesene Nachrichten), uidnext (nächste UID) und uidvalidity (Gültigkeit der UID-Sequenz). Welche Eigenschaften befüllt werden, hängt von den übergebenen Flags ab.
Die gewünschten Informationsfelder werden über bitweise OR-verknüpfte Konstanten wie SA_MESSAGES, SA_RECENT, SA_UNSEEN, SA_UIDNEXT, SA_UIDVALIDITY oder SA_ALL (alle zusammen) gesteuert.
Die Funktion eignet sich gut für regelmäßige Polling-Checks, z. B. in einem E-Mail-Benachrichtigungssystem, da sie deutlich weniger Overhead verursacht als das vollständige Öffnen eines Postfachs.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindungsinstanz, die zuvor mit imap_open() erstellt wurde. |
|
| $mailbox Pflicht | string | Der vollständige Postfachname im Format {imap.example.com}INBOX oder ein Unterordner wie {imap.example.com}INBOX.Sent. |
|
| $flags Pflicht | int | Bitmaske aus einer oder mehreren der folgenden Konstanten: SA_MESSAGES, SA_RECENT, SA_UNSEEN, SA_UIDNEXT, SA_UIDVALIDITY oder SA_ALL für alle Informationen. |
Rückgabewert
stdClass-Objekt mit den angeforderten Statusinformationen als Eigenschaften. Im Fehlerfall (z. B. Postfach nicht vorhanden) wird false zurückgegeben.Beispiele
Anzahl ungelesener Nachrichten im INBOX prüfen
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheimesPasswort');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$status = imap_status($imap, '{imap.example.com:993/imap/ssl}INBOX', SA_UNSEEN | SA_MESSAGES);
if ($status !== false) {
echo 'Gesamtnachrichten: ' . $status->messages . PHP_EOL;
echo 'Ungelesen: ' . $status->unseen . PHP_EOL;
} else {
echo 'Statusabfrage fehlgeschlagen.';
}
imap_close($imap);Alle Statusinformationen eines Unterordners abrufen
<?php
$server = '{imap.example.com:993/imap/ssl}';
$imap = imap_open($server . 'INBOX', 'user@example.com', 'geheimesPasswort');
if ($imap === false) {
die('Verbindung fehlgeschlagen.');
}
$mailbox = $server . 'INBOX.Archiv';
$status = imap_status($imap, $mailbox, SA_ALL);
if ($status !== false) {
echo 'Postfach: ' . $mailbox . PHP_EOL;
echo 'Nachrichten: ' . $status->messages . PHP_EOL;
echo 'Recent: ' . $status->recent . PHP_EOL;
echo 'Ungelesen: ' . $status->unseen . PHP_EOL;
echo 'UID Next: ' . $status->uidnext . PHP_EOL;
echo 'UID Validity:' . $status->uidvalidity . PHP_EOL;
} else {
echo 'Fehler: ' . imap_last_error();
}
imap_close($imap);// Wichtig · Fallstricke
Hinweis zur PHP-Version: Ab PHP 8.1.0 gibt imap_open() ein IMAP\Connection-Objekt zurück statt einer Ressource. Älterer Code, der auf eine Ressource prüft (is_resource()), muss entsprechend angepasst werden.
Sicherheit: Der Postfachname ($mailbox) sollte niemals direkt aus Benutzereingaben übernommen werden, da er Verbindungsparameter enthält und manipulierbare Optionen wie /norsh oder Serveradressen beinhalten kann. Immer serverseitig zusammenbauen und validieren.
Fehlerbehandlung: Gibt die Funktion false zurück, liefert imap_last_error() den letzten Fehlertext. Für alle aufgetretenen Fehler steht imap_errors() zur Verfügung.