Signatur
Beschreibung
imap_setflag_full setzt die angegebenen Flags (z. B. \Seen, \Flagged, \Deleted) für eine Gruppe von Nachrichten, die über eine Sequenzangabe identifiziert werden. Die Sequenz kann einzelne Nachrichtennummern, Bereiche (z. B. 1:10) oder kommagetrennte Listen sein.
Die Flags entsprechen dem IMAP-Standard (RFC 3501) und steuern den Status einer Nachricht im Postfach. Typische Anwendungsfälle sind das Markieren von Nachrichten als gelesen (\Seen), als zu löschende (\Deleted) oder als wichtig (\Flagged). Mehrere Flags können als leerzeichen-getrennte Zeichenkette übergeben werden.
Über den Parameter $options kann gesteuert werden, ob die Sequenz als UID-Sequenz (mit ST_UID) oder als klassische Nachrichtensequenznummer interpretiert wird. Um gesetzte Flags wieder zu entfernen, steht die Gegenfunktion imap_clearflag_full zur Verfügung.
Zu beachten ist, dass das Setzen des Flags \Deleted eine Nachricht nur als zu löschend markiert – zum endgültigen Löschen muss anschließend imap_expunge aufgerufen werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine IMAP-Verbindungsinstanz, die zuvor mit imap_open geöffnet wurde. |
|
| $sequence Pflicht | string | Eine Nachrichtensequenz, z. B. "1", "1:5" oder "1,3,5". Bei Verwendung von ST_UID als Option werden UIDs statt Sequenznummern verwendet. |
|
| $flag Pflicht | string | Ein oder mehrere IMAP-Flags, leerzeichen-getrennt. Gültige Werte sind \Seen, \Answered, \Flagged, \Deleted und \Draft. |
|
| $options | int | 0 | Optionales Bitfeld. ST_UID bewirkt, dass $sequence als UID-Sequenz statt als Nachrichtensequenznummer interpretiert wird. |
Rückgabewert
true zurück. Bei einem Fehler wird seit PHP 8.0 eine ValueError-Exception geworfen.Beispiele
Nachrichten als gelesen markieren
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'benutzer@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Nachrichten 1 bis 5 als gelesen markieren
imap_setflag_full($imap, '1:5', '\\Seen');
echo 'Nachrichten 1-5 wurden als gelesen markiert.' . PHP_EOL;
imap_close($imap);
?>Nachricht per UID als wichtig markieren und zum Löschen vormerken
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'benutzer@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
$uid = 1042; // Bekannte UID der Nachricht
// Als wichtig markieren (Flagged) mittels UID
imap_setflag_full($imap, (string)$uid, '\\Flagged', ST_UID);
echo 'Nachricht als wichtig markiert.' . PHP_EOL;
// Nachricht zum Löschen vormerken
imap_setflag_full($imap, (string)$uid, '\\Deleted', ST_UID);
echo 'Nachricht zum Löschen vorgemerkt.' . PHP_EOL;
// Gelöschte Nachrichten endgültig entfernen
imap_expunge($imap);
echo 'Postfach bereinigt.' . PHP_EOL;
imap_close($imap);
?>// Wichtig · Fallstricke
Backslash-Escaping: IMAP-Flags beginnen mit einem Backslash (z. B. \Seen). Da der Backslash in PHP-Strings ein Sonderzeichen ist, muss er im Quellcode verdoppelt werden: '\\Seen'.
Löschen erfordert Expunge: Das Setzen des Flags \Deleted löscht eine Nachricht nicht sofort. Es ist zwingend erforderlich, danach imap_expunge aufzurufen oder die Verbindung mit dem Flag CL_EXPUNGE zu schließen.
Erweiterung: Die IMAP-Erweiterung ist ab PHP 8.4 als PECL-Paket ausgelagert und muss separat installiert werden. In älteren PHP-Versionen ist sie Teil des Core-Distributions.
Serverkompatibilität: Nicht alle IMAP-Server unterstützen benutzerdefinierte Flags (Keywords). Die Standard-System-Flags gemäß RFC 3501 werden jedoch von allen kompatiblen Servern unterstützt.