Signatur
Beschreibung
imap_clearflag_full() entfernt bestimmte IMAP-Nachrichten-Flags von einer Nachrichtensequenz. Typische Flags sind \\Seen (gelesen), \\Answered (beantwortet), \\Flagged (markiert), \\Deleted (zum Löschen vorgemerkt) und \\Draft (Entwurf). Das Gegenstück zum Setzen von Flags ist imap_setflag_full().
Die Nachrichtensequenz kann eine einzelne Nachrichtennummer (z. B. "1"), eine kommaseparierte Liste ("1,3,5") oder ein Bereich ("1:10") sein. Ob es sich dabei um Sequenznummern oder UIDs handelt, wird durch den Parameter options gesteuert.
Diese Funktion ist besonders nützlich, wenn Anwendungen Nachrichten programmatisch als ungelesen markieren, eine Löschmarkierung rückgängig machen oder andere Statusänderungen an E-Mails vornehmen sollen. Sie setzt direkt am IMAP-Protokoll an und funktioniert daher mit jedem IMAP-konformen Mailserver.
Seit PHP 8.1 ist der erste Parameter vom Typ IMAP\Connection (statt der früher verwendeten Ressource vom Typ resource).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindung, die zuvor mit imap_open() geöffnet wurde. |
|
| $sequence Pflicht | string | Die Nachrichtensequenz als Zeichenkette. Beispiele: "1" für eine einzelne Nachricht, "1,3,7" für mehrere oder "1:100" für einen Bereich. Bei gesetztem ST_UID-Flag werden UIDs statt Sequenznummern verwendet. |
|
| $flag Pflicht | string | Ein oder mehrere IMAP-Flags als Zeichenkette, getrennt durch Leerzeichen. Gültige Werte sind \\Seen, \\Answered, \\Flagged, \\Deleted und \\Draft. |
|
| $options | int | 0 | Optionale Bitmaske. Derzeit wird nur ST_UID unterstützt: Ist dieser Wert gesetzt, wird sequence als UID-Sequenz statt als Sequenznummern-Sequenz interpretiert. |
Rückgabewert
true zurück. Bei einem Fehler wird seit PHP 8.0 eine ValueError- oder RuntimeException ausgelöst.Beispiele
Nachricht als ungelesen markieren (\\Seen-Flag entfernen)
<?php
// Verbindung zum IMAP-Server herstellen
$imap = imap_open(
'{imap.example.com:993/imap/ssl}INBOX',
'benutzer@example.com',
'geheimesPasswort'
);
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Das \Seen-Flag der Nachricht Nr. 5 entfernen (ungelesen markieren)
imap_clearflag_full($imap, '5', '\\Seen');
echo "Nachricht 5 wurde als ungelesen markiert.\n";
imap_close($imap);
Löschmarkierung eines Nachrichtenbereichs rückgängig machen
<?php
$imap = imap_open(
'{imap.example.com:993/imap/ssl}INBOX',
'benutzer@example.com',
'geheimesPasswort'
);
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Das \Deleted-Flag für die Nachrichten 10 bis 20 entfernen
imap_clearflag_full($imap, '10:20', '\\Deleted');
echo "Löschmarkierung der Nachrichten 10–20 wurde entfernt.\n";
// Änderungen werden erst durch imap_expunge() dauerhaft gelöscht;
// da wir hier das Deleted-Flag entfernen, bleiben die Mails erhalten.
imap_close($imap);
// Wichtig · Fallstricke
Achtung: Das Entfernen des \\Deleted-Flags macht eine bereits durch imap_expunge() endgültig gelöschte Nachricht nicht wiederherstellbar. Das Flag muss vor dem Aufruf von imap_expunge() entfernt werden.
Die IMAP-Extension ist standardmäßig nicht in allen PHP-Builds enthalten und muss ggf. separat kompiliert oder installiert werden (--with-imap). Ab PHP 8.1 ist die frühere resource-basierte IMAP-Verbindung durch IMAP\Connection ersetzt worden; älterer Code kann Kompatibilitätsprobleme aufweisen.
Flag-Namen müssen exakt mit führendem doppelten Backslash angegeben werden (\\Seen), da in PHP-Strings ein einfacher Backslash als Escape-Zeichen gilt.