## Summary
- Add automated email notification system for job completion and action
reminders
- Admin UI buttons to copy completion message or send email directly
- Comprehensive test suite (81 new tests)
- **Email subjects include release ID and song info** for easy
identification
## Changes
### Backend
- **Email Service** (`email_service.py`): Extended with SendGrid CC
support, `send_job_completion()` and `send_action_reminder()` methods
- **Job Notification Service** (`job_notification_service.py`): New
service orchestrating completion emails and action reminder scheduling
- **Template Service** (`template_service.py`): GCS-backed HTML email
templates with fallback defaults
- **Worker Service** (`worker_service.py`): Cloud Tasks integration for
delayed idle reminders (5-min delay)
- **Job Manager** (`job_manager.py`): State transition triggers for
automated notifications
- **Admin Routes** (`admin.py`): New endpoints `GET
/api/admin/jobs/{id}/completion-message` and `POST
/api/admin/jobs/{id}/send-completion-email`
- **Internal Routes** (`internal.py`): Idle reminder check endpoint for
Cloud Tasks
### Email Subject Format
Email subjects now include brand code and song info for easy
identification:
- With brand code: `NOMAD-1178: Seether - Tonight (Your karaoke video is
ready!)`
- Without brand code: `Seether - Tonight (Your karaoke video is ready!)`
- Without song info: `Your karaoke video is ready!`
### Frontend
- **OutputLinks Component**: Admin-only "Copy Message" and "Send Email"
buttons with dialog UI
- **E2E Helpers** (`email-testing.ts`): `waitForCompletionEmail()` and
`isCompletionEmail()` methods for testmail.app integration
- **Happy Path Test**: Step 9.5 verifies completion email arrives after
job completion
### Documentation
- Updated API.md with new endpoints
- Updated ARCHITECTURE.md with notification system architecture
- Updated README.md Recent Changes
## Testing
- [x] 81 new unit tests covering:
- `test_email_service.py` (27 tests) - providers, CC support, job
completion/reminder methods
- `test_job_notification_service.py` (21 tests) - URL building, message
generation
- `test_job_manager_notifications.py` (15 tests) - state transition
triggers
- `test_admin_email_endpoints.py` (12 tests) - admin API endpoints
- `test_template_service.py` (6 tests) - GCS template loading, fallbacks
- [x] E2E test extended to verify completion email delivery
- [x] All backend tests pass (`make test`)
- [x] TypeScript compiles
## Feature Flags
- `ENABLE_AUTO_EMAILS` (default: `false`) - Controls automatic email
sending on job state changes
## Review
- [x] Local CodeRabbit review completed (3 cycles)
- [x] Review feedback addressed:
- Fixed potential None state_data in internal.py
- Masked user emails in logs (PII protection)
- Fixed React setTimeout memory leak
- Changed placeholder URL default to empty
- Added CC email deduplication
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
9.1 KiB
Plan: Job Email Notifications & Admin Message Tools
Created: 2026-01-06 Branch: feat/sess-20260106-0116-add-email-button Status: Draft
Overview
Add comprehensive email notification system for karaoke-gen that:
- Auto-sends emails when jobs complete or need user input (after 5-minute idle threshold)
- Uses cloud-stored templates for the job completion message
- Provides admin tools to copy/send completion messages manually (for Fiverr, etc.)
Requirements
Functional Requirements
- Auto-send job completion email to user (CC: gen@nomadkaraoke.com)
- Auto-send "action needed" reminder emails when user is idle for 5+ minutes at blocking states (lyrics review, instrumental selection)
- Store email templates in GCS (editable without code deploy)
- Admin button: "Copy Message" - copies templated completion message to clipboard
- Admin button: "Send Email" - prompts for email address, then sends completion message
Non-Functional Requirements
- Email sending must not block job completion (async/background)
- Idle detection via Cloud Tasks scheduled task (not polling)
- Template changes should take effect without restart (no long-term caching)
Technical Approach
1. Template Storage (GCS)
Store templates in gs://karaoke-gen-storage/templates/:
job-completion.txt- Plain text template for job completionjob-completion.html- HTML version (optional, for rich emails)action-needed-lyrics.txt- Reminder for lyrics reviewaction-needed-instrumental.txt- Reminder for instrumental selection
Template Variables:
{name}- User's display name or "there" if unknown{youtube_url}- YouTube video URL{dropbox_url}- Dropbox folder URL{artist}- Artist name{title}- Song title{job_id}- Job ID{review_url}- Lyrics review URL (for action-needed emails){instrumental_url}- Instrumental selection URL{feedback_url}- Feedback form URL (for completion emails)
2. Email Service Extensions
Extend backend/services/email_service.py:
- Add
send_job_completion()method with CC support - Add
send_action_reminder()method - Add
render_template()helper to fetch & render GCS templates
3. Auto-Email Triggers
Job Completion:
- Trigger point: When job enters
COMPLETEstatus injob_manager.transition_to_state() - Implementation: Call email service async in background task
Action Reminders (5-min idle detection):
- When job enters
AWAITING_REVIEWorAWAITING_INSTRUMENTAL_SELECTION:- Record
blocking_state_entered_attimestamp instate_data - Schedule a Cloud Tasks task for 5 minutes later
- Record
- The scheduled task checks if job is still in blocking state and user hasn't started review
- If idle, send reminder email and set
reminder_sentflag to prevent duplicates - Only one reminder per job - if
reminder_sentis true, skip sending
4. Admin UI (Frontend)
Add admin-only buttons to completed jobs in OutputLinks.tsx:
- "Copy Message" button - fetches rendered template, copies to clipboard
- "Send Email" button - opens dialog for email input, calls API to send
5. Backend API Endpoints
New endpoints in backend/api/routes/admin.py:
GET /api/admin/jobs/{job_id}/completion-message- Returns rendered completion messagePOST /api/admin/jobs/{job_id}/send-completion-email- Sends email to specified address
New internal endpoint for scheduled reminder:
POST /api/internal/jobs/{job_id}/check-idle-reminder- Called by Cloud Tasks
Implementation Steps
Phase 1: Template Infrastructure
- Upload initial template to GCS from user's existing template file
- Create
template_service.pyto fetch/render templates from GCS - Add unit tests for template rendering
Phase 2: Email Extensions
- Extend
email_service.pywith CC support insend_email() - Add
send_job_completion()method - Add
send_action_reminder()method - Add unit tests for new email methods
Phase 3: Auto-Email on Completion
- Modify
job_manager.pyto trigger completion email when entering COMPLETE - Add integration test for completion email trigger
Phase 4: Idle Reminder System
- Add
blocking_state_entered_atfield tracking to job state transitions - Create Cloud Tasks queue for idle reminders (
idle-reminder-queue) - Schedule 5-minute delayed task when entering blocking states
- Implement
/api/internal/jobs/{job_id}/check-idle-reminderendpoint - Add tests for idle reminder flow
Phase 5: Admin API
- Add
GET /api/admin/jobs/{job_id}/completion-messageendpoint - Add
POST /api/admin/jobs/{job_id}/send-completion-emailendpoint - Add tests for admin endpoints
Phase 6: Admin UI
- Add
isAdmincheck toOutputLinks.tsxcomponent - Add "Copy Message" button (admin-only) with loading state
- Add "Send Email" button (admin-only) with email input dialog
- Add E2E test for admin buttons
Phase 7: Documentation
- Document template management in docs/DEVELOPMENT.md
- Update docs/API.md with new endpoints
Files to Create/Modify
| File | Action | Description |
|---|---|---|
backend/services/template_service.py |
Create | GCS template fetching and rendering |
backend/services/email_service.py |
Modify | Add CC support, completion/reminder methods |
backend/services/job_manager.py |
Modify | Trigger emails on state transitions |
backend/services/worker_service.py |
Modify | Add idle reminder task scheduling |
backend/api/routes/admin.py |
Modify | Add completion message/email endpoints |
backend/api/routes/internal.py |
Modify | Add idle reminder check endpoint |
backend/models/job.py |
Modify | Add blocking_state_entered_at, reminder_sent_at to state_data docs |
infrastructure/__main__.py |
Modify | Add idle-reminder-queue Cloud Tasks queue |
frontend/components/job/OutputLinks.tsx |
Modify | Add admin-only Copy/Send buttons |
frontend/lib/api.ts |
Modify | Add API methods for admin endpoints |
tests/unit/test_template_service.py |
Create | Template rendering tests |
tests/unit/test_email_service_completion.py |
Create | Completion email tests |
Testing Strategy
Unit Tests:
- Template rendering with all variable combinations
- Email service CC support
- Completion/reminder email generation
- Idle detection logic
Integration Tests:
- Full flow: job completion → email sent
- Idle reminder: job enters blocking state → 5 min → reminder sent
- Admin endpoint authentication
Manual Testing:
- Verify emails render correctly in Gmail/Outlook
- Test admin buttons on completed job
- Test clipboard copy works across browsers
Open Questions
- Where to store templates? → GCS bucket:
gs://karaoke-gen-storage/templates/ - Should we rate-limit reminder emails? → Max 1 reminder per job (send once after 5 min idle, then stop)
- Should completion emails also include a feedback request link? → Yes, for all users
Rollback Plan
- Email sending failures - All email sends are async/fire-and-forget; job completion unaffected
- Template fetch failures - Fall back to hardcoded template in code
- Idle reminder failures - Jobs continue normally; users can still access review UI manually
- Feature flag - Add
ENABLE_AUTO_EMAILS=true/falseenv var for quick disable
Template Content
Initial template (from user's file, with feedback link added):
Hi {name},
Thanks for your order!
Here's the link for the karaoke video published to YouTube:
{youtube_url}
Here's the dropbox folder with all the finished files and source files, including:
- "(Final Karaoke Lossless).mkv": combined karaoke video in 4k H264 with lossless FLAC audio
- "(Final Karaoke).mp4": combined karaoke video with title/end screen in 4k H264/AAC
- "(Final Karaoke 720p).mp4": combined karaoke video in 720p H264/AAC (smaller file for older systems)
- "(With Vocals).mp4": sing along video in 4k H264/AAC with original vocals
- "(Karaoke).mov": karaoke video output from MidiCo (no title/end screen)
- "(Title).mov"/"(End).mov": title card and end screen videos
- "(Final Karaoke CDG).zip": CDG+MP3 format for older/commercial karaoke systems
- "(Final Karaoke TXT).zip": TXT+MP3 format for Power Karaoke
- stems/*.flac: various separated instrumental and vocal audio stems in lossless format
- lyrics/*.txt song lyrics from various sources in plain text format
{dropbox_url}
Let me know if anything isn't perfect and I'll happily tweak / fix, or if you need it in any other format I can probably convert it for you!
If you have a moment, I'd really appreciate your feedback (takes 2 minutes):
{feedback_url}
Thanks again and have a great day!
-Andrew
Note: The {feedback_url} placeholder will be populated with the feedback form URL. If no feedback URL is configured, this section can be omitted from the rendered output.
Updating Templates
To update email templates after deployment:
# Upload new template
gsutil cp my-template.txt gs://karaoke-gen-storage/templates/job-completion.txt
# Templates are fetched fresh on each use (no caching in code)
# Changes take effect immediately