Advancing an IMAP cursor safely
An IMAP mailbox is read from a cursor: the position past which mail has already been taken in. It moves only after the messages behind it exist as canonical records — never after they were merely fetched, and never at all when the daily allowance refuses the work. That refusal deliberately holds the cursor, because a cursor that moves past unprocessed mail never comes back for it.
What the cursor is, and what it is not#
IMAP identifies messages within a folder by a number that only rises. Connect stores the highest one it has finished with, and each pass asks the server for what sits above it. That is the whole mechanism, and its simplicity is why the rule about *when* it may move carries all the weight.
The number is meaningful only inside one folder on one server. It is not a message identifier you can carry anywhere else, not comparable between mailboxes, and not something to copy when a mailbox is reconnected. A cursor belongs to the mailbox that earned it.
The flow, stage by stage#
- Trigger — a sync pass runs for an IMAP mailbox.
- External event — the server reports which messages sit above the stored cursor.
- Authentication and workspace resolution — the mailbox's workspace is entered before any of its settings or rows are read.
- Ingest — messages are fetched oldest first, in ascending order, not newest first.
- Canonical record — each message is written into the canonical thread and message records the engine reads; the provider-shaped copy is not what anything downstream uses.
- Classification and reasoning — triage runs per message as it lands, so a thread is judged with its earlier messages already present.
- Knowledge, memory and rules — read, not written. A sync pass does not change what Connect knows.
- Autonomy and approval — checked when a reply is considered, not during ingest; ingest itself sends nothing.
- Action through a provider — reads only. Nothing is marked, moved or deleted on the server.
- Result — the cursor is set to the highest message actually recorded, which is not always the highest message seen.
- Relationship, timeline and memory — each new message attaches to its person and lands on the timeline in received order.
- Audit, usage and Needs You — processed mail is metered; a refusal is recorded as a decision and surfaced for a person.
When the cursor moves, and when it must not#
| Situation | Cursor | Why |
|---|---|---|
| A message is fetched and recorded canonically | Moves to that message | The work behind it is genuinely done |
| A message is fetched but the write fails | Stays below it | The next pass must see it again |
| The daily allowance is spent mid-pass | Stays where it is | Work is held rather than dropped; the refusal is shown in Needs You |
| The connection drops part-way | Stays at the last recorded message | A partial pass is a shorter pass, not a skipped one |
| A message cannot be turned into a canonical record | Stays below it | The obstruction is visible and is a person's decision, not something to step over |
| The mailbox is reconnected | Belongs to the mailbox row, not the session | A reconnection is not a reason to re-read or to skip |
What a held cursor looks like from the outside#
- New mail stops appearing in Conversations while the mailbox still reports as connected — connection is not health, and this is one of the cases that proves it.
- A Needs You entry names the refusal and its cause, rather than presenting a sync error the mailbox does not have.
- When the allowance resets, ingest resumes from exactly where it stopped and the backlog arrives in received order.
- Nothing is sent to make up for the delay: the queue is of unread mail, not of unsent replies.
A backlog that never drains is the signal worth acting on. Either the mailbox's daily volume is above what the workspace's allowance covers, or one message at the head of the queue cannot be recorded and is holding everything behind it. The two look identical for a day and diverge after that: an allowance backlog shrinks each morning, an obstruction does not.
Operating it#
Read the mailbox's health verdicts before anything else.
Result You separate a mailbox that cannot authenticate from one that is authenticating perfectly and being held.
Check whether the allowance is the cause, on the plan and usage screen.
Result An allowance hold needs no repair — it needs either patience until the reset or a larger allowance.
If the backlog does not shrink after a reset, escalate with the mailbox address and the day it stopped moving.
Result That is the shape of an obstruction rather than a limit, and it is diagnosed from the mailbox row rather than from the screen.
Do not disconnect and reconnect the mailbox as a first move.
Result You avoid disturbing a cursor that is doing its job, and avoid the duplicate-row problem that reconnecting can cause.
Questions#
Why is mail not arriving when the mailbox says it is connected?
Because connection and health are different questions. An authenticated mailbox whose cursor is held by the allowance behaves exactly like a working mailbox with nothing new in it. The Needs You entry naming the refusal is the distinguishing evidence.
Can I move the cursor forward to skip a stuck message?
There is no supported way to step over unprocessed mail, and the reason is that the cursor only rises: anything skipped is never asked for again. A message that cannot be recorded is treated as an obstruction to clear rather than a position to jump.
Does reconnecting the mailbox reset the cursor?
The cursor belongs to the mailbox row rather than to a session, so reconnecting the same row continues from the same place. Reconnecting is worth avoiding as a reflex anyway, because a mailbox row that scoped lists cannot see can be duplicated that way.