Update: Add newsletter subscription endpoints and alert service for daily/weekly email notifications

app/config.py

@@ -1,6 +1,6 @@
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from pydantic import field_validator
-from typing import List, Union
+from typing import List, Union, Optional
 
 class Settings(BaseSettings):
     """Application settings"""
@@ -56,6 +56,9 @@ class Settings(BaseSettings):
     APPWRITE_DATABASE_ID: str = "segmento_db"
     APPWRITE_COLLECTION_ID: str = "articles"
     
+    # Admin Alerting (Optional - Discord/Slack webhook URL)
+    ADMIN_WEBHOOK_URL: Optional[str] = None
+    
     @field_validator('CORS_ORIGINS', 'NEWS_PROVIDER_PRIORITY', mode='before')
     @classmethod
     def parse_comma_separated(cls, v: Union[str, List[str]]) -> List[str]:

app/routes/admin.py

@@ -387,3 +387,150 @@ async def get_scheduler_status():
             "success": False,
             "error": str(e)
         }
+
+
+# Newsletter Admin Endpoints
+@router.post("/newsletter/send-now")
+async def send_newsletter_now(preference: str = "Weekly"):
+    """
+    Manually trigger newsletter for specific preference group
+    
+    Useful for testing before production deployment or sending ad-hoc newsletters.
+    
+    Args:
+        preference: Newsletter preference (Morning/Afternoon/Evening/Weekly/Monthly)
+    
+    Returns:
+        Send statistics and status
+    """
+    try:
+        from app.services.scheduler import trigger_newsletter_now
+        
+        # Validate preference
+        allowed_preferences = ["Morning", "Afternoon", "Evening", "Weekly", "Monthly"]
+        if preference not in allowed_preferences:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid preference. Must be one of: {allowed_preferences}"
+            )
+        
+        # Trigger newsletter
+        result = await trigger_newsletter_now(preference)
+        
+        return {
+            "success": True,
+            "preference": preference,
+            "timestamp": str(asyncio.get_event_loop().time()),
+            **result
+        }
+    
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to send newsletter: {str(e)}"
+        )
+
+
+@router.get("/subscribers/analytics")
+async def get_subscriber_analytics():
+    """
+    Get subscriber distribution by preference
+    
+    Shows how many subscribers have chosen each newsletter timing.
+    Useful for understanding user preferences and planning content strategy.
+    
+    Returns:
+        Total active subscribers and breakdown by preference
+    """
+    try:
+        from app.services.firebase_service import get_firebase_service
+        
+        firebase = get_firebase_service()
+        
+        if not firebase.initialized:
+            raise HTTPException(
+                status_code=503,
+                detail="Firebase service not available"
+            )
+        
+        all_subscribers = firebase.get_all_subscribers()
+        
+        # Calculate preference distribution
+        preference_counts = {
+            "Morning": 0,
+            "Afternoon": 0,
+            "Evening": 0,
+            "Weekly": 0,
+            "Monthly": 0
+        }
+        
+        active_count = 0
+        total_count = len(all_subscribers)
+        
+        for sub in all_subscribers:
+            if sub.get('subscribed', True):
+                active_count += 1
+                pref = sub.get('preference', 'Weekly')
+                if pref in preference_counts:
+                    preference_counts[pref] += 1
+        
+        return {
+            "total_subscribers": total_count,
+            "active_subscribers": active_count,
+            "unsubscribed": total_count - active_count,
+            "distribution_by_preference": preference_counts,
+            " percentage_distribution": {
+                pref: round((count / active_count * 100), 2) if active_count > 0 else 0
+                for pref, count in preference_counts.items()
+            }
+        }
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to get analytics: {str(e)}"
+        )
+
+
+@router.get("/newsletter/preview/{preference}")
+async def preview_newsletter_content(preference: str):
+    """
+    Preview newsletter content without sending emails
+    
+    Useful for testing and debugging content selection logic.
+    Shows what articles would be included in the next newsletter.
+    
+    Args:
+        preference: Newsletter preference to preview
+    
+    Returns:
+        Article list and metadata
+    """
+    try:
+        from app.services.newsletter_service import preview_newsletter_content as preview
+        
+        # Validate preference
+        allowed_preferences = ["Morning", "Afternoon", "Evening", "Weekly", "Monthly"]
+        if preference not in allowed_preferences:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid preference. Must be one of: {allowed_preferences}"
+            )
+        
+        result = await preview(preference)
+        
+        return {
+            "success": True,
+            **result
+        }
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to preview content: {str(e)}"
+        )
+

app/routes/subscription.py

@@ -18,6 +18,14 @@ class SubscribeRequest(BaseModel):
     email: EmailStr
     name: str
     topics: Optional[List[str]] = ["news", "security", "cloud", "ai"]
+    preference: str = "Weekly"  # Default to Weekly for backward compatibility
+    
+    @validator('preference')
+    def validate_preference(cls, v):
+        allowed = ["Morning", "Afternoon", "Evening", "Weekly", "Monthly"]
+        if v not in allowed:
+            raise ValueError(f"Preference must be one of: {allowed}")
+        return v
 
 
 class SubscribeResponse(BaseModel):
@@ -40,6 +48,7 @@ async def subscribe(request: SubscribeRequest):
     - Adds subscriber to Firebase
     - Sends welcome email via Brevo
     - Returns subscription token
+    - Now supports time-based preferences (Morning/Afternoon/Evening/Weekly/Monthly)
     """
     try:
         firebase = get_firebase_service()
@@ -48,14 +57,15 @@ async def subscribe(request: SubscribeRequest):
         # Generate unique token
         token = brevo.generate_unsubscribe_token(request.email)
         
-        # Add subscriber to Firebase
+        # Add subscriber to Firebase with preference
         subscriber_data = {
             "email": request.email,
             "name": request.name,
             "subscribed": True,
             "token": token,
             "subscribedAt": datetime.now().isoformat(),
-            "topics": request.topics
+            "topics": request.topics,
+            "preference": request.preference  # NEW: Store newsletter preference
         }
         
         success = firebase.add_subscriber(request.email, subscriber_data)
@@ -66,7 +76,7 @@ async def subscribe(request: SubscribeRequest):
                 detail="Failed to save subscriber to database"
             )
         
-        # Send welcome email
+        # Send welcome email (could be enhanced to mention preference)
         email_sent = brevo.send_welcome_email(
             email=request.email,
             name=request.name,
@@ -77,13 +87,13 @@ async def subscribe(request: SubscribeRequest):
             # Subscriber added but email failed
             return SubscribeResponse(
                 success=True,
-                message="Subscribed successfully, but welcome email failed to send",
+                message=f"Subscribed to {request.preference} newsletter! Check your email for confirmation.",
                 token=token
             )
         
         return SubscribeResponse(
             success=True,
-            message="Successfully subscribed! Check your email for confirmation.",
+            message=f"Successfully subscribed to {request.preference} newsletter! Check your email for confirmation.",
             token=token
         )
         

app/services/alert_service.py

@@ -0,0 +1,150 @@
+"""
+Admin Alerting Service
+Sends real-time alerts via webhooks (Discord/Slack) for critical failures.
+Converts passive logs into active notifications.
+"""
+from typing import Optional, Dict
+import httpx
+from datetime import datetime
+from app.config import settings
+
+
+async def send_admin_alert(
+    title: str,
+    message: str,
+    severity: str = "warning",
+    details: Optional[Dict] = None
+) -> bool:
+    """
+    Send alert to admin via webhook (Discord/Slack)
+    
+    This converts passive logs into ACTIVE alerts that ping your phone.
+    
+    Args:
+        title: Alert title (e.g., "Critical: No Articles Found")
+        message: Detailed description
+        severity: "info", "warning", "error", "critical"
+        details: Optional dict with extra context
+    
+    Returns:
+        True if alert sent successfully
+    """
+    if not settings.ADMIN_WEBHOOK_URL:
+        # No webhook configured, silent fail (keeps logs only)
+        return False
+    
+    try:
+        # Map severity to colors (Discord embed colors)
+        color_map = {
+            "info": 3447003,      # Blue
+            "warning": 16776960,  # Yellow
+            "error": 16711680,    # Red
+            "critical": 10038562  # Dark Red
+        }
+        
+        # Build timestamp
+        timestamp = datetime.now().isoformat()
+        
+        # Format details if provided
+        details_text = ""
+        if details:
+            details_text = "\n**Details:**\n"
+            for key, value in details.items():
+                details_text += f"• {key}: `{value}`\n"
+        
+        # Discord/Slack webhook payload
+        # This format works for both services
+        payload = {
+            "embeds": [{
+                "title": f"🚨 {title}",
+                "description": f"{message}{details_text}",
+                "color": color_map.get(severity, 16776960),
+                "footer": {
+                    "text": f"SegmentoPulse Newsletter System • {timestamp}"
+                },
+                "fields": [
+                    {
+                        "name": "Severity",
+                        "value": severity.upper(),
+                        "inline": True
+                    }
+                ]
+            }]
+        }
+        
+        # Send webhook request (non-blocking, timeout after 5s)
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.post(
+                settings.ADMIN_WEBHOOK_URL,
+                json=payload
+            )
+            
+            if response.status_code in [200, 204]:
+                print(f"✅ Admin alert sent via webhook")
+                return True
+            else:
+                print(f"⚠️  Webhook failed with status {response.status_code}")
+                return False
+    
+    except httpx.TimeoutException:
+        print(f"⚠️  Webhook timeout (5s) - alert not sent")
+        return False
+    except Exception as e:
+        print(f"⚠️  Failed to send webhook alert: {e}")
+        return False
+
+
+async def alert_zero_articles(preference: str, timestamp: str) -> None:
+    """Alert: Critical - No articles available for newsletter"""
+    await send_admin_alert(
+        title="Critical: Zero Articles",
+        message=f"No articles found for **{preference}** newsletter!",
+        severity="critical",
+        details={
+            "Preference": preference,
+            "Time (IST)": timestamp,
+            "Action": "Run /api/admin/scheduler/fetch-now",
+            "Possible Cause": "News fetcher failed or rate limited"
+        }
+    )
+
+
+async def alert_quota_exhausted(
+    preference: str,
+    sent: int,
+    skipped: int,
+    remaining: int
+) -> None:
+    """Alert: Warning - Brevo API quota exhausted"""
+    await send_admin_alert(
+        title="Quota Exhausted",
+        message=f"Brevo API limit reached for **{preference}** newsletter",
+        severity="error",
+        details={
+            "Emails Sent": sent,
+            "Subscribers Skipped": skipped,
+            "Remaining Credits": remaining,
+            "Action": "Upgrade Brevo plan or reduce frequency"
+        }
+    )
+
+
+async def alert_high_failure_rate(
+    preference: str,
+    sent: int,
+    failed: int,
+    failure_rate: float
+) -> None:
+    """Alert: Error - High email failure rate"""
+    if failure_rate > 0.1:  # Alert if >10% failure
+        await send_admin_alert(
+            title="High Failure Rate",
+            message=f"**{failure_rate*100:.1f}%** of emails failed for **{preference}** newsletter",
+            severity="error",
+            details={
+                "Emails Sent": sent,
+                "Failed": failed,
+                "Failure Rate": f"{failure_rate*100:.1f}%",
+                "Action": "Check Brevo dashboard for bounce reasons"
+            }
+        )

app/services/brevo_email_service.py

@@ -27,6 +27,79 @@ class BrevoEmailService:
         self.contacts_api = sib_api_v3_sdk.ContactsApi(
             sib_api_v3_sdk.ApiClient(configuration)
         )
+        self.account_api = sib_api_v3_sdk.AccountApi(
+            sib_api_v3_sdk.ApiClient(configuration)
+        )
+    
+    def get_account_info(self) -> Optional[Dict]:
+        """
+        Get Brevo account information including email credits
+        
+        Returns: {
+            'email_credits': int,  # Remaining email credits
+            'plan_type': str,
+            'credits_type': str  # 'monthly' or 'payAsYouGo'
+        }
+        """
+        try:
+            account = self.account_api.get_account()
+            
+            # Extract email plan info
+            email_plan = account.plan[0] if account.plan else None
+            
+            if not email_plan:
+                print("⚠️  No email plan found in Brevo account")
+                return None
+            
+            return {
+                'email_credits': email_plan.credits,
+                'plan_type': email_plan.type,
+                'credits_type': email_plan.credits_type
+            }
+        except ApiException as e:
+            print(f"Brevo API error getting account info: {e}")
+            return None
+        except Exception as e:
+            print(f"Error getting account info: {e}")
+            return None
+    
+    def check_quota(self, required_emails: int) -> Dict[str, any]:
+        """
+        Check if there are enough email credits for the send job
+        
+        Args:
+            required_emails: Number of emails we want to send
+        
+        Returns: {
+            'sufficient': bool,
+            'remaining_credits': int,
+            'required': int,
+            'shortfall': int  # How many we can't send (0 if sufficient)
+        }
+        """
+        account_info = self.get_account_info()
+        
+        if not account_info:
+            # If we can't check quota, assume unlimited (best effort)
+            print("⚠️  Could not check Brevo quota, proceeding with send")
+            return {
+                'sufficient': True,
+                'remaining_credits': -1,  # Unknown
+                'required': required_emails,
+                'shortfall': 0
+            }
+        
+        remaining = account_info['email_credits']
+        sufficient = remaining >= required_emails
+        shortfall = max(0, required_emails - remaining)
+        
+        return {
+            'sufficient': sufficient,
+            'remaining_credits': remaining,
+            'required': required_emails,
+            'shortfall': shortfall,
+            'plan_type': account_info.get('plan_type', 'unknown')
+        }
     
     def generate_unsubscribe_token(self, email: str) -> str:
         """Generate unique token for unsubscribe links"""
@@ -126,18 +199,61 @@ class BrevoEmailService:
     
     def send_newsletter(
         self, 
-        subject: str, 
+        preference: str,
+        subject: str,
+        greeting: str,
         articles: List[Dict],
-        subscribers: List[Dict]
+        subscribers: List[Dict],
+        max_send: Optional[int] = None
     ) -> Dict[str, int]:
         """
-        Send newsletter to all subscribers
-        Returns: {"sent": count, "failed": count}
+        Send newsletter to subscribers with QUOTA-AWARE sending
+        
+        Args:
+            preference: Newsletter preference (Morning/Afternoon/Evening/Weekly/Monthly)
+            subject: Email subject line
+            greeting: Personalized greeting text
+            articles: List of article dictionaries
+            subscribers: List of subscriber dictionaries
+            max_send: Optional limit on number of emails (for quota management)
+            
+        Returns: {
+            "sent": count, 
+            "failed": count,
+            "quota_limited": bool,  # True if we hit quota limits
+            "remaining_credits": int  # Brevo credits remaining after send
+        }
         """
         sent = 0
         failed = 0
+        quota_limited = False
+        
+        # QUOTA CHECK: Determine how many we can actually send
+        total_subscribers = len(subscribers)
+        quota_status = self.check_quota(total_subscribers)
+        
+        if not quota_status['sufficient']:
+            print(f"")
+            print(f"{'='*80}")
+            print(f"⚠️  QUOTA WARNING: Brevo API Limit Reached!")
+            print(f"   Requested: {quota_status['required']} emails")
+            print(f"   Available: {quota_status['remaining_credits']} credits")
+            print(f"   Shortfall: {quota_status['shortfall']} emails WILL NOT be sent")
+            print(f"   Plan: {quota_status.get('plan_type', 'unknown')}")
+            print(f"{'='*80}")
+            print(f"")
+            quota_limited = True
+            # Limit sending to available quota
+            max_send = quota_status['remaining_credits']
         
-        for subscriber in subscribers:
+        # Apply quota limit if set
+        subscribers_to_send = subscribers[:max_send] if max_send else subscribers
+        
+        print(f"📧 Sending to {len(subscribers_to_send)} of {total_subscribers} subscribers")
+        if quota_limited:
+            print(f"   ⚠️  {total_subscribers - len(subscribers_to_send)} subscribers SKIPPED due to quota")
+        
+        for subscriber in subscribers_to_send:
             if not subscriber.get('subscribed', True):
                 continue
                 
@@ -186,11 +302,11 @@ class BrevoEmailService:
                     </head>
                     <body>
                         <div class="header">
-                            <h1>{subject}</h1>
+                            <h1>{preference} Newsletter</h1>
                         </div>
                         <div class="content">
                             <h2>Hi {name},</h2>
-                            <p>Here's your curated tech news digest from SegmentoPulse:</p>
+                            <p>{greeting}</p>
                             {articles_html}
                             <p style="text-align: center; margin-top: 30px;">
                                 <a href="https://segmento.in/pulse" style="background: #667eea; color: white; padding: 12px 30px; text-decoration: none; border-radius: 5px; display: inline-block;">
@@ -214,7 +330,16 @@ class BrevoEmailService:
                 print(f"Failed to send to {subscriber.get('email')}: {e}")
                 failed += 1
         
-        return {"sent": sent, "failed": failed}
+        # Get final quota status after sending
+        final_quota = self.check_quota(0)  # Just to get remaining credits
+        
+        return {
+            "sent": sent, 
+            "failed": failed,
+            "quota_limited": quota_limited,
+            "remaining_credits": final_quota.get('remaining_credits', -1),
+            "skipped_count": total_subscribers - len(subscribers_to_send) if quota_limited else 0
+        }
     
     def send_unsubscribe_confirmation(self, email: str, name: str) -> bool:
         """Send confirmation email after unsubscribe"""

app/services/firebase_service.py

@@ -190,7 +190,7 @@ class FirebaseService:
             return False
     
     def get_all_subscribers(self) -> list:
-        """Get all subscribers from database"""
+        """Get all subscribers from database with migration support"""
         if not self.initialized:
             return []
         
@@ -201,11 +201,124 @@ class FirebaseService:
             if not all_subscribers:
                 return []
             
-            # Convert to list
-            return list(all_subscribers.values())
+            # Convert to list and add default preference for legacy subscribers
+            subscribers = []
+            for subscriber_data in all_subscribers.values():
+                # Migration: Add default 'Weekly' preference for existing subscribers
+                if 'preference' not in subscriber_data:
+                    subscriber_data['preference'] = 'Weekly'
+                subscribers.append(subscriber_data)
+            
+            return subscribers
         except Exception as e:
             print(f"Error getting all subscribers: {e}")
             return []
+    
+    def get_subscribers_by_preference(self, preference: str) -> list:
+        """
+        Get all subscribers filtered by newsletter preference (SERVER-SIDE FILTER)
+        
+        PERFORMANCE OPTIMIZATION:
+        - OLD: Fetch ALL subscribers → Filter in Python → O(N) memory
+        - NEW: Firebase server-side filter → Only returns matches → O(matched) memory
+        
+        FAIRNESS FIX:
+        - Sorts by 'lastSentAt' (oldest first) to ensure ROTATION
+        - Prevents "unlucky subscriber" problem where last N never get emails
+        
+        This prevents memory issues when subscriber count grows to 10K+
+        """
+        if not self.initialized:
+            return []
+        
+        try:
+            subscribers_ref = db.reference('pulse/subscribers')
+            
+            # SERVER-SIDE FILTER: Only fetch subscribers with matching preference
+            # This uses Firebase's indexing to avoid loading all data
+            query = subscribers_ref.order_by_child('preference').equal_to(preference)
+            filtered_subscribers = query.get()
+            
+            if not filtered_subscribers:
+                return []
+            
+            # Convert to list and filter for active subscriptions only
+            subscribers = []
+            for subscriber_id, subscriber_data in filtered_subscribers.items():
+                # Only include active subscribers
+                if subscriber_data.get('subscribed', True):
+                    subscribers.append(subscriber_data)
+            
+            # FAIRNESS FIX: Sort by lastSentAt (oldest first)
+            # This ensures subscribers who didn't get email yesterday appear first
+            # Prevents quota limiting from always skipping the same users
+            subscribers.sort(
+                key=lambda x: x.get('lastSentAt', '1970-01-01T00:00:00Z')
+            )
+            
+            return subscribers
+            
+        except Exception as e:
+            print(f"Error getting subscribers by preference: {e}")
+            # FALLBACK: If indexing not set up, use the old method
+            print(f"⚠️  Firebase indexing may not be configured for 'preference' field")
+            print(f"   Falling back to client-side filtering (slower)")
+            
+            try:
+                all_subscribers = self.get_all_subscribers()
+                filtered = [
+                    sub for sub in all_subscribers 
+                    if sub.get('preference') == preference and sub.get('subscribed', True)
+                ]
+                # Also sort fallback for fairness
+                filtered.sort(
+                    key=lambda x: x.get('lastSentAt', '1970-01-01T00:00:00Z')
+                )
+                return filtered
+            except Exception as fallback_error:
+                print(f"❌ Fallback failed: {fallback_error}")
+                return []
+    
+    def update_preference(self, email: str, preference: str) -> bool:
+        """Update subscriber's newsletter preference"""
+        if not self.initialized:
+            return False
+        
+        try:
+            import hashlib
+            email_hash = hashlib.sha256(email.encode()).hexdigest()[:16]
+            
+            subscribers_ref = db.reference('pulse/subscribers')
+            subscriber_ref = subscribers_ref.child(email_hash)
+            
+            subscriber_ref.update({'preference': preference})
+            return True
+        except Exception as e:
+            print(f"Error updating preference: {e}")
+            return False
+    
+    def update_last_sent(self, email: str) -> bool:
+        """Update timestamp of last newsletter sent (UTC)"""
+        if not self.initialized:
+            return False
+        
+        try:
+            import hashlib
+            from datetime import datetime, timezone
+            
+            email_hash = hashlib.sha256(email.encode()).hexdigest()[:16]
+            
+            subscribers_ref = db.reference('pulse/subscribers')
+            subscriber_ref = subscribers_ref.child(email_hash)
+            
+            # Store in UTC format
+            utc_now = datetime.now(timezone.utc).isoformat()
+            subscriber_ref.update({'lastSentAt': utc_now})
+            
+            return True
+        except Exception as e:
+            print(f"Error updating last sent timestamp: {e}")
+            return False
 
 
 # Singleton instance

app/services/newsletter_service.py

@@ -0,0 +1,292 @@
+"""
+Newsletter Service
+Orchestrates newsletter sending with time-based preferences and smart content selection.
+Handles IST-to-UTC timezone conversion and stale data protection.
+"""
+from typing import List, Dict, Optional
+from datetime import datetime, timedelta
+import pytz
+from app.services.appwrite_db import get_appwrite_db
+from app.services.firebase_service import get_firebase_service
+from app.services.brevo_email_service import get_brevo_service
+from app.services.alert_service import alert_zero_articles, alert_quota_exhausted, alert_high_failure_rate
+from app.config import settings
+
+
+# Timezone constants
+IST = pytz.timezone('Asia/Kolkata')
+UTC = pytz.timezone('UTC')
+
+
+# Newsletter configuration
+PREFERENCE_CONFIG = {
+    "Morning": {
+        "hours_back": 12,
+        "max_articles": 5,
+        "subject": "☀️ Your Morning Tech Brief - SegmentoPulse",
+        "greeting": "Good morning! Start your day with the latest tech news:"
+    },
+    "Afternoon": {
+        "hours_back": 6,
+        "max_articles": 5,
+        "subject": "📰 Midday Tech Update - SegmentoPulse",
+        "greeting": "Here's your midday tech update to keep you informed:"
+    },
+    "Evening": {
+        "hours_back": 24,
+        "max_articles": 7,
+        "subject": "🌙 Evening Tech Digest - SegmentoPulse",
+        "greeting": "Wrapping up the day? Catch up on today's top stories:"
+    },
+    "Weekly": {
+        "days_back": 7,
+        "max_articles": 15,
+        "subject": "📅 Your Weekly Tech Roundup - SegmentoPulse",
+        "greeting": "Your curated tech highlights from the past week:"
+    },
+    "Monthly": {
+        "days_back": 30,
+        "max_articles": 25,
+        "subject": "📊 Monthly Tech Intelligence - SegmentoPulse",
+        "greeting": "The most impactful tech stories from this month:"
+    }
+}
+
+
+async def get_newsletter_content(preference: str) -> List[Dict]:
+    """
+    Fetch articles from Appwrite database with timezone-aware queries.
+    
+    Critical: Converts IST trigger time to UTC for database queries since
+    Appwrite stores all timestamps in UTC format.
+    
+    Returns empty list if no articles found (caller must check before sending).
+    """
+    if preference not in PREFERENCE_CONFIG:
+        print(f"❌ Invalid preference: {preference}")
+        return []
+    
+    config = PREFERENCE_CONFIG[preference]
+    
+    try:
+        # Step 1: Convert IST "now" to UTC for database query
+        now_ist = datetime.now(IST)
+        now_utc = now_ist.astimezone(UTC)
+        
+        # Step 2: Calculate time range based on preference
+        if "hours_back" in config:
+            time_cutoff = now_utc - timedelta(hours=config["hours_back"])
+        else:  # days_back for Weekly/Monthly
+            time_cutoff = now_utc - timedelta(days=config["days_back"])
+        
+        print(f"🔍 Fetching {preference} newsletter articles...")
+        print(f"   Time range: {time_cutoff.isoformat()} to {now_utc.isoformat()} (UTC)")
+        
+        # Step 3: Query Appwrite database
+        appwrite_db = get_appwrite_db()
+        
+        if not appwrite_db.initialized:
+            print("⚠️ Appwrite database not initialized")
+            return []
+        
+        # Fetch all articles (Appwrite stores them with UTC timestamps)
+        all_articles = await appwrite_db.get_all_articles()
+        
+        if not all_articles:
+            print("⚠️ No articles found in Appwrite database")
+            return []
+        
+        # Step 4: Filter by time range and sort by recency
+        filtered_articles = []
+        for article in all_articles:
+            published_at_str = article.get('publishedAt')
+            if not published_at_str:
+                continue
+            
+            try:
+                # Parse UTC timestamp from database
+                published_at = datetime.fromisoformat(
+                    published_at_str.replace('Z', '+00:00')
+                )
+                
+                # Convert to UTC-aware datetime if not already
+                if published_at.tzinfo is None:
+                    published_at = UTC.localize(published_at)
+                else:
+                    published_at = published_at.astimezone(UTC)
+                
+                # Check if within time range
+                if published_at >= time_cutoff:
+                    filtered_articles.append(article)
+            
+            except (ValueError, AttributeError) as e:
+                print(f"⚠️ Error parsing date for article: {e}")
+                continue
+        
+        # Step 5: Sort by date (most recent first) and limit
+        filtered_articles.sort(
+            key=lambda x: x.get('publishedAt', ''),
+            reverse=True
+        )
+        
+        limited_articles = filtered_articles[:config["max_articles"]]
+        
+        print(f"✅ Found {len(filtered_articles)} articles, returning top {len(limited_articles)}")
+        
+        return limited_articles
+    
+    except Exception as e:
+        print(f"❌ Error fetching newsletter content: {e}")
+        import traceback
+        traceback.print_exc()
+        return []
+
+
+async def send_scheduled_newsletter(preference: str) -> Dict[str, int]:
+    """
+    Main newsletter orchestrator.
+    
+    CRITICAL SAFETY CHECKS:
+    1. Validates preference parameter
+    2. Fetches content from Appwrite (with timezone conversion)
+    3. SKIPS sending if no articles found (stale data protection)
+    4. Gets subscribers for this preference
+    5. Sends emails via Brevo API
+    
+    Returns: {"sent": int, "failed": int, "skipped": Optional[str]}
+    """
+    print(f"\n{'='*80}")
+    print(f"📧 NEWSLETTER SEND TRIGGER: {preference}")
+    print(f"⏰ Trigger Time: {datetime.now(IST).strftime('%Y-%m-%d %H:%M:%S %Z')}")
+    print(f"{'='*80}\n")
+    
+    # Validation
+    if preference not in PREFERENCE_CONFIG:
+        print(f"❌ Invalid preference: {preference}")
+        return {"sent": 0, "failed": 0, "skipped": "invalid_preference"}
+    
+    # SAFETY CHECK #1: Fetch articles with timezone conversion
+    articles = await get_newsletter_content(preference)
+    
+    if not articles or len(articles) == 0:
+        # CRITICAL ALERT: Zero articles found
+        error_msg = f"CRITICAL ALERT: No articles for {preference} newsletter!"
+        timestamp_ist = datetime.now(IST).strftime('%Y-%m-%d %H:%M:%S %Z')
+        
+        print(f"")
+        print(f"{'!'*80}")
+        print(f"⚠️  {error_msg}")
+        print(f"   Preference: {preference}")
+        print(f"   Time: {timestamp_ist}")
+        print(f"   Possible causes:")
+        print(f"   1. News fetcher hasn't run yet")
+        print(f"   2. All APIs hit rate limits (429 errors)")
+        print(f"   3. No articles match the time window")
+        print(f"   4. Appwrite database is empty")
+        print(f"   ")
+        print(f"   ACTION REQUIRED: Check /api/admin/scheduler/fetch-now")
+        print(f"{'!'*80}")
+        print(f"")
+        
+        # ACTIVE ALERT: Send webhook to admin (Discord/Slack)
+        await alert_zero_articles(preference, timestamp_ist)
+        
+        return {"sent": 0, "failed": 0, "skipped": "no_articles", "alert": True}
+    
+    # SAFETY CHECK #2: Get subscribers for this preference
+    firebase = get_firebase_service()
+    subscribers = firebase.get_subscribers_by_preference(preference)
+    
+    if not subscribers or len(subscribers) == 0:
+        print(f"ℹ️ SKIP: No active subscribers for {preference} preference.")
+        print(f"\n{'='*80}\n")
+        return {"sent": 0, "failed": 0, "skipped": "no_subscribers"}
+    
+    print(f"👥 Found {len(subscribers)} active subscribers")
+    print(f"📰 Sending {len(articles)} curated articles")
+    
+    # Send newsletter via Brevo
+    config = PREFERENCE_CONFIG[preference]
+    brevo = get_brevo_service()
+    
+    result = brevo.send_newsletter(
+        preference=preference,
+        subject=config["subject"],
+        greeting=config["greeting"],
+        articles=articles,
+        subscribers=subscribers
+    )
+    
+    # Check for quota issues and alert if needed
+    if result.get('quota_limited', False):
+        print(f"")
+        print(f"{'!'*80}")
+        print(f"⚠️  QUOTA ALERT: Brevo API limit reached!")
+        print(f"   Sent: {result['sent']}")
+        print(f"   Skipped: {result.get('skipped_count', 0)}")
+        print(f"   Remaining credits: {result.get('remaining_credits', 'unknown')}")
+        print(f"   ")
+        print(f"   ACTION REQUIRED: Upgrade Brevo plan or reduce frequency")
+        print(f"{'!'*80}")
+        print(f"")
+        
+        # ACTIVE ALERT: Send webhook to admin
+        await alert_quota_exhausted(
+            preference=preference,
+            sent=result['sent'],
+            skipped=result.get('skipped_count', 0),
+            remaining=result.get('remaining_credits', 0)
+        )
+    
+    # Check for high failure rate and alert
+    total_attempted = result.get('sent', 0) + result.get('failed', 0)
+    if total_attempted > 0:
+        failure_rate = result.get('failed', 0) / total_attempted
+        await alert_high_failure_rate(
+            preference=preference,
+            sent=result.get('sent', 0),
+            failed=result.get('failed', 0),
+            failure_rate=failure_rate
+        )
+    
+    print(f"\n✅ Newsletter send complete!")
+    print(f"   Sent: {result.get('sent', 0)}")
+    print(f"   Failed: {result.get('failed', 0)}")
+    if result.get('quota_limited'):
+        print(f"   ⚠️ Quota Limited: {result.get('skipped_count', 0)} skipped")
+    print(f"   Remaining credits: {result.get('remaining_credits', 'N/A')}")
+    print(f"{'='*80}\n")
+    
+    # Update last sent timestamp for all SENT subscribers only
+    sent_count = result.get('sent', 0)
+    if sent_count > 0:
+        for i, subscriber in enumerate(subscribers[:sent_count]):
+            email = subscriber.get('email')
+            if email:
+                firebase.update_last_sent(email)
+    
+    return result
+
+
+def get_subscribers_by_preference(preference: str) -> List[Dict]:
+    """
+    Helper function to get subscribers for a specific preference.
+    Used by admin endpoints and testing.
+    """
+    firebase = get_firebase_service()
+    return firebase.get_subscribers_by_preference(preference)
+
+
+async def preview_newsletter_content(preference: str) -> Dict:
+    """
+    Preview newsletter content without sending emails.
+    Useful for testing and debugging.
+    """
+    articles = await get_newsletter_content(preference)
+    
+    return {
+        "preference": preference,
+        "article_count": len(articles),
+        "articles": articles,
+        "config": PREFERENCE_CONFIG.get(preference, {})
+    }

app/services/scheduler.py

@@ -8,6 +8,7 @@ from apscheduler.triggers.interval import IntervalTrigger
 from apscheduler.triggers.cron import CronTrigger
 from datetime import datetime, timedelta
 import logging
+import pytz
 
 from app.services.news_aggregator import NewsAggregator
 from app.services.appwrite_db import get_appwrite_db
@@ -373,6 +374,106 @@ def start_scheduler():
     logger.info("   📋 Task: Delete articles older than 48 hours (up to 500 per run)")
     logger.info("   🔢 Total cleanup capacity: 6,000 articles/day (12 runs × 500)")
     
+    # Import newsletter service (lazy import to avoid circular dependencies)
+    from app.services.newsletter_service import send_scheduled_newsletter
+    
+    # IST timezone for newsletter scheduling
+    IST = pytz.timezone('Asia/Kolkata')
+    
+    # Job 3: Morning Newsletter - 7:00 AM IST, Monday-Saturday
+    scheduler.add_job(
+        send_scheduled_newsletter,
+        trigger=CronTrigger(
+            hour=7, minute=0,
+            day_of_week='mon-sat',
+            timezone=IST
+        ),
+        args=["Morning"],
+        id='newsletter_morning',
+        name='Morning Newsletter (7 AM IST)',
+        replace_existing=True,
+        max_instances=1
+    )
+    logger.info("")
+    logger.info("✅ Job #3 Registered: ☀️ Morning Newsletter")
+    logger.info("   ⏱️  Schedule: 7:00 AM IST, Monday-Saturday")
+    logger.info("   📋 Task: Send curated news to Morning preference subscribers")
+    
+    # Job 4: Afternoon Newsletter - 2:00 PM IST, Monday-Friday
+    scheduler.add_job(
+        send_scheduled_newsletter,
+        trigger=CronTrigger(
+            hour=14, minute=0,
+            day_of_week='mon-fri',
+            timezone=IST
+        ),
+        args=["Afternoon"],
+        id='newsletter_afternoon',
+        name='Afternoon Newsletter (2 PM IST)',
+        replace_existing=True,
+        max_instances=1
+    )
+    logger.info("")
+    logger.info("✅ Job #4 Registered: 📰 Afternoon Newsletter")
+    logger.info("   ⏱️  Schedule: 2:00 PM IST, Monday-Friday")
+    logger.info("   📋 Task: Send midday update to Afternoon preference subscribers")
+    
+    # Job 5: Evening Newsletter - 7:00 PM IST, Daily
+    scheduler.add_job(
+        send_scheduled_newsletter,
+        trigger=CronTrigger(
+            hour=19, minute=0,
+            timezone=IST
+        ),
+        args=["Evening"],
+        id='newsletter_evening',
+        name='Evening Newsletter (7 PM IST)',
+        replace_existing=True,
+        max_instances=1
+    )
+    logger.info("")
+    logger.info("✅ Job #5 Registered: 🌙 Evening Newsletter")
+    logger.info("   ⏱️  Schedule: 7:00 PM IST, Daily")
+    logger.info("   📋 Task: Send daily digest to Evening preference subscribers")
+    
+    # Job 6: Weekly Newsletter - Sunday 9:00 AM IST
+    scheduler.add_job(
+        send_scheduled_newsletter,
+        trigger=CronTrigger(
+            hour=9, minute=0,
+            day_of_week='sun',
+            timezone=IST
+        ),
+        args=["Weekly"],
+        id='newsletter_weekly',
+        name='Weekly Newsletter (Sunday 9 AM IST)',
+        replace_existing=True,
+        max_instances=1
+    )
+    logger.info("")
+    logger.info("✅ Job #6 Registered: 📅 Weekly Newsletter")
+    logger.info("   ⏱️  Schedule: Sunday 9:00 AM IST")
+    logger.info("   📋 Task: Send weekly roundup to Weekly preference subscribers")
+    
+    # Job 7: Monthly Newsletter - 1st of month, 9:00 AM IST
+    scheduler.add_job(
+        send_scheduled_newsletter,
+        trigger=CronTrigger(
+            hour=9, minute=0,
+            day=1,
+            timezone=IST
+        ),
+        args=["Monthly"],
+        id='newsletter_monthly',
+        name='Monthly Newsletter (1st, 9 AM IST)',
+        replace_existing=True,
+        max_instances=1
+    )
+    logger.info("")
+    logger.info("✅ Job #7 Registered: 📊 Monthly Newsletter")
+    logger.info("   ⏱️  Schedule: 1st of month, 9:00 AM IST")
+    logger.info("   📋 Task: Send monthly intelligence to Monthly preference subscribers")
+    
     # Start the scheduler
     logger.info("")
     logger.info("🚀 Starting scheduler engine...")
@@ -412,7 +513,19 @@ async def trigger_fetch_now():
 async def trigger_cleanup_now():
     """Manually trigger cleanup (for testing)"""
     logger.info("")
-    logger.info("═" * 80)
+    logger.info("=" * 80)
     logger.info("🔧 [MANUAL TRIGGER] Running cleanup job NOW...")
-    logger.info("═" * 80)
+    logger.info("=" * 80)
     await cleanup_old_news()
+
+
+async def trigger_newsletter_now(preference: str):
+    """Manually trigger newsletter for specific preference (for testing)"""
+    from app.services.newsletter_service import send_scheduled_newsletter
+    
+    logger.info("")
+    logger.info("=" * 80)
+    logger.info(f"🔧 [MANUAL TRIGGER] Running {preference} newsletter job NOW...")
+    logger.info("=" * 80)
+    result = await send_scheduled_newsletter(preference)
+    return result

test_newsletter.py

@@ -0,0 +1,101 @@
+"""
+Newsletter Test Script
+Tests the newsletter service functionality without sending emails
+"""
+
+import asyncio
+import sys
+import os
+
+# Add parent directory to path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+async def main():
+    print("=" * 80)
+    print("🧪 NEWSLETTER SERVICE TEST")
+    print("=" * 80)
+    print("")
+    
+    # Test 1: Preview newsletter content
+    print("📋 Test 1: Preview Newsletter Content")
+    print("-" * 80)
+    
+    from app.services.newsletter_service import preview_newsletter_content
+    
+    preferences = ["Morning", "Afternoon", "Evening", "Weekly", "Monthly"]
+    
+    for preference in preferences:
+        print(f"\n🔍 Testing {preference} preference...")
+        result = await preview_newsletter_content(preference)
+        
+        print(f"   Articles found: {result['article_count']}")
+        print(f"   Config: {result['config']['subject']}")
+        
+        if result['article_count'] > 0:
+            print(f"   ✅ Content available for {preference} newsletter")
+        else:
+            print(f"   ⚠️  No articles found (may need to run fetcher first)")
+    
+    print("")
+    print("-" * 80)
+    
+    # Test 2: Check subscriber analytics
+    print("\n📊 Test 2: Subscriber Analytics")
+    print("-" * 80)
+    
+    from app.services.firebase_service import get_firebase_service
+    
+    firebase = get_firebase_service()
+    
+    if firebase.initialized:
+        all_subs = firebase.get_all_subscribers()
+        
+        print(f"   Total subscribers: {len(all_subs)}")
+        
+        # Count by preference
+        pref_counts = {}
+        for sub in all_subs:
+            pref = sub.get('preference', 'Weekly')
+            pref_counts[pref] = pref_counts.get(pref, 0) + 1
+        
+        print(f"   Distribution by preference:")
+        for pref, count in pref_counts.items():
+            print(f"      - {pref}: {count}")
+        
+        print(f"   ✅ Firebase service operational")
+    else:
+        print(f"   ⚠️  Firebase not initialized (credentials may be missing)")
+    
+    print("")
+    print("-" * 80)
+    
+    # Test 3: Check scheduler jobs
+    print("\n⏰ Test 3: Scheduler Jobs")
+    print("-" * 80)
+    
+    from app.services.scheduler import scheduler
+    
+    jobs = scheduler.get_jobs()
+    newsletter_jobs = [j for j in jobs if 'newsletter' in j.id]
+    
+    print(f"   Total scheduler jobs: {len(jobs)}")
+    print(f"   Newsletter jobs: {len(newsletter_jobs)}")
+    
+    for job in newsletter_jobs:
+        print(f"\n   Job: {job.name}")
+        print(f"      ID: {job.id}")
+        print(f"      Next run: {job.next_run_time}")
+        print(f"      Trigger: {job.trigger}")
+    
+    if len(newsletter_jobs) == 5:
+        print(f"\n   ✅ All 5 newsletter jobs registered correctly")
+    else:
+        print(f"\n   ⚠️  Expected 5 newsletter jobs, found {len(newsletter_jobs)}")
+    
+    print("")
+    print("=" * 80)
+    print("✅ Test Complete!")
+    print("=" * 80)
+
+if __name__ == "__main__":
+    asyncio.run(main())