Rework email notifications with explicit send actions.

Add test and report email endpoints, surface SMTP errors to the UI, and add a Send Test/Send Report button so users can verify email delivery before or after running detection.

Made-with: Cursor

app/main.py

@@ -26,7 +26,7 @@ from .auth import (
 )
 from .database import Base, engine, get_db, DATA_DIR
 from .models import User, DetectionRun
-from .notifier import send_notification
+from .notifier import send_notification, send_test_email
 
 import logging
 logger = logging.getLogger(__name__)
@@ -105,6 +105,17 @@ class UserResponse(BaseModel):
     full_name: str
 
 
+class EmailRequest(BaseModel):
+    email: str
+
+
+def _load_regions_json(raw_regions: Optional[str]):
+    try:
+        return json.loads(raw_regions) if raw_regions else []
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+
 # --- Auth routes ---
 def _auth_response(token: str, user: User):
     """JSON response with auth cookie so browser sends token on every request (e.g. POST /api/detect)."""
@@ -324,8 +335,9 @@ async def detect(
 
     # Send email notification if requested
     notification_sent = False
+    notification_error = None
     if notify_email and notify_email.strip():
-        notification_sent = send_notification(
+        notification_sent, notification_error = send_notification(
             recipient=notify_email.strip(),
             title=title,
             method=method,
@@ -356,10 +368,24 @@ async def detect(
         "beforeThumbUrl": f"/api/overlay/{relative_before_thumb}",
         "afterThumbUrl": f"/api/overlay/{relative_after_thumb}",
         "notificationSent": notification_sent,
+        "notificationError": notification_error,
         "createdAt": _isoformat_ist(run.created_at),
     }
 
 
+@app.post("/api/notify/test")
+def notify_test(
+    data: EmailRequest,
+    user: Optional[User] = Depends(get_current_user),
+):
+    if not user:
+        raise HTTPException(status_code=401, detail="Login required")
+    sent, error = send_test_email(data.email.strip())
+    if not sent:
+        raise HTTPException(status_code=400, detail=error or "Failed to send test email")
+    return {"ok": True, "message": f"Test email sent to {data.email.strip()}."}
+
+
 @app.get("/api/overlay/{path:path}")
 def serve_overlay(path: str):
     # Restrict to overlays directory
@@ -415,10 +441,7 @@ def get_run(
     run = db.query(DetectionRun).filter(DetectionRun.id == run_id, DetectionRun.user_id == user.id).first()
     if not run:
         raise HTTPException(status_code=404, detail="Run not found")
-    try:
-        regions = json.loads(run.regions_json) if run.regions_json else []
-    except (json.JSONDecodeError, TypeError):
-        regions = []
+    regions = _load_regions_json(run.regions_json)
     return {
         "id": run.id,
         "title": run.title,
@@ -440,6 +463,36 @@ def get_run(
     }
 
 
+@app.post("/api/history/{run_id}/notify")
+def notify_run(
+    run_id: int,
+    data: EmailRequest,
+    user: Optional[User] = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    if not user:
+        raise HTTPException(status_code=401, detail="Login required")
+    run = db.query(DetectionRun).filter(DetectionRun.id == run_id, DetectionRun.user_id == user.id).first()
+    if not run:
+        raise HTTPException(status_code=404, detail="Run not found")
+
+    regions = _load_regions_json(run.regions_json)
+    sent, error = send_notification(
+        recipient=data.email.strip(),
+        title=run.title,
+        method=run.method,
+        zone=run.zone or "",
+        village=run.village or "",
+        change_pct=float(run.change_percentage),
+        changed_px=int(run.changed_pixels),
+        total_px=int(run.total_pixels),
+        regions=regions,
+    )
+    if not sent:
+        raise HTTPException(status_code=400, detail=error or "Failed to send report email")
+    return {"ok": True, "message": f"Report email sent to {data.email.strip()}."}
+
+
 # --- Delete history run ---
 @app.delete("/api/history/{run_id}")
 def delete_run(

app/notifier.py

@@ -1,7 +1,8 @@
 """
 Email notification module.
-Sends HTML-formatted detection reports via SMTP STARTTLS (port 587).
-Credentials are read from environment variables — never hardcoded.
+Sends HTML-formatted detection reports via Gmail SMTP.
+Credentials are read from environment variables and loaded at send time so a
+server restart or secret update is picked up reliably.
 """
 import logging
 import os
@@ -15,14 +16,24 @@ from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
-SMTP_HOST = os.environ.get("SMTP_HOST", "smtp.gmail.com")
-SMTP_PORT = int(os.environ.get("SMTP_PORT", "587"))
-SMTP_USER = os.environ.get("SMTP_USER", "vedangofficeserver@gmail.com")
-SMTP_PASS = os.environ.get("SMTP_PASS", "")
+EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
 
 TEMPLATE_PATH = Path(__file__).resolve().parent.parent / "templates" / "ChangeDetection.html"
 
 
+def _smtp_settings():
+    return {
+        "host": os.environ.get("SMTP_HOST", "smtp.gmail.com"),
+        "port": int(os.environ.get("SMTP_PORT", "587")),
+        "user": os.environ.get("SMTP_USER", "vedangofficeserver@gmail.com"),
+        "password": os.environ.get("SMTP_PASS", ""),
+    }
+
+
+def _valid_email(email: str) -> bool:
+    return bool(email and EMAIL_RE.match(email.strip()))
+
+
 def _load_template() -> str:
     """Read the HTML email template from disk."""
     if not TEMPLATE_PATH.exists():
@@ -92,6 +103,48 @@ def build_email_body(
     return html
 
 
+def _send_html_email(recipient: str, subject: str, html_body: str):
+    settings = _smtp_settings()
+    smtp_user = settings["user"]
+    smtp_pass = settings["password"]
+    smtp_host = settings["host"]
+    smtp_port = settings["port"]
+
+    if not _valid_email(recipient):
+        return False, "Enter a valid recipient email address."
+    if not smtp_user or not smtp_pass:
+        logger.warning("SMTP_USER or SMTP_PASS not set — skipping email notification")
+        return False, "SMTP credentials are not configured on the server."
+
+    msg = MIMEMultipart("alternative")
+    msg["Subject"] = subject
+    msg["From"] = smtp_user
+    msg["To"] = recipient
+    msg.attach(MIMEText(html_body, "html", "utf-8"))
+
+    try:
+        context = ssl.create_default_context()
+        with smtplib.SMTP(smtp_host, smtp_port, timeout=20) as server:
+            server.ehlo()
+            server.starttls(context=context)
+            server.ehlo()
+            server.login(smtp_user, smtp_pass)
+            server.sendmail(smtp_user, recipient, msg.as_string())
+        logger.info("Notification email sent to %s", recipient)
+        return True, None
+    except smtplib.SMTPAuthenticationError:
+        logger.exception("SMTP authentication failed")
+        return False, "SMTP authentication failed. Check the Gmail app password."
+    except Exception as exc:
+        logger.error(
+            "Failed to send notification email to %s: %s: %s",
+            recipient,
+            type(exc).__name__,
+            exc,
+        )
+        return False, f"{type(exc).__name__}: {exc}"
+
+
 def send_notification(
     recipient: str,
     title: str,
@@ -102,36 +155,26 @@ def send_notification(
     changed_px: int,
     total_px: int,
     regions: list,
-) -> bool:
-    """
-    Send detection report email to the recipient.
-    Returns True on success, False on failure (never raises).
-    """
-    if not SMTP_PASS or not SMTP_USER:
-        logger.warning("SMTP_USER or SMTP_PASS not set — skipping email notification")
-        return False
-
+):
+    """Send a detection report email and return (success, error_message)."""
     html_body = build_email_body(
         title, method, zone, village, change_pct, changed_px, total_px, regions
     )
+    subject = f"Change Detection Report — {title or 'Untitled run'}"
+    return _send_html_email(recipient, subject, html_body)
 
-    msg = MIMEMultipart("alternative")
-    msg["Subject"] = f"Change Detection Report — {title or 'Untitled run'}"
-    msg["From"] = SMTP_USER
-    msg["To"] = recipient
-    msg.attach(MIMEText(html_body, "html", "utf-8"))
 
-    try:
-        context = ssl.create_default_context()
-        with smtplib.SMTP(SMTP_HOST, SMTP_PORT, timeout=15) as server:
-            server.ehlo()
-            server.starttls(context=context)
-            server.ehlo()
-            server.login(SMTP_USER, SMTP_PASS)
-            server.sendmail(SMTP_USER, recipient, msg.as_string())
-        logger.info("Notification email sent to %s", recipient)
-        return True
-    except Exception as e:
-        logger.error("Failed to send notification email to %s: %s: %s",
-                     recipient, type(e).__name__, e)
-        return False
+def send_test_email(recipient: str):
+    """Send a small test email so SMTP configuration can be verified quickly."""
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    html_body = f"""
+    <html>
+      <body style="font-family: Arial, sans-serif; color: #222;">
+        <h2>AI Change Detection Email Test</h2>
+        <p>This is a test email from the AI Change Detection application.</p>
+        <p>If you received this, the SMTP configuration is working.</p>
+        <p><strong>Timestamp:</strong> {now}</p>
+      </body>
+    </html>
+    """
+    return _send_html_email(recipient, "AI Change Detection — Test Email", html_body)

static/css/style.css

@@ -465,9 +465,23 @@ input:focus, select:focus, textarea:focus {
 .notify-email-group input {
   width: 100%;
 }
+.notify-email-actions {
+  display: flex;
+  gap: 0.6rem;
+  align-items: stretch;
+}
+.notify-email-actions .btn {
+  flex-shrink: 0;
+}
+.notify-help {
+  margin-top: 0.35rem;
+  font-size: 0.78rem;
+  color: var(--text-dim);
+}
 @media (max-width: 640px) {
   .notify-row { flex-direction: column; align-items: stretch; }
   .notify-email-group { min-width: 100%; }
+  .notify-email-actions { flex-direction: column; }
 }
 
 /* ---- Upload zones ---- */

static/js/app.js

@@ -30,6 +30,10 @@ function showSuccess(id, msg) {
   setTimeout(() => el.classList.add('hidden'), 4000);
 }
 
+function isValidEmail(email) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test((email || '').trim());
+}
+
 async function api(method, path, options = {}) {
   const headers = { ...options.headers };
   const token = getToken();
@@ -288,9 +292,59 @@ const DELHI_ZONES = {
       group.classList.add('hidden');
       document.getElementById('notify-email').value = '';
     }
+    updateNotifyActionState();
   });
 })();
 
+function updateNotifyActionState() {
+  const cb = document.getElementById('detect-notify');
+  const btn = document.getElementById('notify-send-btn');
+  const help = document.getElementById('notify-help');
+  if (!btn || !cb) return;
+  btn.disabled = !cb.checked;
+  if (currentResultData?.id) {
+    btn.textContent = 'Send Report';
+    if (help) help.textContent = 'Send the currently open result report to this email address, or run a new detection to auto-send.';
+  } else {
+    btn.textContent = 'Send Test';
+    if (help) help.textContent = 'Use Send Test to verify email delivery, or run detection to send the report automatically.';
+  }
+}
+
+document.getElementById('notify-send-btn')?.addEventListener('click', async () => {
+  hideError('dashboard-error');
+  const cb = document.getElementById('detect-notify');
+  const input = document.getElementById('notify-email');
+  const btn = document.getElementById('notify-send-btn');
+  const email = (input?.value || '').trim();
+
+  if (!cb?.checked) {
+    showError('dashboard-error', 'Enable "Notify via Email" first.');
+    return;
+  }
+  if (!isValidEmail(email)) {
+    showError('dashboard-error', 'Please enter a valid email address.');
+    return;
+  }
+
+  const originalText = btn.textContent;
+  btn.disabled = true;
+  btn.textContent = 'Sending...';
+  try {
+    const path = currentResultData?.id
+      ? `/api/history/${currentResultData.id}/notify`
+      : '/api/notify/test';
+    const data = await api('POST', path, { body: JSON.stringify({ email }) });
+    showSuccess('dashboard-success', data?.message || 'Email sent successfully.');
+  } catch (err) {
+    showError('dashboard-error', err.message || 'Failed to send email.');
+  } finally {
+    btn.disabled = false;
+    btn.textContent = originalText;
+    updateNotifyActionState();
+  }
+});
+
 // ---- Run detection ----
 document.getElementById('form-detect')?.addEventListener('submit', async (e) => {
   e.preventDefault();
@@ -323,7 +377,7 @@ document.getElementById('form-detect')?.addEventListener('submit', async (e) =>
   const notifyInput = document.getElementById('notify-email');
   if (notifyCb?.checked) {
     const email = (notifyInput?.value || '').trim();
-    if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    if (!isValidEmail(email)) {
       showError('dashboard-error', 'Please enter a valid email address for notification.');
       btn.disabled = false;
       loading.classList.add('hidden');
@@ -348,7 +402,7 @@ document.getElementById('form-detect')?.addEventListener('submit', async (e) =>
     if (notifyCbDone?.checked) {
       notifyMsg = data.notificationSent
         ? ' Notification email sent.'
-        : ' ⚠ Email notification failed — check SMTP credentials.';
+        : ` Email notification failed${data.notificationError ? `: ${data.notificationError}` : '.'}`;
     }
     showSuccess('dashboard-success', 'Detection complete!' + notifyMsg);
     loadHistory();
@@ -383,6 +437,8 @@ let _regionList = [];        // matching data objects
 const REGIONS_PER_PAGE = 10;
 let _regionPage = 0;
 
+updateNotifyActionState();
+
 function showResult(data) {
   const modal = document.getElementById('result-modal');
   const statsEl = document.getElementById('result-stats');
@@ -464,6 +520,7 @@ function showResult(data) {
 
   _regionPage = 0;
   renderRegionPage();
+  updateNotifyActionState();
   openResultModal();
 }
 

templates/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>AI Change Detection</title>
-  <link rel="stylesheet" href="/static/css/style.css?v=17" />
+  <link rel="stylesheet" href="/static/css/style.css?v=18" />
 </head>
 <body>
   <div class="app">
@@ -228,7 +228,11 @@
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"/><polyline points="22,6 12,13 2,6"/></svg>
                 Recipient Email
               </label>
-              <input type="email" id="notify-email" placeholder="recipient@example.com" />
+              <div class="notify-email-actions">
+                <input type="email" id="notify-email" placeholder="recipient@example.com" />
+                <button type="button" class="btn btn-secondary" id="notify-send-btn">Send Test</button>
+              </div>
+              <div class="notify-help" id="notify-help">Use Send Test to verify email delivery, or run detection to send the report automatically.</div>
             </div>
           </div>
           <div class="run-btn-wrap">
@@ -346,6 +350,6 @@
     </div>
   </div>
 
-  <script src="/static/js/app.js?v=23"></script>
+  <script src="/static/js/app.js?v=24"></script>
 </body>
 </html>