Finalize diagnostics, logging controls, and email test support

backend/app/services/invite_email.py

@@ -394,6 +394,17 @@ def _send_email_sync(*, recipient_email: str, subject: str, body_text: str, body
     use_ssl = bool(runtime.magent_notify_email_use_ssl)
     if not host or not from_address:
         raise RuntimeError("SMTP email settings are incomplete.")
+    logger.info(
+        "smtp send started recipient=%s from=%s host=%s port=%s tls=%s ssl=%s auth=%s subject=%s",
+        recipient_email,
+        from_address,
+        host,
+        port,
+        use_tls,
+        use_ssl,
+        bool(username and password),
+        subject,
+    )
 
     message = EmailMessage()
     message["Subject"] = subject
@@ -405,19 +416,26 @@ def _send_email_sync(*, recipient_email: str, subject: str, body_text: str, body
 
     if use_ssl:
         with smtplib.SMTP_SSL(host, port, timeout=20) as smtp:
+            logger.debug("smtp ssl connection opened host=%s port=%s", host, port)
             if username and password:
                 smtp.login(username, password)
+                logger.debug("smtp login succeeded host=%s username=%s", host, username)
             smtp.send_message(message)
+            logger.info("smtp send accepted recipient=%s host=%s mode=ssl", recipient_email, host)
         return
 
     with smtplib.SMTP(host, port, timeout=20) as smtp:
+        logger.debug("smtp connection opened host=%s port=%s", host, port)
         smtp.ehlo()
         if use_tls:
             smtp.starttls()
             smtp.ehlo()
+            logger.debug("smtp starttls negotiated host=%s port=%s", host, port)
         if username and password:
             smtp.login(username, password)
+            logger.debug("smtp login succeeded host=%s username=%s", host, username)
         smtp.send_message(message)
+        logger.info("smtp send accepted recipient=%s host=%s mode=plain", recipient_email, host)
 
 
 async def send_templated_email(
@@ -461,3 +479,40 @@ async def send_templated_email(
         "recipient_email": resolved_email,
         "subject": rendered["subject"],
     }
+
+
+async def send_test_email(recipient_email: Optional[str] = None) -> Dict[str, str]:
+    ready, detail = smtp_email_config_ready()
+    if not ready:
+        raise RuntimeError(detail)
+
+    runtime = get_runtime_settings()
+    resolved_email = _normalize_email(recipient_email) or _normalize_email(
+        runtime.magent_notify_email_from_address
+    )
+    if not resolved_email:
+        raise RuntimeError("No valid recipient email is configured for the test message.")
+
+    application_url = _normalize_display_text(runtime.magent_application_url, "Not configured")
+    subject = f"{env_settings.app_name} email test"
+    body_text = (
+        f"This is a test email from {env_settings.app_name}.\n\n"
+        f"Build: {BUILD_NUMBER}\n"
+        f"Application URL: {application_url}\n"
+    )
+    body_html = (
+        f"<h1>{html.escape(env_settings.app_name)} email test</h1>"
+        f"<p>This is a test email from <strong>{html.escape(env_settings.app_name)}</strong>.</p>"
+        f"<p><strong>Build:</strong> {html.escape(BUILD_NUMBER)}<br />"
+        f"<strong>Application URL:</strong> {html.escape(application_url)}</p>"
+    )
+
+    await asyncio.to_thread(
+        _send_email_sync,
+        recipient_email=resolved_email,
+        subject=subject,
+        body_text=body_text,
+        body_html=body_html,
+    )
+    logger.info("SMTP test email sent: recipient=%s", resolved_email)
+    return {"recipient_email": resolved_email, "subject": subject}