diff --git a/plugins/platforms/email/adapter.py b/plugins/platforms/email/adapter.py index 572b5c11455d3..864cf4626e677 100644 --- a/plugins/platforms/email/adapter.py +++ b/plugins/platforms/email/adapter.py @@ -46,6 +46,92 @@ from utils import env_int, env_bool logger = logging.getLogger(__name__) + +# ── HTML Email Styling ────────────────────────────────────────────────────── +# Inline CSS for maximum email client compatibility (Gmail, Outlook, Apple Mail). + +_HTML_PREFIX = """\ + + + + +
+ +""" + +_HERMES_EMAIL_FOOTER = """\ + +
+ Sent by Hermes Agent · + + hermes-agent.nousresearch.com + +
+
+ + +""" + +_HERMES_EMAIL_ELEMENT_STYLES = [ + ("h1", 'style="font-size:24px;font-weight:700;color:#1a202c;margin:24px 0 12px;border-bottom:2px solid #667eea;padding-bottom:8px;"'), + ("h2", 'style="font-size:20px;font-weight:700;color:#2d3748;margin:24px 0 10px;border-bottom:1px solid #e2e8f0;padding-bottom:6px;"'), + ("h3", 'style="font-size:17px;font-weight:600;color:#4a5568;margin:18px 0 8px;"'), + ("h4", 'style="font-size:15px;font-weight:600;color:#718096;margin:14px 0 6px;"'), + ("p", 'style="margin:0 0 12px;"'), + ("ul", 'style="margin:0 0 12px;padding-left:24px;"'), + ("ol", 'style="margin:0 0 12px;padding-left:24px;"'), + ("li", 'style="margin-bottom:4px;"'), + ("blockquote", 'style="margin:12px 0;padding:12px 16px;border-left:4px solid #667eea;background:#f7fafc;color:#4a5568;font-style:italic;"'), + ("table", 'style="border-collapse:collapse;width:100%;margin:12px 0;font-size:14px;"'), + ("th", 'style="background:#667eea;color:#fff;padding:8px 12px;text-align:left;font-weight:600;"'), + ("td", 'style="padding:8px 12px;border-bottom:1px solid #e2e8f0;"'), + ("tr", 'style="border-bottom:1px solid #e2e8f0;"'), + ("code", 'style="background:#edf2f7;padding:2px 5px;border-radius:3px;font-size:13px;font-family:Menlo,Monaco,Consolas,monospace;"'), + ("pre", 'style="background:#2d3748;color:#e2e8f0;padding:16px;border-radius:6px;overflow-x:auto;font-size:13px;line-height:1.5;"'), + ("a", 'style="color:#667eea;text-decoration:none;"'), + ("strong", 'style="color:#1a202c;"'), + ("em", 'style="color:#4a5568;"'), + ("hr", 'style="border:none;border-top:1px solid #e2e8f0;margin:20px 0;"'), +] + +# HTML detection regex — matches common HTML document openings or HTML +# fragment tags that signal the body is HTML (not plain text). +# Used to detect pre-existing HTML in model/cron output. +_HTML_RE = re.compile( + r"(?:]|<(?:div|table|h[1-6]|section|article|main|header|footer|style)\b)", + re.IGNORECASE | re.DOTALL, +) + +# Block-level closing tags used to detect end of HTML fragments +_BLOCK_CLOSE_RE = re.compile( + r"", + re.IGNORECASE, +) + + +def _style_html_email(html: str) -> str: + """Inject inline CSS styles into HTML elements for email client compat.""" + import re + # Pre-code override MUST run before the general tag loop, + # otherwise the general loop adds style= to first and the + # override regex (?![^>]*style=) can no longer match. + html = re.sub( + r'(]*>.*?)]*style=)(\s|>)', + r'\1]*style=)(\s|>)', + rf'<{tag} {style}\1', + html, + ) + return html + # Automated sender patterns — emails from these are silently ignored _NOREPLY_PATTERNS = ( "noreply", "no-reply", "no_reply", "donotreply", "do-not-reply", @@ -447,6 +533,7 @@ def __init__(self, config: PlatformConfig): # email: # skip_attachments: true self._skip_attachments = extra.get("skip_attachments", False) + self._html_format = extra.get("html_format", True) # Require the sender's From: domain to be authenticated (SPF/DKIM/DMARC) # before trusting it for authorization. The From: header is @@ -946,7 +1033,7 @@ def _send_email( msg_id = f"" msg["Message-ID"] = msg_id - msg.attach(MIMEText(body, "plain", "utf-8")) + self._attach_body(msg, body) smtp = self._connect_smtp() try: @@ -964,6 +1051,74 @@ def _send_email( async def send_typing(self, chat_id: str, metadata: Optional[Dict[str, Any]] = None) -> None: """Email has no typing indicator — no-op.""" + # ── HTML email helpers ────────────────────────────────────────────────── + + def _attach_body(self, msg: MIMEMultipart, body: str) -> None: + """Attach body as plain text + optional HTML to a message. + + Always wraps in multipart/alternative so email clients correctly + choose between plain and HTML representations. + """ + alt = MIMEMultipart("alternative") + self._attach_parts(alt, body) + msg.attach(alt) + + def _create_body_part(self, body: str) -> MIMEMultipart: + """Create a multipart/alternative body part (for use inside multipart/mixed).""" + alt = MIMEMultipart("alternative") + self._attach_parts(alt, body) + return alt + + def _attach_parts(self, container: MIMEMultipart, body: str) -> None: + """Attach plain + optional HTML parts to a multipart container.""" + # Check if body already contains HTML (from cron/model output). + # Models sometimes produce full HTML documents or fragments with + # preamble text before the first HTML tag. + html_match = _HTML_RE.search(body) + if html_match and self._html_format: + # Body already contains HTML — strip preamble and trailing + # commentary, then send as multipart/alternative. + html_body = body[html_match.start():] + + # Strip content after (first occurrence, not last) + html_end = html_body.lower().find("") + if html_end >= 0: + html_body = html_body[: html_end + len("")] + else: + # HTML fragment — strip trailing model commentary + for m in reversed(list(_BLOCK_CLOSE_RE.finditer(html_body))): + after = html_body[m.end():] + if not after.strip(): + break + if re.search(r"<[a-zA-Z/!]", after.strip()): + continue # still HTML + html_body = html_body[: m.end()] + break + + # Generate plain-text fallback + import html as _html_mod + plain = _html_mod.unescape(re.sub(r"<[^>]+>", "", html_body)).strip() + if not plain: + plain = "(HTML email — please view in a client that supports HTML.)" + + container.attach(MIMEText(plain, "plain", "utf-8")) + container.attach(MIMEText(html_body, "html", "utf-8")) + else: + # Body is markdown/plain — convert to HTML if html_format enabled + container.attach(MIMEText(body, "plain", "utf-8")) + if self._html_format: + try: + import markdown + html_body = markdown.markdown( + body, extensions=["tables", "fenced_code", "nl2br"] + ) + html_body = _style_html_email(_HTML_PREFIX + html_body + _HERMES_EMAIL_FOOTER) + container.attach(MIMEText(html_body, "html", "utf-8")) + except ImportError: + logger.debug("[Email] markdown not installed, sending plain text") + except Exception as e: + logger.warning("[Email] HTML conversion failed, falling back to plain: %s", e) + async def send_image( self, chat_id: str, @@ -1060,7 +1215,7 @@ def _send_email_with_attachments( msg["Message-ID"] = msg_id if body: - msg.attach(MIMEText(body, "plain", "utf-8")) + msg.attach(self._create_body_part(body)) for file_path in file_paths: p = Path(file_path) @@ -1140,7 +1295,7 @@ def _send_email_with_attachment( msg["Message-ID"] = msg_id if body: - msg.attach(MIMEText(body, "plain", "utf-8")) + msg.attach(self._create_body_part(body)) # Attach file p = Path(file_path) @@ -1197,16 +1352,22 @@ async def _standalone_send( force_document=False, ): """Out-of-process Email delivery via SMTP (one-shot). Implements the - standalone_sender_fn contract; replaces the legacy _send_email helper.""" + standalone_sender_fn contract; replaces the legacy _send_email helper. + + Sends multipart/alternative with plain text + HTML (when markdown is + available). Uses the same inline CSS styling as the adapter class. + """ import smtplib import ssl as _ssl from email.mime.text import MIMEText from email.utils import formatdate + from email.mime.multipart import MIMEMultipart as _MIMEMultipart extra = getattr(pconfig, "extra", {}) or {} address = extra.get("address") or os.getenv("EMAIL_ADDRESS", "") password = os.getenv("EMAIL_PASSWORD", "") smtp_host = extra.get("smtp_host") or os.getenv("EMAIL_SMTP_HOST", "") + html_format = extra.get("html_format", True) try: smtp_port = int(os.getenv("EMAIL_SMTP_PORT", "587")) except (ValueError, TypeError): @@ -1216,14 +1377,40 @@ async def _standalone_send( return {"error": "Email not configured (EMAIL_ADDRESS, EMAIL_PASSWORD, EMAIL_SMTP_HOST required)"} try: - msg = MIMEText(message, "plain", "utf-8") + # Build multipart/alternative with plain + HTML + msg = _MIMEMultipart() msg["From"] = address msg["To"] = chat_id msg["Subject"] = "Hermes Agent" msg["Date"] = formatdate(localtime=True) - server = smtplib.SMTP(smtp_host, smtp_port) - server.starttls(context=_ssl.create_default_context()) + # Plain text part (always) + alt = _MIMEMultipart("alternative") + alt.attach(MIMEText(message, "plain", "utf-8")) + + # HTML part (when markdown is available and html_format enabled) + if html_format: + try: + import markdown + html_body = markdown.markdown( + message, extensions=["tables", "fenced_code", "nl2br"] + ) + html_body = _style_html_email(_HTML_PREFIX + html_body + _HERMES_EMAIL_FOOTER) + alt.attach(MIMEText(html_body, "html", "utf-8")) + except ImportError: + pass # no markdown lib, send plain only + except Exception: + pass # HTML conversion failed, send plain only + + msg.attach(alt) + + # Port 465 uses implicit TLS (SMTP_SSL), others use STARTTLS + ctx = _ssl.create_default_context() + if smtp_port == 465: + server = smtplib.SMTP_SSL(smtp_host, smtp_port, timeout=30, context=ctx) + else: + server = smtplib.SMTP(smtp_host, smtp_port, timeout=30) + server.starttls(context=ctx) server.login(address, password) server.send_message(msg) server.quit() @@ -1266,7 +1453,7 @@ def register(ctx) -> None: allow_all_env="EMAIL_ALLOW_ALL_USERS", cron_deliver_env_var="EMAIL_HOME_ADDRESS", standalone_sender_fn=_standalone_send, - max_message_length=50_000, + max_message_length=200_000, pii_safe=True, emoji="📧", allow_update_command=True, diff --git a/tests/test_email_html.py b/tests/test_email_html.py new file mode 100644 index 0000000000000..09f7409530be5 --- /dev/null +++ b/tests/test_email_html.py @@ -0,0 +1,342 @@ +"""Tests for HTML email rendering in the email platform adapter. + +Covers: +- _style_html_email: inline CSS injection,
 override
+- _attach_body: multipart/alternative wrapping
+- _create_body_part: multipart/alternative for attachment paths
+- html_format config: opt-in/opt-out behavior
+- Pre-existing HTML detection and preamble stripping
+- Port 465 SMTP_SSL handling
+"""
+
+import pytest
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from unittest.mock import MagicMock, patch
+
+
+# Import the module under test
+import sys
+import os
+
+# Ensure the repo root is on sys.path so plugin imports resolve
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from plugins.platforms.email.adapter import (
+    _style_html_email,
+    _HTML_PREFIX,
+    _HERMES_EMAIL_FOOTER,
+    _HERMES_EMAIL_ELEMENT_STYLES,
+)
+
+
+class TestStyleHtmlEmail:
+    """Tests for _style_html_email() inline CSS injection."""
+
+    def test_code_inside_pre_gets_transparent_style(self):
+        """ inside 
 must get transparent background, not the default inline-code style."""
+        html = '
print("hello")
' + result = _style_html_email(html) + # The inside
 should have transparent background
+        assert 'background:transparent' in result
+        assert 'padding:0' in result
+        # Should NOT have the default inline-code background
+        assert 'background:#edf2f7' not in result.split(' outside 
 gets the inline-code background style."""
+        html = '

Use foo() here

' + result = _style_html_email(html) + assert 'background:#edf2f7' in result + assert 'border-radius:3px' in result + + def test_h1_gets_style(self): + """Heading tags get styled.""" + html = '

Title

' + result = _style_html_email(html) + assert 'font-size:24px' in result + assert 'border-bottom:2px solid #667eea' in result + + def test_pre_code_order_matters(self): + """The
 override must run before the general  loop."""
+        html = '
x = 1

inline y

' + result = _style_html_email(html) + # Split at
to isolate pre content from inline content + pre_part = result.split('
')[0] + rest_part = result.split('
')[1] if '
' in result else '' + # pre code should be transparent + assert 'background:transparent' in pre_part + # inline code should have the standard background + if rest_part: + assert 'background:#edf2f7' in rest_part + + def test_no_double_style_attribute(self): + """Elements that already have style= are not double-styled.""" + html = '

already styled

' + result = _style_html_email(html) + # Should not add a second style= attribute + assert result.count('style=') == 1 + + def test_table_gets_style(self): + """Table elements get styled.""" + html = '
cell
' + result = _style_html_email(html) + assert 'border-collapse:collapse' in result + + +class TestAttachBody: + """Tests for EmailAdapter._attach_body() MIME structure.""" + + def _make_adapter(self, html_format=True): + """Create a minimal EmailAdapter mock with html_format config.""" + from plugins.platforms.email.adapter import EmailAdapter + from gateway.config import PlatformConfig + + config = PlatformConfig.from_dict( + {"extra": {"address": "test@test.com", "html_format": html_format}}, + ) + # Mock the __init__ to skip env var resolution + with patch.object(EmailAdapter, '__init__', lambda self, *a, **kw: None): + adapter = EmailAdapter.__new__(EmailAdapter) + adapter._html_format = html_format + adapter._address = "test@test.com" + return adapter + + def test_attach_body_creates_multipart_alternative(self): + """_attach_body should wrap body in multipart/alternative.""" + adapter = self._make_adapter(html_format=False) + msg = MIMEMultipart() + adapter._attach_body(msg, "Hello") + + # The root msg should have one child: multipart/alternative + parts = msg.get_payload() + assert len(parts) == 1 + assert parts[0].get_content_type() == "multipart/alternative" + + def _decode_payload(self, part): + """Decode a MIME part's payload, handling base64 encoding.""" + decoded = part.get_payload(decode=True) + if decoded: + return decoded.decode("utf-8", errors="replace") + return part.get_payload() + + def test_attach_body_with_html_disabled(self): + """With html_format=False, alternative part has only text/plain.""" + adapter = self._make_adapter(html_format=False) + msg = MIMEMultipart() + adapter._attach_body(msg, "Hello **world**") + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + assert len(payloads) == 1 + assert payloads[0].get_content_type() == "text/plain" + assert self._decode_payload(payloads[0]) == "Hello **world**" + + def test_attach_body_with_html_enabled(self): + """With html_format=True, alternative part has text/plain + text/html.""" + adapter = self._make_adapter(html_format=True) + msg = MIMEMultipart() + adapter._attach_body(msg, "Hello **world**") + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + assert len(payloads) == 2 + assert payloads[0].get_content_type() == "text/plain" + assert payloads[1].get_content_type() == "text/html" + html_content = self._decode_payload(payloads[1]) + assert " multipart/alternative.""" + adapter = self._make_adapter(html_format=True) + msg = MIMEMultipart() + adapter._attach_body(msg, "Hello **world**") + + assert msg.get_content_type() == "multipart/mixed" + body_part = msg.get_payload()[0] + assert body_part.get_content_type() == "multipart/alternative" + alt_payloads = body_part.get_payload() + assert len(alt_payloads) == 2 + assert alt_payloads[0].get_content_type() == "text/plain" + assert alt_payloads[1].get_content_type() == "text/html" + + def test_attachment_path_produces_correct_structure(self): + """_create_body_part inside multipart/mixed mimics real attachment flow.""" + adapter = self._make_adapter(html_format=True) + msg = MIMEMultipart() + body_part = adapter._create_body_part("Body with **bold**") + msg.attach(body_part) + + assert msg.get_content_type() == "multipart/mixed" + alt = msg.get_payload()[0] + assert alt.get_content_type() == "multipart/alternative" + + +class TestPreExistingHTML: + """Tests for HTML that's already in the body (from cron/model output).""" + + def _make_adapter(self, html_format=True): + from plugins.platforms.email.adapter import EmailAdapter + with patch.object(EmailAdapter, '__init__', lambda self, *a, **kw: None): + adapter = EmailAdapter.__new__(EmailAdapter) + adapter._html_format = html_format + return adapter + + def _decode_payload(self, part): + decoded = part.get_payload(decode=True) + if decoded: + return decoded.decode("utf-8", errors="replace") + return part.get_payload() + + def test_html_document_with_preamble(self): + """HTML document with preamble text → preamble stripped, sent as HTML.""" + adapter = self._make_adapter() + body = "Here is your daily briefing:\n

Report

" + msg = MIMEMultipart() + adapter._attach_body(msg, body) + + alt = msg.get_payload()[0] + assert alt.get_content_type() == "multipart/alternative" + payloads = alt.get_payload() + assert len(payloads) == 2 + assert payloads[0].get_content_type() == "text/plain" + assert payloads[1].get_content_type() == "text/html" + html_content = self._decode_payload(payloads[1]) + assert html_content.startswith("") + assert "daily briefing" not in html_content + + def test_html_fragment_no_html_close(self): + """HTML fragment (no ) → trailing commentary stripped.""" + adapter = self._make_adapter() + body = "

Status

OK

\n\nThe report above shows the current status." + msg = MIMEMultipart() + adapter._attach_body(msg, body) + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + html_content = self._decode_payload(payloads[1]) + assert html_content.endswith("") + assert "report above" not in html_content + + def test_duplicate_html_close_uses_first(self): + """Duplicate — first occurrence is used.""" + adapter = self._make_adapter() + body = "

Hello

\ngarbage\n" + msg = MIMEMultipart() + adapter._attach_body(msg, body) + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + html_content = self._decode_payload(payloads[1]) + assert html_content.count("") == 1 + + def test_plain_text_not_detected_as_html(self): + """Plain text body → sent as plain text, not HTML.""" + adapter = self._make_adapter(html_format=False) + body = "Hello Felix,\n\nYour daily briefing is ready." + msg = MIMEMultipart() + adapter._attach_body(msg, body) + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + assert len(payloads) == 1 + assert payloads[0].get_content_type() == "text/plain" + + +class TestHtmlFormatOptOut: + """Tests for html_format=False opt-out behavior.""" + + def _make_adapter(self, html_format=True): + from plugins.platforms.email.adapter import EmailAdapter + with patch.object(EmailAdapter, '__init__', lambda self, *a, **kw: None): + adapter = EmailAdapter.__new__(EmailAdapter) + adapter._html_format = html_format + return adapter + + def _decode_payload(self, part): + decoded = part.get_payload(decode=True) + if decoded: + return decoded.decode("utf-8", errors="replace") + return part.get_payload() + + def test_pre_existing_html_opt_out(self): + """html_format=False should send pre-existing HTML as plain text.""" + adapter = self._make_adapter(html_format=False) + body = "

Report

" + msg = MIMEMultipart() + adapter._attach_body(msg, body) + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + # Should have only plain text (HTML stripped to plain) + assert len(payloads) == 1 + assert payloads[0].get_content_type() == "text/plain" + + def test_html_fragment_opt_out(self): + """html_format=False should send HTML fragments as plain text.""" + adapter = self._make_adapter(html_format=False) + body = "

Status

OK

" + msg = MIMEMultipart() + adapter._attach_body(msg, body) + + alt = msg.get_payload()[0] + payloads = alt.get_payload() + assert len(payloads) == 1 + assert payloads[0].get_content_type() == "text/plain" + + +class TestStandaloneSendPort465: + """Tests for standalone send path port 465 handling.""" + + def test_standalone_send_uses_smtp_ssl_for_port465(self): + """_standalone_send should use SMTP_SSL for port 465.""" + import inspect + from plugins.platforms.email.adapter import _standalone_send + source = inspect.getsource(_standalone_send) + assert "SMTP_SSL" in source, "_standalone_send should use SMTP_SSL for port 465" + assert "smtp_port == 465" in source, "_standalone_send should check port 465" + + def test_standalone_send_reads_html_format(self): + """_standalone_send should read html_format from config.""" + import inspect + from plugins.platforms.email.adapter import _standalone_send + source = inspect.getsource(_standalone_send) + assert "html_format" in source, "_standalone_send should read html_format setting" diff --git a/website/docs/user-guide/messaging/email.md b/website/docs/user-guide/messaging/email.md index eabde5da496fc..c7fa77e0ef9d7 100644 --- a/website/docs/user-guide/messaging/email.md +++ b/website/docs/user-guide/messaging/email.md @@ -120,7 +120,30 @@ Replies are sent via SMTP with proper email threading: - **In-Reply-To** and **References** headers maintain the thread - **Subject line** preserved with `Re:` prefix (no double `Re: Re:`) - **Message-ID** generated with the agent's domain -- Responses are sent as plain text (UTF-8) +- Responses are sent as **multipart/alternative** with both plain text and HTML (when `html_format: true`, the default) +- HTML emails use inline CSS for maximum client compatibility (Gmail, Outlook, Apple Mail) +- If the model output already contains HTML (e.g., from cron jobs), it is detected and sent as HTML with preamble stripping +- Port 465 uses implicit TLS (SMTP_SSL), other ports use STARTTLS + +#### HTML Format Configuration + +By default, email responses include rich HTML formatting. To disable HTML and send plain text only: + +```yaml +platforms: + email: + extra: + html_format: false +``` + +When `html_format: true` (default): +- Markdown content is converted to styled HTML with inline CSS +- Pre-existing HTML in model output is detected and sent as-is +- Both plain text and HTML parts are wrapped in `multipart/alternative` + +When `html_format: false`: +- All content is sent as plain text only +- HTML tags in model output are stripped ### File Attachments