Add apology opening to first-payment email (broken link recovery)

forgejo_admin commented

2026-04-14 01:14:48 +00:00

Owner

Type

Feature

Lineage

Follow-up to forgejo_admin/basketball-api#473 (the 409 fix). Parents who clicked the original April blast link got 409 errors and couldn't pay. We need to acknowledge that before re-sending.

Repo

forgejo_admin/basketball-api

User Story

As a parent
I want an acknowledgment that the previous payment link was broken
So that I trust the new link and understand why I'm getting a second email

Context

The April 11 first-payment blast went out with checkout links that failed (100% 409). Parents clicked, got errors, lost trust. Fix merged (#473) and deployed. Now we need to re-send the email with an apology opening.

Marcus (admin) proposed the exact wording via GroupMe. Adopt it verbatim, insert as a new opening paragraph above the existing template body. Keep everything else the same — same branded HTML, same fee display, same checkout URL.

Both HTML and plaintext versions must be updated.

File Targets

Files to modify:

src/basketball_api/services/email.py — send_first_payment_email() function. Add apology paragraph at the top of both body_html (inside the branded wrapper) and plain_body.

Files to NOT touch:

src/basketball_api/routes/checkout.py — already fixed
src/basketball_api/routes/admin.py — blast endpoint unchanged

Acceptance Criteria

HTML email renders with apology as the first paragraph (above "{player_name} is in...")
Plaintext email has apology as the first paragraph
Existing content (fee, checkout URL, footer) unchanged
Existing tests still pass
New test verifies apology text is present in both HTML and plaintext

Test Expectations

Update test_send_first_payment_email_180_fee or add test_send_first_payment_email_contains_apology — assert apology string in both html_body and body
Run: pytest tests/test_first_payment_email.py -v

Constraints

Use Marcus's exact wording (approved via GroupMe):

"Apologies for the issue with the monthly payment email — there was a bug on our end. This email will include your updated monthly payment link. Thank you for your understanding and patience."
Match existing style: same color, margin, font-size as existing opening paragraph in body_html
Do NOT change subject line
Do NOT change any fee math or URL construction

Checklist

PR opened
Tests pass
QA review passed
Lucas-approved test email shows correct rendering

westside-basketball — project this affects
forgejo_admin/basketball-api#473 — the underlying bug that triggered this need

### Type Feature ### Lineage Follow-up to `forgejo_admin/basketball-api#473` (the 409 fix). Parents who clicked the original April blast link got 409 errors and couldn't pay. We need to acknowledge that before re-sending. ### Repo `forgejo_admin/basketball-api` ### User Story As a parent I want an acknowledgment that the previous payment link was broken So that I trust the new link and understand why I'm getting a second email ### Context The April 11 first-payment blast went out with checkout links that failed (100% 409). Parents clicked, got errors, lost trust. Fix merged (#473) and deployed. Now we need to re-send the email with an apology opening. Marcus (admin) proposed the exact wording via GroupMe. Adopt it verbatim, insert as a new opening paragraph above the existing template body. Keep everything else the same — same branded HTML, same fee display, same checkout URL. Both HTML and plaintext versions must be updated. ### File Targets Files to modify: - `src/basketball_api/services/email.py` — `send_first_payment_email()` function. Add apology paragraph at the top of both `body_html` (inside the branded wrapper) and `plain_body`. Files to NOT touch: - `src/basketball_api/routes/checkout.py` — already fixed - `src/basketball_api/routes/admin.py` — blast endpoint unchanged ### Acceptance Criteria - [ ] HTML email renders with apology as the first paragraph (above "{player_name} is in...") - [ ] Plaintext email has apology as the first paragraph - [ ] Existing content (fee, checkout URL, footer) unchanged - [ ] Existing tests still pass - [ ] New test verifies apology text is present in both HTML and plaintext ### Test Expectations - [ ] Update `test_send_first_payment_email_180_fee` or add `test_send_first_payment_email_contains_apology` — assert apology string in both html_body and body - Run: `pytest tests/test_first_payment_email.py -v` ### Constraints - Use Marcus's exact wording (approved via GroupMe): > "Apologies for the issue with the monthly payment email — there was a bug on our end. This email will include your updated monthly payment link. Thank you for your understanding and patience." - Match existing style: same color, margin, font-size as existing opening paragraph in `body_html` - Do NOT change subject line - Do NOT change any fee math or URL construction ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] QA review passed - [ ] Lucas-approved test email shows correct rendering ### Related - `westside-basketball` — project this affects - `forgejo_admin/basketball-api#473` — the underlying bug that triggered this need

forgejo_admin commented

2026-04-14 01:16:39 +00:00

Author

Owner

Scope Review: READY

Review note: review-1005-2026-04-13

Tightly-scoped, agent-ready. Single function (send_first_payment_email at src/basketball_api/services/email.py:1021), Marcus-approved verbatim copy, 5 verifiable AC, existing test file at tests/test_first_payment_email.py with an anchor test (test_send_first_payment_email_180_fee at L116).

Traceability verified:

story:WS-S22 exists on project-westside-basketball (parent clear comms)
arch:basketball-api label present; arch-basketball-api note still missing in pal-e-docs — standing [SCOPE] recommendation (non-blocking, flagged across prior reviews)

No decomposition needed. Dispatch dev agent.

## Scope Review: READY Review note: `review-1005-2026-04-13` Tightly-scoped, agent-ready. Single function (`send_first_payment_email` at `src/basketball_api/services/email.py:1021`), Marcus-approved verbatim copy, 5 verifiable AC, existing test file at `tests/test_first_payment_email.py` with an anchor test (`test_send_first_payment_email_180_fee` at L116). Traceability verified: - story:WS-S22 exists on project-westside-basketball (parent clear comms) - arch:basketball-api label present; `arch-basketball-api` note still missing in pal-e-docs — standing [SCOPE] recommendation (non-blocking, flagged across prior reviews) No decomposition needed. Dispatch dev agent.