Research: which IMAP and SMTP auth failures are permanent vs transient

[Hohnik]

Part of #18

Question

When a capability check fails, is the failure a settled fact or a momentary condition? The re-check policy depends on telling them apart.

Both were observed live against T-Online on the same credentials:

• 535 5.7.0 Authentication rejected / Authentication failed. — SMTP, permanent-looking 5xx
• 421 IP=... No more parallel connections from your address allowed — SMTP, transient 4xx rate limit

Establish from primary sources (RFC 5321 for SMTP reply codes, RFC 3501/9051 for IMAP responses, plus smtplib/imaplib exception surfaces):

• Which SMTP reply classes mean "these credentials will never work" vs "try again later"?
• What is the IMAP equivalent — NO vs BAD vs connection-level failures — and how does imaplib surface each?
• Do the Python stdlib exception types (SMTPAuthenticationError, SMTPConnectError, IMAP4.error, IMAP4.abort) preserve enough to classify reliably, or must reply codes be parsed?
• Is there a documented convention for how mail clients treat a 4xx during credential verification?

Output: a classification a re-check policy can be written against.

[Hohnik]

A /research subagent is running against this ticket.

• Branch: research/imap-smtp-failure-classification (throwaway — not merged, not pushed)
• Findings will land at: docs/research/imap-smtp-failure-classification.md
• Format follows the prior art in docs/research/t-online-imap-smtp-totp.md

Scope given to the agent: SMTP reply-code classification (RFC 5321 / RFC 4954, with 454 vs 535 called out specifically), the IMAP NO/BAD/connection-failure equivalent (RFC 3501 / RFC 9051), whether the smtplib / imaplib exception types preserve enough to classify without parsing reply codes, and any documented convention for treating a 4xx during verification rather than during submission.

Deliverable is a failure -> permanent/transient -> recommended-behaviour table that Decide when SMTP capability is re-checked can be written against, plus explicit flagging of anywhere the RFCs are ambiguous or real servers diverge.

This ticket stays open — the agent produces the research only; resolving it is a human session.

[Hohnik]

Research landed. Ticket stays open — resolving it is a human session.

• Branch: research/imap-smtp-failure-classification, commit e9446ae (local only, not pushed)
• File: docs/research/imap-smtp-failure-classification.md (502 lines)

Headline

The protocols give a clean two-way split; the Python stdlib gives a three-way one. A re-check policy needs permanent / transient / indeterminate, not a boolean.

Three findings that drive the policy

1. 5xx means "stop auto-retrying", not "the credentials are wrong." RFC 5321 §4.2.1 says even permanent conditions can be corrected — and this repo's own case proves it, since the same password authenticated over IMAP while SMTP returned 535. No reply code in either protocol means "this password is wrong", so any UI copy asserting that is an inference the protocol doesn't support. Bears directly on Decide how a degraded account appears on the accounts list.

2. smtplib.SMTP.login() destroys the classification. It tries every advertised mechanism and re-raises only the last failure — verified in both directions (454-then-535 reports as 535; 535-then-454 reports as 454). A 421 mid-AUTH usually closes the socket, so login() retries on a dead socket and yields a code-less SMTPServerDisconnected. Same server condition, different exception type, depending only on how many mechanisms were advertised. Recommendation: call SMTP.auth() directly for the capability check.

3. imaplib has no structured error surface. NO and BAD raise the identical IMAP4.error; the only discriminator is whether args[0] is bytes (NO) or str (BAD) — an undocumented implementation detail. RFC 5530 codes must be regexed out. IMAP4.abort subclasses error, so it must be caught first.

Ambiguities flagged

Eight, notably: enhanced status codes disagree with reply codes in the wild (T-Online sent 535 5.7.0 where RFC 4954 registers 5.7.8; Gmail uses 5.7.80) — don't classify on the enhanced code. Servers also use 5xx for rate limits and 4xx for durable states. And a 5xx auth failure is frequently a server-side policy state (Microsoft documents SMTP AUTH disabled tenant-wide, per-mailbox, or by security defaults) — the strongest external argument for this map's per-protocol model.

Convention for a 4xx during verification (Q4)

Not in the RFCs, but unambiguous in practice: 4xx auto-retry belongs to message submission, not credential verification. Thunderbird scopes its 4xx retry to _actionMAIL/_actionRCPT; the AUTH path has no such branch, and its account-setup verifier is one-shot that deliberately refuses to claim "wrong password" unless certain. RFC 5321 §4.5.4.1 also warns clients to take great care caching negative responses — and a stored smtp_ok = False is a cached negative response.

Codebase note for the implementer

accounts/service.py:58-59 f-strings the exception into AccountConnectionError, discarding both the exception type and smtp_code and keeping only str(error). Classification must happen in sync/smtp_client.py / sync/imap_client.py where the live exception still exists, then travel as structured data — which constrains Decide the shape of per-protocol capability state on Account.