IMAP UID vs. sequence number: use the right identifier in automation

Sequence numbers are positions in a changing view

IMAP message sequence numbers are convenient inside a session, but they can change when messages are expunged. If a worker stores “message 12” and an older message disappears, sequence 12 may now refer to a different item. That makes sequence numbers unsuitable as durable database keys for reply automation. They are best understood as current positions in the selected mailbox state, not identities that can safely survive reconnects, cleanup jobs, or other clients mutating the folder.

UIDs are the durable identifier within an epoch

IMAP UIDs are designed to remain stable for a message within a mailbox while the UIDVALIDITY value remains the same. Persist both UID and UIDVALIDITY. The pair gives your application a meaningful durable reference and tells it when a server has reset the UID namespace so previously stored UIDs cannot be assumed to identify the same messages. This is a better foundation for processed-state, reply deduplication, and deferred actions than storing sequence positions.

Treat UIDVALIDITY change as a reconciliation event

If the server reports a different UIDVALIDITY for a mailbox, do not continue applying old UID state blindly. Mark the prior mapping stale, rediscover messages using safe evidence such as Message-ID and recent timestamps where appropriate, and rebuild application state carefully. The exact recovery strategy depends on how much history the outbound system needs, but silent reuse of old UIDs is the dangerous choice. Log the epoch change prominently because it explains why previously durable identifiers must be reconsidered.

Use UID commands in workers that persist state

When your library exposes both sequence-based and UID-based methods, choose UID variants for jobs that may retry or run after other mailbox changes. A worker that discovers UID 4821 can later fetch or flag UID 4821 without relying on its current sequence number. Keep sequence numbers as transient metadata if useful for diagnostics, but never make them the key that cancels a prospect's follow-up or marks a reply processed in the database.

Message-ID is complementary, not a replacement for mailbox UID state

RFC message identifiers are valuable for threading and cross-message relationships, but real-world mail can contain malformed, missing, or duplicated Message-ID values. Keep them for reply correlation while still using the mailbox's UID/UIDVALIDITY pair for IMAP processing. The two identifiers answer different questions: UID locates the item in this mailbox epoch; Message-ID helps identify the message in mail semantics and across copies. Idempotent systems often store both.

Cleanup jobs are where sequence-number bugs become obvious

Imagine a poller records sequence 12, then a cleanup worker expunges messages 1 through 4. The original item may now have sequence 8. A delayed job acting on 12 can touch the wrong message. UID-based jobs avoid that class of error because expunging earlier messages does not reassign the stored UID within the same UIDVALIDITY epoch. Test this exact sequence in development: discover, delete an earlier item, then retry the stored job and verify it still targets the intended message.

Design database keys around mailbox identity too

UIDs are scoped to a mailbox, so `4821` in one account or folder is not the same object as `4821` in another. Include account/mailbox identity and UIDVALIDITY in the durable key. If messages move between folders, model the move as a state transition rather than assuming the UID remains globally meaningful. This explicit scoping prevents collisions when a small agency connects several mailboxes to the same reply-processing service.

Sequence numbers can change while the connection is alive

Message sequence numbers are positions in the currently selected mailbox view. When messages are expunged, later sequence numbers can shift. A worker that stores “message 42” and comes back after cleanup may now be pointing at a different message. RFC 9051 provides UIDs specifically for durable client state and requires their persistence to be detectable through UIDVALIDITY. Use sequence numbers only for short-lived interactions where the current mailbox view is authoritative; use UID commands for database-backed processing, retries and cross-job references. This distinction becomes critical when one process is detecting replies while another is archiving or deleting old messages in the same mailbox.

UIDVALIDITY is the epoch boundary for your cache

At mailbox selection time, record the server’s UIDVALIDITY value. If it differs from the value stored with your previous cache, stop treating old UIDs as valid references and reconcile. A robust worker can then rebuild its recent-message index using Message-ID, dates and other immutable content as supporting evidence while assigning the new mailbox UIDs. Do not silently continue because the numeric UIDs happen to overlap; the protocol explicitly uses UIDVALIDITY to tell clients when the mapping has changed. For a solo operator, this event may be rare, but handling it once prevents the worst kind of automation bug: updating campaign state from the wrong inbound message with no obvious crash.

Use UIDNEXT only as a hint that new mail may exist

RFC 9051 describes UIDNEXT as the predicted value that will be assigned to a new message; it is useful for noticing that messages may have arrived, but it is not a promise that a particular UID exists. A worker can cache UIDNEXT and quickly decide whether the mailbox probably changed, then issue a UID-based search or fetch to discover actual messages. Do not construct a message record simply because UIDNEXT increased by three. Messages can be added and expunged before the client checks. Treat UIDNEXT as an efficient change detector and the returned message UIDs as the authoritative processing set.

Log both identifiers while debugging live sessions

During development, it can be useful to log the current sequence number beside the UID so mailbox changes are easy to see. If message sequence 37 becomes 36 after another message is expunged while the UID remains unchanged, the log demonstrates why persistent state must use the UID. Remove noisy sequence-number logging later if needed, but keep UIDVALIDITY and UID in durable records. This simple diagnostic helps developers who are used to array indexes understand that an IMAP mailbox is a changing server view, not a static local list.

Field checklist

• Do not persist IMAP sequence numbers as durable message identity.
• Store mailbox identity + UIDVALIDITY + UID.
• Treat UIDVALIDITY changes as reconciliation events.
• Use UID-based fetch/store operations for retryable workers.
• Keep Message-ID for threading/correlation alongside IMAP identity.
• Test expunge/retry cases where sequence positions change.