# Plan: Automated Weekly Digest Email ## TL;DR Convert the manual `app:send-recommendations` command into a fully automated weekly digest that sends every Monday at 9:00 CET to all eligible users. Add a "what's new this week" section alongside the existing MLT-based personalized recommendations. This is the lowest-effort, highest-impact retention feature since 90% of the infrastructure already exists. --- ## Current State - **Command**: `src/Command/SendRecommendationsCommand.php` (376 lines) — runs manually with `--limit`, `--exclude-sent`, `--no-login-filter` - **Recommendation engine**: `src/Service/RecommendationService.php` — ES MLT based on user's `user_read_history` slugs - **Email delivery**: `src/Service/ListmonkService.php` — self-hosted Listmonk transactional API (template ID 6) - **Eligible users**: `src/Service/ReadHistoryService.php::getEligibleUsers()` — verified + newsletter enabled - **Logging**: `src/Entity/NewsletterLog.php` (table `newsletter_log`) — tracks every send with campaign, status, error - **Template**: `templates/emails/newsletter_recommendations.html.twig` (213 lines) — RTL/LTR aware, tracking pixel, unsubscribe link - **Cron**: Currently documented but NOT active on prod. No crontab entry exists. --- ## Steps ### Step 1: Add "Weekly Digest" Content to Recommendations Extend `src/Service/RecommendationService.php` to add a new method `getWeeklyDigest(User $user, int $count = 3)`: - Query ES for papers added in the last 7 days matching user's `TagInterestsUser` tags or `studyField` - Sort by trending score (join with `trending_research_cache` or use `research_view_log` counts) - Deduplicate against the user's existing MLT recommendations - Return array of `[slug, title, abstract, tags, index]` ### Step 2: Update Email Template Update `templates/emails/newsletter_recommendations.html.twig`: - Add a "New This Week in Your Field" section above the existing "Recommended for You" section - Show 3 weekly digest papers with a "NEW" badge - Keep existing 5 MLT recommendations below - Add a "View More" button linking to `/filter?field={userField}&sortOrder=date` ### Step 3: Update SendRecommendationsCommand Add `--campaign` option to `src/Command/SendRecommendationsCommand.php` (default: `weekly-digest-{date}`): - Pass weekly digest data alongside recommendations to the template - Add `--weekly` flag that combines MLT + weekly digest content - Log with distinct campaign name for tracking ### Step 4: Set Up Production Cron SSH to `20.241.4.71` and add crontab for `www-data`: ``` # Weekly digest — every Monday 9:00 CET (7:00 UTC) 0 7 * * 1 cd /var/www/html/academia_v2 && php bin/console app:send-recommendations --weekly --exclude-sent --env=prod >> /var/log/shamra-weekly-digest.log 2>&1 ``` ### Step 5: Add Batching for Large User Base Current command sends synchronously (200ms delay between emails). For 30K+ users, this takes ~1.7 hours. Options: - **Option A (simple)**: Keep synchronous but add `--batch-size=500 --batch-delay=60` — send 500, pause 60s, repeat - **Option B (better)**: Route email sends through Symfony Messenger async transport. Create `SendNewsletterEmail` message + handler. This decouples the command from delivery. ### Step 6: Add Open/Click Tracking per Digest Extend `src/Entity/EmailTracker.php` to track weekly digest engagement: - Add `campaign` field to correlate with `NewsletterLog` - Track which of the 8 papers (3 digest + 5 MLT) the user clicks - This data feeds back into recommendation quality measurement --- ## Verification 1. **Dry run**: `app:send-recommendations --weekly --dry-run --limit=5 --user={testUserId}` — confirm template renders correctly with both sections 2. **Send to test users**: `--limit=10 --weekly` — verify emails arrive, links work, tracking fires 3. **Monitor**: Check `newsletter_log` for campaign `weekly-digest-2026-03-10` the following Monday 4. **Engagement**: After 2 weeks, query `email_tracker` for open rates on digest vs. regular campaigns --- ## Decisions - **Weekly not daily**: Daily is too noisy for 30K users and risks unsubscribes. Weekly is the industry standard for research platforms. - **Listmonk not Mailgun**: Continue with Listmonk since it's already handling recommendations with good deliverability - **Synchronous initially**: Keep simple synchronous sending until user base exceeds 50K, then migrate to Messenger-based async