imap_uid — Funktion · PHP-Referenz

Signatur

imap_uid(IMAP\Connection $imap, int $message_num): int|false

Beschreibung

imap_uid() konvertiert eine sequenzielle Nachrichtennummer (Message Sequence Number, MSN) in die zugehörige eindeutige Nachrichtenkennung (UID). Während Nachrichtennummern sich bei Aktionen wie dem Löschen oder Verschieben von Nachrichten ändern können, bleibt die UID einer Nachricht innerhalb eines Postfachs dauerhaft stabil.

Die Funktion ist besonders wichtig, wenn Nachrichten über mehrere Verbindungs-Sitzungen hinweg zuverlässig referenziert werden müssen. UIDs eignen sich daher für das Speichern von Referenzen in einer Datenbank oder für die Synchronisation von E-Mail-Clients. Für UID-basierte Operationen können dann Funktionen wie imap_fetch_overview() oder imap_fetchbody() mit dem Flag FT_UID genutzt werden.

Die inverse Operation – eine UID in eine sequenzielle Nachrichtennummer umzuwandeln – bietet die Funktion imap_msgno().

Parameter

Name	Typ	Default	Beschreibung
$imap Pflicht	IMAP\Connection		Eine aktive IMAP-Verbindungsinstanz, wie sie von `imap_open()` zurückgegeben wird.
$message_num Pflicht	int		Die sequenzielle Nachrichtennummer (beginnend bei `1`), deren UID ermittelt werden soll.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die UID der Nachricht als int zurück. Im Fehlerfall (z. B. wenn die Nachrichtennummer ungültig ist oder die Verbindung fehlgeschlagen ist) wird false zurückgegeben.

Beispiele

UID einer Nachricht ermitteln und für spätere Referenz speichern

<?php
// IMAP-Verbindung öffnen
$imap = imap_open('{mail.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheim');

if ($imap === false) {
    die('Verbindung fehlgeschlagen: ' . imap_last_error());
}

// Anzahl der Nachrichten im Postfach ermitteln
$msgCount = imap_num_msg($imap);

echo "Nachrichten im Postfach: $msgCount" . PHP_EOL;

// UID der ersten Nachricht abrufen
if ($msgCount > 0) {
    $uid = imap_uid($imap, 1);
    if ($uid !== false) {
        echo "UID der ersten Nachricht: $uid" . PHP_EOL;
        // UID könnte nun in einer Datenbank gespeichert werden
    } else {
        echo 'UID konnte nicht ermittelt werden.' . PHP_EOL;
    }
}

imap_close($imap);

Nachrichten im Postfach: 5 UID der ersten Nachricht: 1042

Alle UIDs im Postfach auflisten und Nachrichtennummern zuordnen

<?php
$imap = imap_open('{mail.example.com:993/imap/ssl}INBOX', 'user@example.com', 'geheim');

if ($imap === false) {
    die('Verbindung fehlgeschlagen: ' . imap_last_error());
}

$msgCount = imap_num_msg($imap);
$uidMap = [];

for ($i = 1; $i <= $msgCount; $i++) {
    $uid = imap_uid($imap, $i);
    if ($uid !== false) {
        $uidMap[$i] = $uid;
        echo "Nachrichtennummer $i => UID $uid" . PHP_EOL;
    }
}

// Nachrichteninhalt über UID abrufen (mit FT_UID-Flag)
if (!empty($uidMap)) {
    $firstUid = reset($uidMap);
    $header = imap_fetchheader($imap, $firstUid, FT_UID);
    echo PHP_EOL . "Header der ersten Nachricht (UID $firstUid):" . PHP_EOL;
    echo substr($header, 0, 200) . '...' . PHP_EOL;
}

imap_close($imap);

Nachrichtennummer 1 => UID 1042 Nachrichtennummer 2 => UID 1043 Nachrichtennummer 3 => UID 1047 Header der ersten Nachricht (UID 1042): Return-Path: <sender@example.com> ...

// Wichtig · Fallstricke

Stabilität von UIDs: UIDs sind innerhalb eines Postfachs eindeutig und persistent – sie ändern sich nicht, solange das Postfach existiert. Sequenzielle Nachrichtennummern hingegen können sich bei jeder IMAP-Sitzung oder nach dem Löschen von Nachrichten verschieben. Für langfristige Referenzen (z. B. in Datenbanken) sollten daher immer UIDs verwendet werden.

Hinweis zur Erweiterung: Ab PHP 8.1 ist der Typ des ersten Parameters IMAP\Connection (statt der früher verwendeten resource). Älterer Code, der eine resource übergibt, muss entsprechend angepasst werden.

Erweiterung aktivieren: Die IMAP-Funktionen erfordern, dass die PHP-IMAP-Erweiterung (php-imap) installiert und aktiviert ist.

Siehe auch

imap_msgno imap_open imap_num_msg imap_fetchheader imap_fetch_overview imap_fetchbody