Mailbox health
"Connected" says a credential was accepted. Health says what the mailbox has actually been doing — whether mail arrived, whether sends were acknowledged, whether work was refused. The verdicts on a mailbox row are derived from those events rather than from its configuration, which is why a row can read connected and unhealthy at the same time without either being wrong.
The distinction that makes the page necessary#
Connection is a claim about credentials at one instant. Health is a claim about behaviour over a period. Treating the first as the second is the commonest way a mail integration fails silently: everything on the screen is green, and nothing has moved for four days.
So the verdicts are derived from what happened rather than from what is configured. A mailbox that has never completed a fetch is not the same as one fetching normally, and neither is the same as one whose sends are failing while its reads are fine. Configuration cannot tell those apart; only the record of attempts can.
This is the same principle that governs sending. A message is reported as sent only when the provider has acknowledged it, and there is a third state — uncertain — shown as uncertain rather than guessed either way, because re-sending on a maybe is how a customer receives the same reply twice. Health and send evidence are two applications of one rule: report what is known, and name what is not.
Reading the row#
| Situation | What it means | What to do |
|---|---|---|
| Connected, no pass has ever completed | The credential was accepted; nothing has been proved beyond that | Wait for the first sync, then judge — Syncing an inbox |
| Fetching, nothing new arriving | A quiet mailbox: a signal, not an error | Confirm mail is actually arriving at the address — A quiet mailbox |
| Authentication failing | The grant was revoked, a password changed, or a provider security event invalidated the token | Reconnect through the same path; history is untouched |
| Reads fine, sends failing | The outgoing half is broken independently of the incoming one | On IMAP/SMTP check the outgoing half separately; on an API provider check the send permission |
| Work refused by the allowance | Metering, not a fault — the plan's daily allowance is spent | Nothing is lost; the cursor did not advance. The daily email allowance |
| The row is not on the screen at all | Possibly an empty workspace_id: invisible rather than missing | Do not reconnect first — see Mailboxes |
Where health surfaces#
The mailbox row is where you go looking. Needs You is where health comes to you: it is the ranked queue of decisions, approvals and operational problems for a person, and an operational problem on a mailbox belongs in it exactly as a held draft does. Entries drain by themselves as their cause clears, so the queue is a picture of what is wrong now rather than a log of what was ever wrong.
That draining behaviour is worth knowing before you start clearing things by hand. A verdict that disappeared after you fixed the credential was not dismissed; it stopped being true.
Judging a mailbox honestly#
- Ask what the mailbox has done, not what it is configured to do.
- Separate the incoming half from the outgoing half — they fail independently, and on IMAP/SMTP they are separate servers.
- Distinguish a refusal from a failure. Refused work is held and resumes; failed work needs an action from you.
- Distinguish empty from broken. A mailbox that authenticates and returns nothing is quiet, and quiet is frequently correct.
- Prove a fix by an event, not by a form. One message in and one message out, acknowledged, is the whole test.
Why 'connected' is not enough to prove mailbox health is the longer argument, including why a health check that only pings the provider will pass on a mailbox nobody is being answered from.
Questions#
Can a mailbox be connected and unhealthy at once?
Yes, and it is the case worth designing for. Credentials being valid says nothing about whether mail is arriving, whether sends are acknowledged, or whether the allowance is refusing work. All three are visible on the row.
Does a health problem stop Connect answering customers?
It depends which half is affected. A broken incoming connection means nothing new to answer; a broken outgoing one means replies are written and cannot leave; a write-back failure means neither, because write-back never blocks a reply.
Do I have to clear health items myself?
No. Needs You entries drain as their cause clears. If one persists after you believe you have fixed the cause, the cause is probably still true — check the other half of the connection.