Catching up after a Gmail history gap
Gmail sync reads changes since a stored history point rather than re-listing the mailbox. When Gmail can no longer serve from that point, the incremental request is refused and Connect falls back to listing recent messages directly. Everything re-fetched is matched against what is already held, so a catch-up closes the gap without duplicating a thread, and the stored point only moves once the messages behind it are recorded.
What a gap is#
Incremental Gmail sync works from a history point: a marker meaning *everything up to here is already read*. Each pass asks Gmail for what changed after it. This is cheap and precise, and it depends on Gmail still holding the history that far back — which it does not do indefinitely.
A gap is that refusal. It is not an error in the mailbox and not a sign of lost mail: it means the marker is older than what the provider will replay. The usual reasons are a mailbox that has been quiet for a long stretch, a workspace that was switched off, or a mailbox whose work was held long enough for its marker to age out.
The flow, stage by stage#
- Trigger — a sync pass runs for a Gmail mailbox on the usual schedule.
- External event — Gmail refuses the incremental request because the stored history point is no longer serviceable.
- Authentication and workspace resolution — the mailbox's workspace is entered first; the refusal is handled inside it, never against a global list.
- Ingest — Connect stops asking for changes and lists recent messages instead, bounded rather than unbounded.
- Canonical record — each message is matched on the identifiers it carries; anything already held updates in place, and only genuinely new mail becomes a new canonical message.
- Classification and reasoning — new mail is triaged as it always is; re-seen mail is not re-triaged, and no draft is written a second time.
- Knowledge, memory and rules — unchanged. A catch-up is a read, and reading does not rewrite what Connect knows.
- Autonomy and approval — unchanged. Nothing is sent by a catch-up.
- Action through a provider — reads only: a list, then the messages the list named.
- Result — a fresh history point is stored, and only after the messages behind it are recorded.
- Relationship, timeline and memory — new messages attach to their people and appear on the timeline in the order the conversation happened.
- Audit, usage and Needs You — processed mail counts against the daily allowance; a gap wide enough to exhaust it holds the remainder rather than skipping it.
The two guarantees that make it safe#
| Guarantee | What it prevents | How it holds |
|---|---|---|
| Order | A thread assembled backwards, with the answer above the question | Messages are processed oldest first, so a conversation is built in the order it happened |
| Identity | The same conversation appearing twice | Re-fetched mail is matched on the identifiers the message itself carries, and updates the record already held |
| Cursor discipline | Silently skipping mail that was never read | The new history point is stored after the messages are recorded, never before |
| Allowance behaviour | A large gap quietly eating a day's mail | When the allowance is spent the remaining work is held, and the read point does not move past it |
The fourth row is the one that costs a mail agent its credibility when it is missing. Advancing a read point on a refusal marks work as done that was never done, and the messages behind it are never asked for again. Holding instead is visible, recoverable and slow; skipping is invisible and permanent.
What you see while it runs#
- A burst of conversations appearing at once, dated when they were actually received rather than when they were read.
- Replies drafted only for mail that still needs one — a message answered by a person during the outage does not get a second answer.
- A Needs You entry if the allowance runs out mid-catch-up, naming the refusal rather than reporting a sync failure.
- No change at all in Gmail: a catch-up reads, and read marks and labels belong to a different step that runs beside a reply.
The recipients notice nothing. Nothing is sent by the catch-up itself, so a wide gap does not produce a wave of belated replies to conversations that have moved on — each thread is judged on its current state, including any message a person sent by hand while the mailbox was behind.
When to intervene#
- Gaps keep recurring on one mailbox
- The mailbox is either being held by the allowance every day or is not being synced as often as its volume needs. Read the mailbox's health rather than reconnecting it.
- Very old mail did not come back
- The fallback listing is bounded. It closes the gap for recent mail; it is not an archive import, and it is not meant to be.
- A conversation now appears twice
- That is an identity failure rather than a gap failure, and it has its own page: The same conversation appears twice.
- Nothing arrived at all
- A gap is not the likely cause. Start at Mail is in the provider but not in Connect.
Questions#
Does a history gap mean messages were lost?
No. The gap is in the provider's change log, not in the mailbox. The messages are still there, and the fallback listing is how Connect reaches them without the change log's help.
Will a catch-up re-answer conversations somebody already handled?
No. Re-fetched mail is recognised as mail already held, and each thread is judged on its current state — including a reply a person sent by hand while the mailbox was behind.
Why does the catch-up sometimes stop halfway?
The daily allowance bounds how much mail is processed. When it is reached the remaining messages are held rather than dropped, the read point stays where it is, and work continues when the allowance resets.