add email-version hook to override detected Connect version

Author: juleswg23

src/resources/filters/modules/connectversion.lua

@@ -4,6 +4,20 @@ Connect version sniffing utilities for email extension
 Functions to detect and compare Posit Connect versions from environment variables
 ]]
 
+-- Get email format version override from metadata
+-- Can be set in YAML as: 
+--   format:
+--     email:
+--       email-version: 2
+-- Returns: version string (e.g., "2") if override is set, nil otherwise
+function get_email_format_override(meta)
+  if meta and meta["email-version"] then
+    return pandoc.utils.stringify(meta["email-version"])
+  end
+
+  return nil
+end
+
 -- Parse Connect version from SPARK_CONNECT_USER_AGENT
 -- Format:  posit-connect/2024.09.0
 --          posit-connect/2024.09.0-dev+26-dirty-g51b853f70e
@@ -70,5 +84,6 @@ end
 
 -- Export functions for module usage
 return {
-  is_connect_version_at_least = is_connect_version_at_least
+  is_connect_version_at_least = is_connect_version_at_least,
+  get_email_format_override = get_email_format_override
 }

src/resources/filters/quarto-post/email.lua

@@ -347,10 +347,22 @@ function process_document(doc)
     return doc
   end
 
-  -- Detect format upfront: Check Connect version and look for document-level metadata
-  -- This must be determined before processing to avoid confusion about which format to use
-  if connectversion.is_connect_version_at_least(constants.kConnectEmailMetadataChangeVersion) then
-    connect_supports_v2 = true
+  -- Check for explicit email format override first
+  local format_override = connectversion.get_email_format_override(doc.meta)
+  if format_override then
+    -- If override is set, interpret the value as a string
+    if format_override == "2" then
+      connect_supports_v2 = true
+      io.stderr:write("WARNING: Email format v2 is being forced via 'format.email.version: " .. format_override .. "' in YAML. This overrides the Connect version detection.\n")
+    else
+      connect_supports_v2 = false
+      io.stderr:write("WARNING: Email format v1 is being forced via 'format.email.version: " .. format_override .. "' in YAML. This overrides the Connect version detection.\n")
+    end
+  else
+    -- Fall back to version sniffing if no explicit override
+    if connectversion.is_connect_version_at_least(constants.kConnectEmailMetadataChangeVersion) then
+      connect_supports_v2 = true
+    end
   end
 
   -- Scan for document-level metadata at the TOP LEVEL of the document

src/resources/schema/document-email.yml

@@ -0,0 +1,12 @@
+- name: email-version
+  tags:
+    formats: [email]
+  schema:
+    enum: [1, 2]
+  description:
+    short: "Email format version"
+    long: |
+      Specifies which email format version to use.
+      
+      - `1`: Legacy email format with document-level metadata (compatible with older Connect versions)
+      - `2`: New email format with multiple individual emails and v2 markers (requires Posit Connect 2026.03 or later)

tests/docs/email/email-force-v2.qmd

@@ -0,0 +1,28 @@
+---
+title: Email Test Document
+author: Charles Teague
+format: 
+  email:
+    email-version: 2
+---
+
+The report content. Anything that is here is not part of the email message.
+
+::: {.email}
+
+::: {.subject}
+The subject line.
+:::
+
+::: {.email-text}
+An optional text-only version of the email message..
+:::
+
+The HTML email content. Here you can add code cells, produce images, and write accompanying text.
+This content is not seen when viewing the rendered document on Connect (it's only
+seen when sending an email from the Connect document page). Emails from Connect
+can be sent manually, and they can also be scheduled.
+
+:::
+
+Any additional report content not part of the email message.

tests/smoke/render/render-email.test.ts

@@ -183,6 +183,23 @@ testRender(docs("email/email-multi-v2.qmd"), "email", false, [
   }
 });
 
+// Test v2 format override with old Connect version
+// Uses email-format: v2 in YAML to force v2 despite old Connect version
+testRender(docs("email/email-force-v2.qmd"), "email", false, [fileExists(previewFileV2_1), validJsonWithMultipleEmails(jsonFile, 1, {
+  "0": {
+    "email_id": 1,
+    "subject": "The subject line.",
+    "attachments": [],
+    "suppress_scheduled": false,
+    "send_report_as_attachment": false
+  }
+})], {
+  ...cleanupCtx,
+  env: {
+    "SPARK_CONNECT_USER_AGENT": "posit-connect/2024.09.0"
+  }
+});
+
 // Test mixed metadata - some emails have metadata, others don't
 testRender(docs("email/email-mixed-metadata-v2.qmd"), "email", false, [
   fileExists(previewFileV2_1),