IMAP UID and cursor lifecycle
An IMAP mailbox has no change log, so Connect resumes from a UID — the position in the folder up to which everything has been dealt with. It advances only for work that was actually processed. A refusal, a failure or a partial pass leaves it where it was, which means the same messages are offered again rather than skipped.
What the cursor claims#
A cursor is not a bookmark saying "I read this far". It is a claim that everything up to that point has been canonicalised, triaged and accounted for. That distinction decides every rule on this page: a bookmark can be moved optimistically, a claim cannot.
IMAP gives each message in a folder a UID that is unique within that folder and increases over time, which makes "everything after N" a cheap question. What IMAP does not give is a log of changes, so unlike Gmail history sync there is nothing to ask about deletions, flags or moves in one call. The protocol itself is described in the technology reference.
The one outcome that advances it#
| Outcome | Cursor | Why |
|---|---|---|
| Messages fetched, bridged and accepted | Advances | The claim is now true up to the new UID |
| The daily allowance refused the batch | Stays | The work was not done; the mail waits at the server and Needs You shows the refusal |
| The connection dropped mid-pass | Stays | A partial pass proves nothing about the messages it did not reach |
| The bridge rejected a message | Stays at the last accepted UID | A canonical record was not produced, so the claim would be false |
| Nothing new above the cursor | Stays | A quiet mailbox: correct and uneventful |
The cost of this discipline is duplication of effort — a message may be fetched more than once if a pass keeps failing after it. The cost of the alternative is a customer who was never answered and no record that they were ever seen. How a mail cursor loses messages, and how to stop it works through why the second cost is not comparable to the first.
When a UID stops meaning anything#
- The folder's validity marker changed
- IMAP servers publish a validity value alongside UIDs; when it changes, previously recorded UIDs no longer refer to the same messages. A cursor from before the change cannot be trusted against the folder after it.
- The mailbox was recreated or migrated
- A restore, a migration between servers, or a rebuilt folder can renumber everything. The mailbox is then in the position of one that has never been read.
- The folder being read changed
- A cursor belongs to a folder. Pointing the connection at a different one is a different sequence of UIDs, not a continuation of the old one.
- The mailbox was reconnected
- A new connection establishes a new position rather than inheriting the old one, in the same way a first pass does.
None of these deletes anything in the workspace. Canonical threads, messages and contacts already produced are unaffected — they were copied across the bridge and belong to the workspace, not to the folder they came from.
Diagnosing a stuck cursor#
Check whether the mailbox is refusing or failing. They look identical from the Conversations screen and are different problems.
Result A refusal appears in Needs You with its reason; a failure appears as a health verdict on the mailbox row.
If it is a refusal, look at the allowance rather than the mailbox.
Result Nothing is wrong with the connection. The work resumes when the allowance does — The daily email allowance.
If it is a failure, test the incoming half on its own.
Result IMAP and SMTP fail independently, and a mailbox whose reads are stuck may be sending perfectly — Connecting an IMAP and SMTP server.
Only then consider reconnecting.
Result Reconnecting establishes a new position, which resolves a cursor that has genuinely become meaningless and does nothing at all for a mailbox that was simply refused.
Questions#
Will the same message be processed twice?
It can be fetched twice — that is the deliberate cost of never advancing on a refusal. What protects you downstream is that canonicalisation and the send boundary are the same for both attempts, so a repeat fetch does not become a repeated reply.
Can I move the cursor by hand?
It is not a user-facing setting, and that is intentional: every manual position change is either a no-op or an assertion that unprocessed mail was processed. Reconnecting is the supported way to establish a new position.
Does the cursor track deletions or read flags on the server?
A UID cursor answers "what is new above this point". Changes to older messages are not something a plain UID position describes, which is one of the concrete differences between IMAP and Gmail's history mechanism.