Writing back to Gmail
When a reply leaves a Gmail mailbox, Connect labels the whole thread Connect by JBRH and removes its unread state, in one call, so people sharing that inbox can see it is handled without opening Connect. It runs after the send is committed and never raises: a thread that could not be labelled belongs to a customer who has still been answered.
The problem it solves#
Connect reads a mailbox, drafts, and replies. Before this, that is where it stopped, and the mailbox it had just worked showed no sign of it: the thread stayed unread, sat in the inbox looking untouched, and the business had to remember which conversations had already been answered. Two people working one inbox with no shared marks on it is how a customer gets answered twice, or not at all.
So the mark is made where the people are, not only where Connect is. The label shows in the Gmail sidebar, in search and on a phone, in the customer's own account. Both marks are ordinary Gmail state, both are reversible by the customer in one click, and neither deletes anything.
Exactly what is written#
The reply is sent and the outcome is committed.
Result The write-back has not started yet. Nothing about it can affect whether the message went.
Connect's label is found, or created the first time.
Result It is created with explicit list and message visibility so it behaves like a label the customer made themselves, rather than a hidden marker. Two clients creating it at once is answered by Gmail with a conflict, and the label then exists — which is all this wanted.
One modify call is made against the thread.
Result The label is added and the unread state removed. Modifying the thread rather than the message means the whole conversation carries the mark, not only the message Connect happened to reply to.
The result is logged either way.
Result Success or failure, with the reason. A write into somebody's mailbox has to be answerable afterwards.
- Never
- Trashes, deletes permanently, edits the content of a message, or touches a thread Connect did not answer.
- Only Gmail
- It is the one transport Connect holds a modify grant for. An IMAP or Microsoft mailbox is left exactly as it was.
- Switchable off
- A real per-workspace choice. A settings read that fails does not block the mark; it is treated as on.
Why the permission is what it is#
Labelling and read state are writes to the mailbox, so a read-only grant cannot perform them by definition. A send-only grant covers the reply and nothing else — it cannot label the thread it just replied to. A labels-only grant could label but could neither read the thread nor send the reply, so it would have to be a *third* scope stacked on the other two.
The modify scope is the single grant that covers reading, sending and this write-back, and unlike full mailbox access it cannot delete anything permanently — which is exactly the boundary this feature wants. The per-scope reasoning is set out in Gmail OAuth scopes and why each is asked for.
When it fails#
Failure here is never allowed to matter, and that is a design decision rather than an oversight. The reply has already gone; turning a labelling error into a raised exception would make a delivered message look like a failed one, which is the more expensive wrong answer by a wide margin. Every error is recorded and swallowed.
| Symptom | Likely cause | What to do |
|---|---|---|
| Gmail refused the update outright | The mailbox was connected without the permission Connect needs to label and mark threads. | Reconnect the mailbox — see Connecting Gmail. |
| Nothing was marked and the log says it was skipped | The mailbox is not a Gmail API one, or the write-back is switched off for the workspace. | Expected behaviour. An IMAP or Microsoft mailbox is never marked. |
| No Gmail thread identifier on the send result | The provider did not return one for that send. | The reply is unaffected; there is simply no thread to mark. |
| The reply is present but the thread is still unread | A transient error at Gmail. | The next reply on that thread marks it. Nothing needs repairing. |
In every one of those rows the customer has been answered. That is the test to apply when reading a write-back warning: it is a note about housekeeping in a mailbox, never evidence about delivery. Delivery evidence is a different record entirely — Proof that a message was sent.
Questions#
Can I use my own label name?
No. It is deliberately the product name, because a label called something like "Handled" is ambiguous in a shared inbox where several tools and several people are all handling things.
Does every send path mark the thread, or only the automatic ones?
Every path arrives at the same send boundary — a person pressing send, an approval in the queue, the engine replying on its own — so the mark is consistent whoever caused it.
Will it mark threads Connect only read?
No. The write-back happens on the send, so a thread nobody replied to is untouched. Syncing a mailbox also does not mark mail read at the provider.