docs: fix nil-sender HTTP 503 documentation for EmailVerification and PasswordReset handlers

[github-actions]

What

Corrects factually wrong documentation about the behavior of EmailVerificationHandler and PasswordResetHandler when their sender function fields are nil, and adds missing HTTP 503 status rows to all relevant status-code tables.

Why

Both README.md and the handler reference docs incorrectly stated that when SendEmail / SendResetEmail is nil, tokens are still created and stored (just not delivered). This was described as "useful in tests". The actual implementation returns HTTP 503 immediately, before any database write, in both handlers — the same pattern already correctly documented for MagicLinkHandler.

This inaccuracy could lead integrators to:

• ship a misconfigured handler that silently accumulates unreachable tokens
• write tests that leave the field nil expecting no-op behavior, and then get surprising 503 errors in production

Changes

File	Change
docs/handler/email-verification.md	Add missing SendVerification | 503 Service Unavailable | SendEmail is nil row to HTTP status codes table
docs/handler/password-reset.md	Add !!! warning admonition about nil SendResetEmail (matching the style of email-verification.md and magic-links.md); add missing RequestReset | 503 Service Unavailable row to HTTP status codes table
README.md	Correct the nil-sender prose for both handlers; add 503 Service Unavailable rows to each handler's error-response table; update the SendVerification blanket-200 note to exclude the 503 case

Verification

Confirmed against source:

• handler/email_verification.go:66-69 — if h.SendEmail == nil { writeError(... StatusServiceUnavailable ...)
• handler/password_reset.go:73-76 — if h.SendResetEmail == nil { writeError(... StatusServiceUnavailable ...)

Both checks occur after request-body validation (400) but before any store call, consistent with the updated documentation.

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Update Docs · ● 2.4M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

This docs-only PR corrects factually wrong nil-sender behaviour for EmailVerificationHandler and PasswordResetHandler — both return HTTP 503 immediately (before any DB write) when the sender function is nil, not the previously documented no-op token-creation path. The README.md, email-verification.md, and password-reset.md all receive 503 rows in their status tables and updated prose, verified against the source implementations.

• The !!! info callout at the bottom of docs/handler/email-verification.md (line 67) still says "Only the missing-email validation check surfaces as a non-200 error," which now contradicts the 503 row added four lines above — this was flagged in a prior review and remains unaddressed.

Confidence Score: 4/5

Safe to merge after fixing the one remaining stale callout in email-verification.md.

One P1 finding: the !!! info callout in docs/handler/email-verification.md directly contradicts the new 503 row added in this same PR. All other changes are accurate and consistent with the source code.

docs/handler/email-verification.md — the closing info callout needs updating to include the 503 case.

Important Files Changed

Filename	Overview
docs/handler/email-verification.md	Adds 503 row to status table and corrects prose, but the closing !!! info callout (line 67) still incorrectly states that only the 400 case is a non-200 error.
docs/handler/password-reset.md	Adds !!! warning for nil SendResetEmail, qualifies the enumeration-prevention callout to exclude 400/429/503, and adds the 503 row to the status table — all consistent with the source code.
README.md	Corrects nil-sender prose for both handlers, adds 503 rows to both error-response tables, and qualifies the blanket-200 note for SendVerification — all verified against the source code.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[POST /verify-email/send or POST /password-reset/request] --> B{Rate limit exceeded?\nPasswordReset only}
    B -- Yes --> R429[429 Too Many Requests]
    B -- No --> C{Valid JSON &\nemail present?}
    C -- No --> R400[400 Bad Request]
    C -- Yes --> D{SendEmail /\nSendResetEmail == nil?}
    D -- Yes --> R503[503 Service Unavailable\nbefore any DB write]
    D -- No --> E[Store lookup & token creation]
    E --> F{Store error?}
    F -- Yes --> R500[500 Internal Server Error]
    F -- No --> G[Send email]
    G --> R200[200 OK\nalways — prevents enumeration]

Loading

Comments Outside Diff (4)

1. docs/handler/email-verification.md, line 39 (link)

   Stale prose contradicts the new 503 row

   This sentence still says "For all valid requests it returns HTTP 200 regardless of whether the address is registered," but a request with a valid email field when SendEmail is nil is structurally valid yet now documented (and actually) returns HTTP 503. The same inconsistency appears on line 59 (Always) and line 67 (Only the missing-email validation check surfaces as a non-200 error). All three need updating to match the 503 row that was just added to the status table.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/handler/email-verification.md
   Line: 39
   
   Comment:
   **Stale prose contradicts the new 503 row**
   
   This sentence still says "For all valid requests it returns HTTP 200 regardless of whether the address is registered," but a request with a valid `email` field when `SendEmail` is `nil` is structurally valid yet now documented (and actually) returns HTTP 503. The same inconsistency appears on line 59 (`Always`) and line 67 (`Only the missing-email validation check surfaces as a non-200 error`). All three need updating to match the 503 row that was just added to the status table.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

2. docs/handler/email-verification.md, line 67 (link)

   Info callout still incorrect after 503 addition

   "Only the missing-email validation check surfaces as a non-200 error" is now wrong — the nil-SendEmail 503 is also a non-200 error. This callout should at minimum say "the 400 and 503 cases" to stay consistent with the rest of the updated docs.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/handler/email-verification.md
   Line: 67
   
   Comment:
   **Info callout still incorrect after 503 addition**
   
   "Only the missing-`email` validation check surfaces as a non-200 error" is now wrong — the nil-`SendEmail` 503 is also a non-200 error. This callout should at minimum say "the 400 and 503 cases" to stay consistent with the rest of the updated docs.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

3. docs/handler/password-reset.md, line 46 (link)

   "Always returns HTTP 200" callout excludes the new 503 case

   The info callout says "RequestReset always returns HTTP 200 … regardless of whether the email is registered," but that is no longer true when SendResetEmail is nil. The same "always" qualifier appears in the status table row on line 62. Both need qualifying — the README.md equivalent was already corrected in this PR.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/handler/password-reset.md
   Line: 46
   
   Comment:
   **"Always returns HTTP 200" callout excludes the new 503 case**
   
   The info callout says "`RequestReset` always returns HTTP 200 … regardless of whether the email is registered," but that is no longer true when `SendResetEmail` is `nil`. The same "always" qualifier appears in the status table row on line 62. Both need qualifying — the `README.md` equivalent was already corrected in this PR.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

4. docs/handler/email-verification.md, line 67 (link)

   Info callout still omits the 503 case

   The !!! info callout says "Only the missing-email validation check surfaces as a non-200 error," but SendEmail == nil now also surfaces as a non-200 error (503). This directly contradicts the new 503 row added to the status table four lines above. The README.md and the updated prose on line 39 both already use "the 400 and 503 cases."

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/handler/email-verification.md
   Line: 67
   
   Comment:
   **Info callout still omits the 503 case**
   
   The `!!! info` callout says "Only the missing-`email` validation check surfaces as a non-200 error," but `SendEmail == nil` now also surfaces as a non-200 error (503). This directly contradicts the new 503 row added to the status table four lines above. The `README.md` and the updated prose on line 39 both already use "the `400` and `503` cases."
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/handler/email-verification.md
Line: 67

Comment:
**Info callout still omits the 503 case**

The `!!! info` callout says "Only the missing-`email` validation check surfaces as a non-200 error," but `SendEmail == nil` now also surfaces as a non-200 error (503). This directly contradicts the new 503 row added to the status table four lines above. The `README.md` and the updated prose on line 39 both already use "the `400` and `503` cases."

```suggestion
    `SendVerification` returns 200 for unregistered emails and already-verified addresses without storing a token or sending an email. Only the `400` (missing `email`) and `503` (nil `SendEmail`) checks surface as non-200 errors.
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (2): Last reviewed commit: "docs: correct 200 OK conditions to exclu..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR corrects documentation for EmailVerificationHandler and PasswordResetHandler to match the actual runtime behavior when their email-sender function fields are nil (immediate HTTP 503, no DB writes), and updates status-code tables accordingly.

Changes:

• Add missing 503 Service Unavailable rows to handler status-code tables where sender funcs can be nil.
• Update README prose and error-response tables to describe the 503 misconfiguration behavior (and adjust the blanket “always 200” note to exclude 503).
• Add a warning admonition to PasswordResetHandler docs recommending a no-op sender for tests.

Show a summary per file

File	Description
docs/handler/email-verification.md	Documents 503 when SendEmail is nil via status-code table update.
docs/handler/password-reset.md	Adds warning admonition for nil SendResetEmail and documents 503 in status-code table.
README.md	Fixes nil-sender behavior descriptions and adds 503 rows to error-response tables for both handlers.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 3/3 changed files
• Comments generated: 2