Signatur
Beschreibung
imap_search() durchsucht das aktuell geöffnete IMAP-Postfach anhand von RFC3501-kompatiblen Suchkriterien. Die Funktion gibt ein Array mit Nachrichten-Nummern oder Nachrichten-UIDs zurück, die auf die Kriterien passen. Dies ermöglicht es, gezielt nach bestimmten E-Mails zu filtern – zum Beispiel nach ungelesenen Nachrichten, E-Mails eines bestimmten Absenders oder Nachrichten in einem bestimmten Datumsbereich.
Der Parameter criteria ist eine Zeichenkette, die ein oder mehrere RFC3501-Suchschlüsselwörter enthält, getrennt durch Leerzeichen. Gängige Schlüsselwörter sind unter anderem: ALL (alle Nachrichten), UNSEEN (ungelesene Nachrichten), FROM "absender@example.com", SUBJECT "Betreff", SINCE "01-Jan-2024" oder FLAGGED (markierte Nachrichten). Mehrere Kriterien können kombiniert werden, z. B. UNSEEN FROM "chef@firma.de".
Mit dem Parameter flags lässt sich steuern, ob die Rückgabe aus sequenziellen Nachrichten-Nummern (SE_FREE, Standard) oder aus UID-Werten (SE_UID) besteht. UIDs sind stabiler, da sie sich beim Löschen anderer Nachrichten nicht verschieben. Der optionale Parameter charset gibt den Zeichensatz an, der bei der Suche verwendet werden soll (z. B. UTF-8).
Die Funktion ist besonders nützlich in E-Mail-Verwaltungsanwendungen, Newsletter-Systemen oder automatisierten Mailverarbeitungs-Scripts, wo nur relevante Nachrichten selektiert und anschließend z. B. mit imap_fetchbody() oder imap_header() weiterverarbeitet werden sollen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindungsinstanz, wie sie von imap_open() zurückgegeben wird. |
|
| $criteria Pflicht | string | Suchkriterien gemäß RFC3501 als Zeichenkette, z. B. "UNSEEN", "FROM \"name@example.com\"" oder "SUBJECT \"Rechnung\" SINCE \"01-Jan-2024\"". Mehrere Bedingungen werden durch Leerzeichen kombiniert (implizites AND). |
|
| $flags | int | SE_FREE | Steuert das Format der zurückgegebenen IDs. SE_FREE (Standard) liefert sequenzielle Nachrichten-Nummern, SE_UID liefert UIDs (stabiler bei Postfachoperationen). |
| $charset | string | "" | Der MIME-Zeichensatz, der bei der Suche verwendet wird, z. B. "UTF-8". Wird ein leerer String übergeben, verwendet der Server seinen Standardzeichensatz. |
Rückgabewert
SE_UID) zurück, die den Suchkriterien entsprechen. Wurden keine Nachrichten gefunden oder tritt ein Fehler auf, wird false zurückgegeben.Beispiele
Alle ungelesenen Nachrichten abrufen
<?php
$imap = imap_open('{mail.example.com:993/imap/ssl}INBOX', 'benutzer@example.com', 'geheimesPasswort');
if (!$imap) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$ungelesen = imap_search($imap, 'UNSEEN');
if ($ungelesen) {
echo 'Ungelesene Nachrichten: ' . count($ungelesen) . PHP_EOL;
foreach ($ungelesen as $msgNr) {
$header = imap_headerinfo($imap, $msgNr);
echo 'Von: ' . $header->fromaddress . ' | Betreff: ' . $header->subject . PHP_EOL;
}
} else {
echo 'Keine ungelesenen Nachrichten gefunden.';
}
imap_close($imap);Kombinierte Suche: Nachrichten eines Absenders seit einem Datum (mit UIDs)
<?php
$imap = imap_open('{mail.example.com:993/imap/ssl}INBOX', 'benutzer@example.com', 'geheimesPasswort');
if (!$imap) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// UIDs abrufen für stabilen Zugriff
$uids = imap_search($imap, 'FROM "rechnungen@lieferant.de" SINCE "01-Jan-2024"', SE_UID);
if ($uids) {
foreach ($uids as $uid) {
// Nachrichtentext per UID abrufen
$body = imap_fetchbody($imap, $uid, '1', FT_UID);
echo "UID $uid – Nachrichteninhalt (gekürzt): " . mb_substr($body, 0, 100) . PHP_EOL;
}
} else {
echo 'Keine passenden Nachrichten gefunden.';
}
imap_close($imap);// Wichtig · Fallstricke
Erweiterungsvoraussetzung: Die IMAP-Erweiterung muss in PHP aktiviert sein (ext-imap). Ab PHP 8.1 sind IMAP-Verbindungen Objekte vom Typ IMAP\Connection statt Ressourcen.
Sonderzeichen in Kriterien: Suchbegriffe wie Absender-Adressen oder Betreffzeilen müssen in doppelte Anführungszeichen eingeschlossen werden. Bei der Verwendung in PHP-Strings müssen diese entsprechend escapt werden (FROM "name" → 'FROM "name"' oder "FROM \"name\"").
Zeichensatz-Kompatibilität: Nicht alle IMAP-Server unterstützen den Parameter charset vollständig. Bei der Suche nach Nachrichten mit Umlauten oder anderen Nicht-ASCII-Zeichen sollte UTF-8 angegeben werden, jedoch kann das Verhalten je nach Mailserver variieren.
Große Postfächer: Bei sehr großen Postfächern kann imap_search() langsam sein. Es empfiehlt sich, die Suche durch Ordnerauswahl und möglichst enge Kriterien zu begrenzen. Die Verwendung von UIDs (SE_UID) ist für robuste Anwendungen zu bevorzugen, da sequenzielle Nummern sich nach dem Löschen von Nachrichten verschieben können.