feat(email): Markdown-to-HTML rendering for outbound emails

[swissly]

What does this PR do?

Adds automatic Markdown-to-HTML rendering for all outbound emails. Sends emails as multipart/alternative with both text/plain (raw body) and text/html (styled HTML), so HTML-capable clients render rich formatting while plain-text clients fall back gracefully.

Addresses: Closes #11941 (2 reactions), also related to #25439.

How it works

1. _markdown_to_html_email(body) converts Markdown to HTML using the markdown library (tables, fenced code, nl2br), then injects inline CSS per element (because Gmail strips <style> blocks).

2. All 3 send paths use new helpers:

   • _send_email uses _attach_body(msg, body) — plain + HTML parts on MIMEMultipart("alternative")
   • _send_email_with_attachment uses _create_body_part(body) — wrapped in multipart/alternative inside multipart/mixed
   • _send_email_with_attachments — same wrapper pattern

3. Config opt-out: platforms.email.html_format: false disables HTML and keeps plain-text-only behavior (default: true).

4. Graceful fallback: if markdown is not installed or conversion fails, plain text is sent as before.

Why inline CSS instead of style blocks

Gmail (both web and mobile) strips <style> tags from emails. Every style must be on the element itself. This is a well-known email development constraint.

Design decisions

• Lazy import markdown: Avoids hard dependency — email adapter loads even if markdown is not installed. Falls back to plain text.
• Inline CSS per element: Gmail compatibility — <style> blocks are stripped.
• html_format: true default: Rich email is the better default. Users who want plain-only can opt out.
• MIMEMultipart("alternative"): Standard email multipart for plain+HTML — all clients understand it.

Changes Made

• gateway/platforms/email.py:
  • Add _HERMES_EMAIL_HTML_TEMPLATE — responsive HTML wrapper
  • Add _HERMES_EMAIL_STYLES — inline CSS map for 17 HTML elements
  • Add _markdown_to_html_email() — Markdown to HTML to styled HTML
  • Add EmailAdapter._attach_body() — attach plain+HTML to a message
  • Add EmailAdapter._create_body_part() — wrap body for multipart/mixed (attachments)
  • Modify __init__: read html_format from config.extra (default: true)
  • Modify _send_email: use MIMEMultipart("alternative") + _attach_body
  • Modify _send_email_with_attachment: use _create_body_part
  • Modify _send_email_with_attachments: use _create_body_part

How to Test

# Unit: syntax + import check
python3 -c "from gateway.platforms.email import _markdown_to_html_email; print(_markdown_to_html_email('**bold** and *italic*'))"

# E2E: send a message via email, check:
# - Gmail: renders headings, bold, tables, code blocks
# - Apple Mail: same
# - Thunderbird: same
# - Plain-text client (mutt): sees raw Markdown (unchanged)

Checklist

• Only gateway/platforms/email.py touched (1 file, 84 insertions, 4 deletions)
• Lazy import — no hard dependency added to pyproject.toml
• Config opt-out available (html_format: false)
• Graceful fallback: markdown missing leads to plain text; conversion error leads to plain text + warning
• All 3 send paths updated
• Conventional Commits format (feat(email): ...)
• Cross-platform: pure Python email.mime + markdown library, no OS-specific code
• No tool schema change

MIME Structure

With html_format: true (default):

multipart/alternative
+-- text/plain   (raw Markdown body)
+-- text/html    (styled HTML with inline CSS)

With attachments:

multipart/mixed
+-- multipart/alternative
|   +-- text/plain
|   +-- text/html
+-- application/octet-stream (attachment)

With html_format: false:

text/plain   (unchanged from current behavior)

Note on markdown dependency

The markdown library is a lightweight pure-Python package (~100KB, no transitive deps, widely used by Django/MkDocs/Jupyter). It is lazily imported — the email adapter loads and works even if markdown is not installed (falls back to plain text). If the maintainers prefer, it can be added to pyproject.toml as an exact-pinned dependency or moved to an optional extra.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds optional HTML email formatting by converting Markdown bodies into styled HTML and attaching both plain-text and HTML parts to outgoing emails.

Changes:

• Introduced Markdown→HTML conversion with an inline-styled HTML wrapper template.
• Added platforms.email.html_format config toggle (default enabled).
• Refactored email body attachment logic to use multipart/alternative (and nested alternative parts for attachments).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[swissly]

Copilot Review Fixes (from #46642)

Applied these fixes in my duplicate PR — contributing them here:

1. Regex: style= anywhere in tag

Current code matches style= only as first attribute. Tags like <p class="x" style="..."> get duplicate style.

# Current (broken for existing style= not-first):
html = re.sub(rf'<{tag}(\s|>)', rf'<{tag} {style}\1', html)

# Fixed (checks [^>]* for style= anywhere):
html = re.sub(rf'<{tag}(?![^>]*style=)(\s|>)', rf'<{tag} {style}\1', html)

2. Markdown validation in init

Auto-disable HTML if markdown not installed (one warning, not per-send):

self._html_format = extra.get('html_format', True)
if self._html_format:
    try:
        import markdown  # noqa: F401
    except ImportError:
        logger.warning('[Email] markdown not installed — HTML disabled')
        self._html_format = False

3. Security comment

Document why no bleach (self-to-self, config kill-switch):

# SECURITY NOTE: We intentionally do NOT sanitize with bleach because:
#   1. Hermes generates its own email bodies (LLM output, not user input)
#   2. Emails are sent to the configured address (self-to-self)
#   3. The config toggle provides a kill-switch: set html_format: false

4. Naming

_HERMES_EMAIL_HTML_TEMPLATE is fine, but consider _HTML_PREFIX + _HTML_FOOTER for the split parts (avoids .replace() on template).

Verified

• Syntax check passed
• multipart/alternative structure correct
• RFC-compliant email structure

[swissly]

Superseded by #54073 which targets the new plugins/platforms/email/adapter.py path (the email adapter was migrated from gateway/platforms/ since this PR was opened).

Closing in favor of #54073.

[swissly]

Superseded by #54107 (clean PR targeting the new plugin path at plugins/platforms/email/adapter.py, with consolidated HTML helpers and no bundled unrelated changes).

[swissly]

Superseded by #73294 — ported to plugins/platforms/email/adapter.py (live path) with all 4 send paths including _standalone_send.