feat(email): HTML branded templates with inline logo, wire remaining notification types

- All webhook emails now render as branded HTML (dark header, inline base64
  Aegis logo, card layout, CTA-button links) instead of plain text.
- Wired the 7 remaining notification-preference keys that had no trigger:
  stale coverage alerts, campaign-activated assignment emails, generic
  test-state-change steps (execution started / blue evaluating / in review),
  all-team-validation broadcasts on every lead vote, webhook delivery
  failures (3rd consecutive failure), new user registration, and background
  job errors (APScheduler global error listener).
- New notify_roles_by_email() helper for role-scoped, preference-gated,
  actor-excludable broadcasts.
- Fixed apscheduler.events stubbing gaps in several test files' sys.modules
  fakes that broke full-suite collection after adding the APScheduler
  error-listener import.

backend/app/jobs/mitre_sync_job.py

@@ -16,6 +16,7 @@ from datetime import datetime, timedelta, timezone
 
 # Import BackgroundScheduler from apscheduler.schedulers.background
 from apscheduler.schedulers.background import BackgroundScheduler
+from apscheduler.events import EVENT_JOB_ERROR
 
 # Import SessionLocal from app.database
 from app.database import SessionLocal
@@ -60,6 +61,27 @@ logger = logging.getLogger(__name__)
 scheduler = BackgroundScheduler()
 
 
+def _on_job_error(event) -> None:
+    """Email admins (opted-in) whenever a scheduled background job raises."""
+    db = SessionLocal()
+    try:
+        from app.services.notification_service import notify_roles_by_email
+        notify_roles_by_email(
+            db, roles=["admin"],
+            preference_key="email_on_system_errors",
+            subject=f"Aegis Background Job Failed: {event.job_id}",
+            message=(
+                f'The scheduled job "{event.job_id}" raised an exception and did '
+                f"not complete:\n\n{event.exception}"
+            ),
+        )
+        db.commit()
+    except Exception:
+        logger.exception("Failed to dispatch system-error notification")
+    finally:
+        db.close()
+
+
 # ---------------------------------------------------------------------------
 # Job functions
 # ---------------------------------------------------------------------------
@@ -440,6 +462,7 @@ def start_scheduler() -> None:
 
     Neither job fires immediately on startup.
     """
+    scheduler.add_listener(_on_job_error, EVENT_JOB_ERROR)
     # Call scheduler.add_job()
     scheduler.add_job(
         _run_mitre_sync,

backend/app/routers/campaigns.py

@@ -124,7 +124,7 @@ from app.services.campaign_crud_service import (
 from app.services.audit_service import log_action
 
 # Import notify_role from app.services.notification_service
-from app.services.notification_service import notify_role
+from app.services.notification_service import notify_role, notify_roles_by_email
 from app.services.webhook_service import dispatch_webhook
 
 # Assign logger = logging.getLogger(__name__)
@@ -543,6 +543,12 @@ def approve_campaign_endpoint(
             entity_id=campaign.id,
             details={"start_date": payload.start_date},
         )
+        notify_roles_by_email(
+            db, roles=["red_tech"],
+            preference_key="email_on_assigned_to_campaign",
+            subject=f"Campaign Activated: {campaign.name}",
+            message=f'Campaign "{campaign.name}" has been approved and activated. You may have tests assigned.',
+        )
         uow.commit()
     db.refresh(campaign)
 
@@ -868,6 +874,12 @@ def activate_campaign(
             # Keyword argument: entity_id
             entity_id=campaign.id,
         )
+        notify_roles_by_email(
+            db, roles=["red_tech"],
+            preference_key="email_on_assigned_to_campaign",
+            subject=f"Campaign Activated: {campaign.name}",
+            message=f'Campaign "{campaign.name}" has been activated. You may have tests assigned.',
+        )
         # Call log_action()
         log_action(
             db,

backend/app/routers/users.py

@@ -185,6 +185,18 @@ def create_user_route(
     # Reload ORM object attributes from the database
     db.refresh(user)
 
+    from app.services.notification_service import notify_roles_by_email
+    notify_roles_by_email(
+        db, roles=["admin"],
+        preference_key="email_on_new_users",
+        subject=f"New User Created: {user.full_name or user.email}",
+        message=(
+            f'A new user account was created: {user.full_name or user.email} '
+            f"({user.email}), role: {user.role}."
+        ),
+        exclude_user_id=current_user.id,
+    )
+
     # Return user
     return user
 

backend/app/services/notification_service.py

@@ -291,6 +291,30 @@ def notify_all_users_by_email(db: Session, *, preference_key: str, subject: str,
             pass  # nosec B110 — one user's failure must not skip the rest
 
 
+def notify_roles_by_email(
+    db: Session, *, roles: list[str], preference_key: str, subject: str, message: str,
+    exclude_user_id=None,
+) -> None:
+    """Email every active, opted-in user holding any of *roles*.
+
+    For workflow-wide callouts to a team (e.g. every lead vote) rather than
+    a single actor's own action — no in-app notification is created here,
+    only the email; pair with ``create_notification``/``notify_role_with_email``
+    if an in-app entry is also needed.
+    """
+    users = db.query(User).filter(User.role.in_(roles), User.is_active == True).all()  # noqa: E712
+    for user in users:
+        if exclude_user_id and user.id == exclude_user_id:
+            continue
+        if not _preference_allows(user, preference_key):
+            continue
+        try:
+            from app.services.webhook_email_service import send_webhook_email
+            send_webhook_email(db, to=user.email, subject=subject, message=message, full_name=user.full_name)
+        except Exception:
+            pass  # nosec B110 — one user's failure must not skip the rest
+
+
 def notify_role_with_email(
     db: Session,
     *,
@@ -362,6 +386,12 @@ def notify_test_state_change(db: Session, test, new_state: str) -> None:
             # Keyword argument: entity_id
             entity_id=test_id,
         )
+        notify_user_by_email(
+            db, creator_id,
+            preference_key="email_on_test_state_change",
+            subject=f"Test Execution Started: {test_name}",
+            message=f'Your test "{test_name}" has moved to the execution phase.',
+        )
 
     # Alternative: new_state == "blue_evaluating"
     elif new_state == "blue_evaluating":
@@ -385,6 +415,12 @@ def notify_test_state_change(db: Session, test, new_state: str) -> None:
                 # Keyword argument: entity_id
                 entity_id=test_id,
             )
+            notify_user_by_email(
+                db, user.id,
+                preference_key="email_on_test_state_change",
+                subject=f"Test Ready for Blue Evaluation: {test_name}",
+                message=f'Test "{test_name}" needs blue team evaluation.',
+            )
 
     # Alternative: new_state == "in_review"
     elif new_state == "in_review":
@@ -414,6 +450,12 @@ def notify_test_state_change(db: Session, test, new_state: str) -> None:
                 # Keyword argument: entity_id
                 entity_id=test_id,
             )
+            notify_user_by_email(
+                db, user.id,
+                preference_key="email_on_test_state_change",
+                subject=f"Test Ready for Validation: {test_name}",
+                message=f'Test "{test_name}" is awaiting your review.',
+            )
 
     # Alternative: new_state == "rejected" and creator_id
     elif new_state == "rejected" and creator_id:

backend/app/services/operational_alert_service.py

@@ -29,7 +29,7 @@ log = logging.getLogger(__name__)
 
 def _dispatch_inapp_notifications(db: Session, rule: AlertRule, instance: AlertInstance) -> None:
     """Create in-app Notification rows for all admins and leads."""
-    from app.services.notification_service import create_notification
+    from app.services.notification_service import create_notification, notify_roles_by_email
 
     admin_roles = {"admin", "red_lead", "blue_lead"}
     users = db.query(User).filter(
@@ -47,6 +47,14 @@ def _dispatch_inapp_notifications(db: Session, rule: AlertRule, instance: AlertI
             entity_id  = instance.id,
         )
 
+    if rule.rule_type == AlertRuleType.stale_technique.value:
+        notify_roles_by_email(
+            db, roles=list(admin_roles),
+            preference_key="email_on_stale_coverage",
+            subject=instance.title,
+            message=instance.message,
+        )
+
 
 def _dispatch_webhooks(rule: AlertRule, instance: AlertInstance) -> None:
     """Fire webhook(s) for a triggered alert (all exceptions caught)."""

backend/app/services/test_workflow_service.py

@@ -39,6 +39,7 @@ from app.services.notification_service import (
     notify_test_state_change,
     create_notification,
     notify_role_with_email,
+    notify_roles_by_email,
 )
 
 # Assign logger = logging.getLogger(__name__)
@@ -1048,6 +1049,13 @@ def validate_as_red_lead(
         },
     )
 
+    notify_roles_by_email(
+        db, roles=["red_lead", "blue_lead"],
+        preference_key="email_on_all_team_validations",
+        subject=f"Red Lead Vote: {test.name}",
+        message=f'{user.full_name or user.username} cast a "{validation_status}" vote as Red Lead on test "{test.name}".',
+        exclude_user_id=user.id,
+    )
     _dispatch_dual_validation_effects(db, test, entity, actor=user)
     return test
 
@@ -1113,6 +1121,13 @@ def validate_as_blue_lead(
         },
     )
 
+    notify_roles_by_email(
+        db, roles=["red_lead", "blue_lead"],
+        preference_key="email_on_all_team_validations",
+        subject=f"Blue Lead Vote: {test.name}",
+        message=f'{user.full_name or user.username} cast a "{validation_status}" vote as Blue Lead on test "{test.name}".',
+        exclude_user_id=user.id,
+    )
     _dispatch_dual_validation_effects(db, test, entity, actor=user)
     return test
 

backend/app/services/webhook_email_service.py

@@ -5,8 +5,9 @@ platform (password setup/reset, test validated, campaign completed, new
 MITRE techniques synced, etc.) goes through ``send_webhook_email`` here,
 which POSTs a ``{to, subject, body}`` JSON payload to a single configured
 webhook URL — intended for a Power Automate flow that actually delivers
-the email. An optional API key, if configured, is sent as an
-``x-api-key`` header.
+the email (the ``body`` is full HTML; the flow's "send email" step must
+have its "Is HTML" option enabled). An optional API key, if configured,
+is sent as an ``x-api-key`` header.
 
 SMTP (``app.services.email_service``) is intentionally left in place but
 unused and unreachable from the UI — see that module's docstring.
@@ -14,7 +15,11 @@ unused and unreachable from the UI — see that module's docstring.
 
 from __future__ import annotations
 
+import base64
+import html as html_lib
 import logging
+import re
+from pathlib import Path
 
 import requests
 from sqlalchemy.orm import Session
@@ -24,22 +29,91 @@ logger = logging.getLogger(__name__)
 _WEBHOOK_URL_CONFIG_KEY = "email_webhook.url"
 _WEBHOOK_API_KEY_CONFIG_KEY = "email_webhook.api_key"
 
-# Standard greeting + footer wrapped around every notification email's
-# actual message, matching the platform's established template.
-_EMAIL_SIGNATURE = (
-    "\n\nRegards,\n"
-    "AEGIS Security Platform\n"
-    "Purple Team Engineering\n"
-    "Owned and operated by Enterprise Corp.\n\n"
-    "Assume breach. Validate controls. Improve continuously.\n\n"
-    "This is an automated notification. Please do not reply."
-)
+_LOGO_PATH = Path(__file__).resolve().parent.parent / "assets" / "email_logo.png"
+_URL_RE = re.compile(r"^https?://\S+$")
+
+_logo_b64_cache: str | None = None
+
+
+def _get_logo_base64() -> str:
+    """Read + cache the inline email logo as a base64 string (empty if missing)."""
+    global _logo_b64_cache
+    if _logo_b64_cache is None:
+        try:
+            _logo_b64_cache = base64.b64encode(_LOGO_PATH.read_bytes()).decode("ascii")
+        except OSError:
+            logger.warning("Email logo asset missing at %s", _LOGO_PATH)
+            _logo_b64_cache = ""
+    return _logo_b64_cache
+
+
+def _message_to_html(message: str) -> str:
+    """Turn a plain-text message (paragraphs separated by blank lines) into
+    escaped HTML, rendering any lone-URL paragraph as a call-to-action button.
+    """
+    parts: list[str] = []
+    for para in message.strip().split("\n\n"):
+        para = para.strip()
+        if not para:
+            continue
+        if _URL_RE.match(para):
+            url = html_lib.escape(para, quote=True)
+            parts.append(
+                f'<p style="margin:0 0 20px;">'
+                f'<a href="{url}" style="display:inline-block;background-color:#0891b2;'
+                f'color:#ffffff;text-decoration:none;padding:12px 24px;border-radius:6px;'
+                f'font-weight:600;font-size:14px;">Open Link &rarr;</a>'
+                f'</p>'
+            )
+        else:
+            escaped = html_lib.escape(para).replace("\n", "<br>")
+            parts.append(f'<p style="margin:0 0 16px;">{escaped}</p>')
+    return "".join(parts)
 
 
 def build_email_body(full_name: str | None, message: str) -> str:
-    """Wrap *message* in the standard greeting + signature template."""
-    greeting = full_name or "there"
-    return f"HI {greeting}\n\n{message}{_EMAIL_SIGNATURE}"
+    """Wrap *message* in Aegis's branded HTML email template (inline logo)."""
+    greeting = html_lib.escape(full_name) if full_name else "there"
+    message_html = _message_to_html(message)
+    logo_b64 = _get_logo_base64()
+    logo_tag = (
+        f'<img src="data:image/png;base64,{logo_b64}" width="56" height="57" alt="Aegis" '
+        f'style="display:block;margin:0 auto 10px;border:0;" />'
+        if logo_b64
+        else ""
+    )
+    return f"""<!DOCTYPE html>
+<html>
+  <body style="margin:0;padding:0;background-color:#0b0f19;font-family:'Segoe UI',Helvetica,Arial,sans-serif;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color:#0b0f19;padding:32px 0;">
+      <tr>
+        <td align="center">
+          <table role="presentation" width="560" cellpadding="0" cellspacing="0" style="max-width:560px;width:100%;background-color:#111827;border-radius:12px;overflow:hidden;border:1px solid #1f2937;">
+            <tr>
+              <td style="background-color:#0e7490;background-image:linear-gradient(135deg,#0e7490,#0891b2);padding:28px 32px;text-align:center;">
+                {logo_tag}
+                <div style="color:#ffffff;font-size:20px;font-weight:700;letter-spacing:1px;">AEGIS SECURITY PLATFORM</div>
+                <div style="color:#cffafe;font-size:11px;letter-spacing:2px;text-transform:uppercase;margin-top:4px;">Purple Team Engineering</div>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:32px;">
+                <p style="color:#e5e7eb;font-size:16px;margin:0 0 16px;">Hi {greeting},</p>
+                <div style="color:#d1d5db;font-size:14px;line-height:1.6;">{message_html}</div>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:20px 32px;background-color:#0b0f19;border-top:1px solid #1f2937;">
+                <p style="color:#67e8f9;font-size:12px;margin:0 0 8px;font-style:italic;">Assume breach. Validate controls. Improve continuously.</p>
+                <p style="color:#4b5563;font-size:11px;margin:0;">Owned and operated by Enterprise Corp. This is an automated notification &mdash; please do not reply.</p>
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>"""
 
 
 def _read_system_config(db: Session, key: str) -> str | None:

backend/app/services/webhook_service.py

@@ -184,6 +184,19 @@ def _send_webhook(db, wh: WebhookConfig, event_type: str, payload: dict) -> None
             "Webhook '%s' (%s) failed for event=%s: %s (failure_count=%d)",
             wh.name, wh.url, event_type, exc, wh.failure_count,
         )
+        if wh.failure_count == 3:
+            # Email once on the 3rd consecutive failure — signals "this looks
+            # broken", without alerting on every transient single failure.
+            from app.services.notification_service import notify_roles_by_email
+            notify_roles_by_email(
+                db, roles=["admin"],
+                preference_key="email_on_webhook_failures",
+                subject=f"Webhook Delivery Failing: {wh.name}",
+                message=(
+                    f'The webhook "{wh.name}" ({wh.url}) has failed {wh.failure_count} times '
+                    f'in a row for event "{event_type}". Last error: {exc}'
+                ),
+            )
 
 
 # ---------------------------------------------------------------------------