Signatur
Beschreibung
imap_mail_move() verschiebt Nachrichten, die durch die Nachrichtennummern-Sequenz $message_nums angegeben werden, in das Ziel-Postfach $mailbox. Die Funktion kopiert die Nachrichten intern in das Ziel-Postfach und markiert die Originale im Quell-Postfach mit dem \\Deleted-Flag. Um den Vorgang abzuschließen und die markierten Nachrichten tatsächlich zu entfernen, muss anschließend imap_expunge() aufgerufen werden.
Die Nachrichtennummern in $message_nums können als einzelne Nummer ('1'), kommagetrennte Liste ('1,3,5') oder als Bereich ('1:5') übergeben werden. Standardmäßig werden dabei Sequenznummern verwendet; mit dem Flag CP_UID kann stattdessen mit UIDs gearbeitet werden, was stabiler ist, da UIDs sich beim Hinzufügen neuer Nachrichten nicht verschieben.
Diese Funktion ist nützlich, wenn Nachrichten in einem IMAP-Konto organisiert werden sollen, zum Beispiel beim automatischen Einsortieren von E-Mails in Ordner, beim Archivieren gelesener Nachrichten oder beim Bereinigen des Posteingangs. Sie ist Teil der IMAP-Erweiterung, die mit der PHP-Option --with-imap aktiviert werden muss.
Hinweis: Ab PHP 8.1.0 ist der erste Parameter vom Typ IMAP\Connection statt der zuvor verwendeten Ressource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $imap Pflicht | IMAP\Connection | Eine aktive IMAP-Verbindung, die zuvor mit imap_open() geöffnet wurde. |
|
| $message_nums Pflicht | string | Nachrichtennummern-Sequenz als String. Einzelne Nummer ('3'), kommagetrennte Liste ('1,3,7') oder Bereich ('1:10'). Wenn das Flag CP_UID gesetzt ist, werden UIDs erwartet. |
|
| $mailbox Pflicht | string | Name des Ziel-Postfachs (Ordners) auf dem IMAP-Server, z. B. 'INBOX.Archiv' oder 'Gelöscht'. Der Ordner muss auf dem Server existieren. |
|
| $flags | int | 0 | Optionale Flags. Mit CP_UID werden die Angaben in $message_nums als UIDs interpretiert statt als Sequenznummern. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. wenn das Ziel-Postfach nicht existiert oder die Verbindung unterbrochen ist).Beispiele
Einzelne Nachricht in Archiv-Ordner verschieben
<?php
// IMAP-Verbindung öffnen
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Nachricht mit Sequenznummer 3 in den Ordner 'Archiv' verschieben
$result = imap_mail_move($imap, '3', 'Archiv');
if ($result) {
// Zum Löschen markierte Nachrichten endgültig entfernen
imap_expunge($imap);
echo 'Nachricht erfolgreich verschoben.';
} else {
echo 'Fehler beim Verschieben: ' . imap_last_error();
}
imap_close($imap);Mehrere Nachrichten per UID in einen Unterordner verschieben
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheim');
if ($imap === false) {
die('Verbindung fehlgeschlagen: ' . imap_last_error());
}
// Alle Nachrichten suchen, die älter als 30 Tage sind
$dreissigTageAlt = date('d-M-Y', strtotime('-30 days'));
$uids = imap_search($imap, 'BEFORE ' . $dreissigTageAlt, SE_UID);
if ($uids) {
$uidListe = implode(',', $uids);
// Nachrichten per UID in 'INBOX.Alt' verschieben
if (imap_mail_move($imap, $uidListe, 'INBOX.Alt', CP_UID)) {
imap_expunge($imap);
echo count($uids) . ' alte Nachrichten archiviert.';
} else {
echo 'Fehler: ' . imap_last_error();
}
} else {
echo 'Keine alten Nachrichten gefunden.';
}
imap_close($imap);// Wichtig · Fallstricke
Expunge nicht vergessen: imap_mail_move() markiert die Quelldateien nur mit \\Deleted. Ohne nachfolgendes imap_expunge() oder imap_close($imap, CL_EXPUNGE) bleiben die Originale im Quell-Postfach sichtbar.
Ziel-Ordner muss existieren: Wenn der Zielordner auf dem Server nicht vorhanden ist, schlägt die Funktion fehl. Mit imap_createmailbox() kann ein fehlender Ordner vorab angelegt werden.
Sequenznummern vs. UIDs: Sequenznummern können sich ändern, wenn Nachrichten hinzugefügt oder gelöscht werden. Für robusteren Code empfiehlt sich die Verwendung von UIDs zusammen mit dem Flag CP_UID.
Erweiterung: Die IMAP-Erweiterung ist nicht standardmäßig aktiviert und muss beim Kompilieren von PHP oder über eine Distribution aktiviert werden. Für moderne Projekte kann imap_mail_move() durch spezialisierte Bibliotheken wie phpmailer/phpmailer oder ddeboer/imap ersetzt werden.