goodmail 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa74c986faf7a129fa8daa4546192918312488290ad46aff8f889009efdefbe4
-  data.tar.gz: 9d138231f61b68a137a2726b989788bd180d7c15e6fa6a4f414c929243c8b343
+  metadata.gz: 97d19566a8e8eacb10fed28cddfbe7c9f254ae6f4df4b0c2a8ad5259d646631d
+  data.tar.gz: a15578a0b463e3372ffeff6f9d0a2b0aaa3754c0cf604cc574a97fb0506545fe
 SHA512:
-  metadata.gz: 66d62b19ff6baebd3512bc3d04f60b0b329fec2e36b90ccd8cc9701a955206b91f73f86af4ccdb9a74501f0e05d4f36c948d1683b54049fdebf821244965331c
-  data.tar.gz: a1c74368751fc8c5701f6aefc588a118ac1839691d5657475024343e0b007646271e9ffe1b7c23294245dfaedde263e421a4b24418a3df0fc74998a983f49ab3
+  metadata.gz: 8ec18e8bc6a78545259c5a359b1811fa7df18cccdca0df36761b94db25304ea9f894ae85cbddbeb54c674526ad7eb5c5a80e24767f7bd97d23baa692ab02aa5f
+  data.tar.gz: d384ec22ed4107cb20c73deff523e15b3d5dcaf7c3d5a464030024336fde15e6346f5f02f90673e23d6790e085db70782b2a2e0df783dbd7db8ad23908b8e3ff

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.2.0] - 2025-05-02
+
+### Added
+
+- **New DSL Methods:** Added `code_box` and `price_row` for displaying formatted content like license keys or simple line items.
+- **Configuration Validation:** Added validation to ensure required config keys (`company_name`, `brand_color`) are set on application startup.
+- **Clickable Logo:** Added `config.company_url` to make the header logo clickable.
+- **Preheader Text:** Added support for hidden preheader text via `config.default_preheader` and `headers[:preheader]`.
+- **Schema.org Microdata:** Included basic Schema.org (`EmailMessage`, `ConfirmAction`) markup in the layout template for potential enhancements in email clients (like Gmail action buttons).
+
+### Fixed
+
+- Resolved Action Mailer errors related to template lookups and `deliver_later` safety checks.
+- Correctly added `.html_safe` to MSO conditional comment wrappers in Builder to prevent Rails from escaping them.
+- Corrected plaintext generation issues related to image alt text and signatures.
+
 ## [0.1.0] - 2025-05-02
 
 - Initial release

data/README.md

@@ -1,10 +1,14 @@
-# 💌 Goodmail - Make your transactional emails look beautiful
-[![Gem Version](https://badge.fury.io/rb/pay.svg)](https://badge.fury.io/rb/pay)
+# 💌 Goodmail - Make your Rails SaaS transactional emails look beautiful
+[![Gem Version](https://badge.fury.io/rb/goodmail.svg)](https://badge.fury.io/rb/goodmail)
 
 Send beautiful, simple transactional emails with zero HTML hell.
 
 Goodmail turns your ugly, default, text-only emails into SaaS-ready emails. It's an opinionated, minimal, expressive Ruby DSL for sending beautiful, production-grade transactional emails in Rails apps — no templates, no partials, no HTML hell. The template works well and looks nice across email clients.
 
+![Goodmail Example Email](mailgood.webp)
+
+You can easily add buttons, images, links, price lines, and text to your emails, and it'll look good everywhere, no styling needed.
+
 Here's the catch: there's only one template. You can't change it. You're guaranteed you'll send good emails, but the cost is you don't have much flexibility. If you're okay with this, welcome to `goodmail`! You'll be shipping decent emails that look great everywhere in no time.
 
 (And you can still use Action Mailer for all other template-intensive emails – Goodmail doesn't replace Action Mailer, just builds on top of it!)
@@ -25,39 +29,54 @@ bundle install
 
 ## Configuration
 
-You can (and should!) edit the default strings in the Goodmail initializer.
+Goodmail requires minimal configuration to ensure emails look correct. You **must** set at least your `company_name`.
 
-Create an initializer file at `config/initializers/goodmail.rb`:
+Create an initializer file at `config/initializers/goodmail.rb` and configure the options:
 
 ```ruby
 # config/initializers/goodmail.rb
 
 Goodmail.configure do |config|
-  # The main accent color used for buttons and links in the email body.
-  # Default: "#348eda"
-  config.brand_color = "#E62F17" # Your brand's primary color
+  # --- Basic Branding (Required) --- 
 
-  # The company name displayed in the email footer and used by the default `sign` helper.
-  # Default: "Example Inc."
+  # The company name displayed in the email footer and used by `sign` helper.
+  # NOT OPTIONAL - MUST BE SET
   config.company_name = "MyApp Inc."
 
-  # Optional: URL to your company logo. If set, it will appear centered in the header.
-  # Recommended size: max-height 30px.
+  # --- Optional Branding --- 
+
+  # The main accent color used for buttons and links in the email body.
+  config.brand_color = "#E62F17"
+
+  # Optional: URL to your company logo. If set, it will appear in the header.
   # Default: nil
   config.logo_url = "https://cdn.myapp.com/images/email_logo.png"
 
-  # Optional: Custom text displayed in the footer below the copyright.
-  # Use this to explain why the user received the email.
+  # Optional: URL the header logo links to (e.g., your homepage).
+  # Ignored if logo_url is not set. Must be a valid URL (no spaces etc.).
   # Default: nil
-  config.footer_text = "You are receiving this email because you signed up for an account at MyApp."
+  config.company_url = "https://myapp.com"
+
+  # --- Optional Email Content Defaults --- 
 
-  # Optional: Global default URL for unsubscribe links (both the List-Unsubscribe
-  # header and the optional visible link in the footer).
+  # Optional: Default preheader text (appears after subject in inbox preview).
+  # Can be overridden per email via headers[:preheader]. If unset, subject is used.
+  # Default: nil
+  config.default_preheader = "Your account update from MyApp."
+
+  # Optional: Global default URL for unsubscribe links.
   # Goodmail *does not* handle the unsubscribe logic; you must provide a valid URL.
   # Can be overridden per email via headers[:unsubscribe_url].
   # Default: nil
   config.unsubscribe_url = "https://myapp.com/emails/unsubscribe"
 
+  # --- Optional Footer Customization --- 
+
+  # Optional: Custom text displayed in the footer below the copyright.
+  # Use this to explain why the user received the email.
+  # Default: nil
+  config.footer_text = "You are receiving this email because you signed up for an account at MyApp."
+
   # Optional: Whether to show a visible unsubscribe link in the footer.
   # Requires an unsubscribe URL to be set (globally or per-email).
   # Default: false
@@ -69,21 +88,34 @@ Goodmail.configure do |config|
 end
 ```
 
+*The application will raise an error on startup if required configuration keys (`company_name`) are missing or blank.*
+
 Make sure to restart your Rails server after creating or modifying the initializer.
 
 ## Quick start
 
-Use the `Goodmail.compose` method to compose emails using the DSL, then call `.deliver_now` or `.deliver_later` on it (your usual standard Action Mailer methods)
+Use the `Goodmail.compose` method to compose emails using the DSL, then call `.deliver_now` or `.deliver_later` on it.
 
-### Basic Example
+### Basic Example (Deliver Now)
 
 ```ruby
-# In a controller action, background job, or service object
-Goodmail.compose(to: user.email, subject: "Welcome!") do
-  greeting "Hey #{user.first_name},"
-  text     "Thanks for joining. Confirm below:"
-  button   "Confirm account", confirm_url
-end.deliver_now
+# Assumes config/initializers/goodmail.rb is configured!
+recipient = User.find(params[:user_id])
+
+mail = Goodmail.compose(
+  to: recipient.email,
+  from: "'#{Goodmail.config.company_name} Support' <support@myapp.com>",
+  subject: "Welcome to MyApp!",
+  preheader: "Your adventure begins now!" # Optional override
+) do
+  h1 "Welcome aboard, #{recipient.name}!"
+  text "We're thrilled to have you join the MyApp community."
+  text "Here are a few things: Check the <a href=\"/help\">Help Center</a>."
+  button "Go to Dashboard", user_dashboard_url(recipient)
+  sign
+end
+
+mail.deliver_now
 ```
 
 ### Deliver Later (Background Job)
@@ -102,52 +134,135 @@ mail.deliver_later
 
 *(Requires Active Job configured.)*
 
+## Why does `goodmail` exist?
+
+Here's the problem: you can't just use standard HTML and CSS in mails.
+
+Emails are notoriously complicated to work with, because they're very difficult to style.
+
+Modern CSS doesn't work in mails, because email clients render styles differently and some only support a primitive subset of HTML / CSS.
+
+So, for example, you can't use stylesheets **at all**: all CSS needs to be inlined. You can't use many modern CSS properties either.
+
+This is why many emails still use `<table>` elements, for example. It's the only way of making mails look good!
+
+In fact, Mailgun released years ago [a few battle-tested HTML templates for emails](https://github.com/mailgun/transactional-email-templates). I took one of those email templates and have been using it in my projects for years.
+
+So, can't this just be an Action Mailer `.erb` template instead?
+
+I thought the same! And that's actually how I started using it. But after using it for years I realized I ended up building my own "proto-DSL" around it: I decomposed the email HTML template in partials, I was copying the same partials from project to project, etc. And setting up good emails in every new project took me a while because each project would have slight inconsistencies in the mail partials.
+
+So making it into a gem with a simple DSL was my solution to solve this email HTML mess.
+
+## Usage
+
 ### Available DSL Methods
 
 Inside the `Goodmail.compose` block, you have access to these methods:
 
 *   `h1(text)`, `h2(text)`, `h3(text)`: Styled heading tags.
-*   `text(string)`: A paragraph of text. Handles `\n` for line breaks. Allows simple inline `<a>` tags with `href` attributes; other HTML is stripped for safety.
-*   `button(link_text, url)`: A prominent, styled call-to-action button.
-*   `image(src, alt = "", width: nil, height: nil)`: Embeds an image, centered by default.
+*   `text(string)`: A paragraph of text. Allows simple inline `<a>` tags with `href` attributes; other HTML is stripped for safety. Handles `\n` for line breaks.
+*   `button(link_text, url)`: A prominent, styled call-to-action button (includes Outlook VML fallback).
+*   `image(src, alt = "", width: nil, height: nil)`: Embeds an image, centered by default (includes Outlook MSO fallback). Uses `config.company_name` for alt text if none provided.
 *   `space(pixels = 16)`: Adds vertical whitespace.
 *   `line`: Adds a horizontal rule (`<hr>`).
 *   `center { ... }`: Centers the content generated within the block.
+*   `code_box(text)`: Displays text centered and bold within a styled box (grey background, padding, italic). Text is HTML-escaped.
+*   `price_row(name, price)`: Adds a styled paragraph showing a name and price, separated by a top border (e.g., for simple receipt line items). Text is HTML-escaped.
 *   `sign(name = Goodmail.config.company_name)`: Adds a standard closing signature line.
-*   `html(raw_html_string)`: **Use with extreme caution.** Allows embedding raw, *un-sanitized* HTML. Only use this if you absolutely trust the source of the string.
+*   `html(raw_html_string)`: **Use with extreme caution.** Allows embedding raw, *un-sanitized* HTML.
+
+### Advanced: Rendering Email Parts with `Goodmail.render`
+
+For more advanced use cases, such as integrating Goodmail's content generation into existing mailer workflows (like Devise mailers) or when you need direct access to the generated HTML and plain text parts before sending, Goodmail provides the `Goodmail.render` method.
+
+This method processes your DSL block, applies the layout, runs Premailer for CSS inlining, and performs plain text cleanup, similar to `Goodmail.compose`. However, instead of returning a `Mail::Message` object ready for delivery, it returns a `Goodmail::EmailParts` struct.
+
+The `Goodmail::EmailParts` struct (defined in `goodmail/email.rb`) has two attributes:
+*   `html`: The final, inlined HTML content for your email.
+*   `text`: The cleaned-up plain text version of your email.
+
+**How to use it:**
+
+You can then use these parts within any Action Mailer setup:
+
+```ruby
+# In your custom mailer (e.g., a Devise mailer override)
+
+# Define your headers (to, from, subject, etc.)
+# The :subject is crucial for Goodmail.render.
+# You can also pass :unsubscribe_url and :preheader to Goodmail.render
+# to override global configurations for that specific email.
+# Note: these Goodmail-specific keys will be used by Goodmail.render
+# and should not be passed directly to ActionMailer's mail() method
+# if they are not standard mail headers.
+mail_rendering_headers = {
+  to: recipient.email,
+  from: "notifications@myapp.com",
+  subject: "Important Update for #{recipient.name}",
+  unsubscribe_url: custom_unsubscribe_url_for_user(recipient), # Optional
+  preheader: "A quick update you should see." # Optional
+}
+
+# Render the email parts using Goodmail's DSL
+# Goodmail.render will use :subject, :unsubscribe_url, :preheader internally.
+parts = Goodmail.render(mail_rendering_headers) do
+  h1 "Hello, #{recipient.name}!"
+  text "This is an important update regarding your account."
+  button "View Details", view_details_url(recipient)
+  sign "The MyApp Team"
+end
+
+# Prepare headers for ActionMailer's mail() method,
+# ensuring only standard mail headers are passed.
+action_mailer_headers = mail_rendering_headers.slice(:to, :from, :subject, :cc, :bcc, :reply_to)
+
+# Now use these parts in ActionMailer's mail method
+# You might also want to add the List-Unsubscribe header manually here if needed.
+final_mail_object = mail(action_mailer_headers) do |format|
+  format.html { render html: parts.html.html_safe }
+  format.text { render plain: parts.text }
+end
+
+# The `final_mail_object` returned by ActionMailer can then be delivered:
+# final_mail_object.deliver_now or final_mail_object.deliver_later
+```
+
+**Key Differences from `Goodmail.compose`:**
+
+*   **Return Value**: `Goodmail.render` returns an instance of `Goodmail::EmailParts` (e.g., `EmailParts.new(html: "...", text: "...")`). `Goodmail.compose` returns a `Mail::Message` object.
+*   **Purpose**: `Goodmail.render` is primarily for generating and retrieving processed email content parts. `Goodmail.compose` is for generating a complete, deliverable `Mail::Message` object.
+*   **List-Unsubscribe Header**: `Goodmail.render` itself does *not* add the `List-Unsubscribe` header to any mail object (as it doesn't create one). If you use `Goodmail.render`, you are responsible for adding this header to your `Mail::Message` object if an `unsubscribe_url` was effectively used during rendering (either passed to `Goodmail.render` or taken from global config) and you require this header. The internal `Goodmail::Mailer` (used by `Goodmail.compose`) handles adding this header automatically to the `Mail::Message` object it builds.
 
 ### Adding Unsubscribe Functionality
 
-Goodmail helps you add the `List-Unsubscribe` header and an optional visible link, but **you must provide the actual URL** where users can unsubscribe. Goodmail does not generate unsubscribe URLs or handle the logic.
+Goodmail helps you add the `List-Unsubscribe` header and an optional visible link, but **you must provide the actual URL** where users can unsubscribe.
 
-1.  **Provide the URL:** You have two options:
-    *   **Globally:** Set `config.unsubscribe_url = "your_global_url"` in the initializer (`config/initializers/goodmail.rb`).
-    *   **Per-Email:** Pass `unsubscribe_url: "your_specific_url"` in the headers hash when calling `Goodmail.compose`. This overrides the global setting for that email.
+1.  **Provide the URL:**
+    *   **Globally:** Set `config.unsubscribe_url = "your_global_url"`.
+    *   **Per-Email:** Pass `unsubscribe_url: "your_specific_url"` in the headers hash. This overrides the global setting.
 
     ```ruby
-    # Example using per-email override
     mail = Goodmail.compose(
       to: recipient.email,
+      unsubscribe_url: manage_subscription_url(recipient),
       # ... other headers ...
-      unsubscribe_url: manage_subscription_url(recipient) # Your app's URL helper
-    ) do
-      # ... email content ...
-    end
+    ) do # ...
     ```
-    *If an `unsubscribe_url` is provided (either globally or per-email), Goodmail will automatically add the standard `List-Unsubscribe` header.*
+    *If an `unsubscribe_url` is provided, Goodmail adds the `List-Unsubscribe` header.*
 
 2.  **Optionally Show Footer Link:**
-    *   To show a visible link in the email footer, set `config.show_footer_unsubscribe_link = true` in the initializer.
-    *   You can customize the link text with `config.footer_unsubscribe_link_text` (default: "Unsubscribe").
-    *   *Note: The footer link only appears if an `unsubscribe_url` was provided (step 1) AND `config.show_footer_unsubscribe_link` is true.* 
+    *   Set `config.show_footer_unsubscribe_link = true`.
+    *   Customize `config.footer_unsubscribe_link_text`.
+    *   *The footer link only appears if an `unsubscribe_url` was provided AND `config.show_footer_unsubscribe_link` is true.* 
 
     ```ruby
     # config/initializers/goodmail.rb
     Goodmail.configure do |config|
-      # ... other settings
       config.unsubscribe_url = "https://myapp.com/preferences"
       config.show_footer_unsubscribe_link = true
       config.footer_unsubscribe_link_text = "Manage email preferences"
+      # ...
     end
     ```
 
@@ -163,4 +278,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/rameer
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/goodmail/builder.rb

@@ -6,6 +6,9 @@ module Goodmail
   # Builds the HTML content string based on DSL method calls.
   class Builder
     include ERB::Util # For the h() helper
+    # The h helper, included from ERB::Util, stands for html_escape.
+    # It converts special characters (&, <, >, ", ') into their HTML entity equivalents (&amp;, &lt;, &gt;, &quot;, &#39;). This prevents Cross-Site Scripting (XSS) by ensuring dynamic content is displayed as literal text rather than being interpreted as HTML.
+
 
     # Initialize a basic sanitizer allowing only <a> tags with href
     HTML_SANITIZER = Rails::Html::SafeListSanitizer.new
@@ -34,16 +37,62 @@ module Goodmail
     end
 
     def button(text, url)
-      # Use a class for easier styling via layout CSS
-      parts << %(<div class="goodmail-button" style="text-align: center; margin: 24px 0;"><a href="#{h url}"><span style=\"color:#ffffff;\">#{h text}</span></a></div>)
+      # Standard HTML button link
+      button_html = %(<a href="#{h url}" class="goodmail-button-link" style="color:#ffffff;">#{h text}</a>)
+      # VML fallback for Outlook
+      vml_button = <<~VML
+        <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="#{h url}" style="height:44px; v-text-anchor:middle; width:200px;" arcsize="10%" stroke="f" fillcolor="#{Goodmail.config.brand_color}">
+          <w:anchorlock/>
+          <center style="color:#ffffff; font-family:sans-serif; font-size:14px; font-weight:bold;">
+            #{h text}
+          </center>
+        </v:roundrect>
+      VML
+      # MSO conditional wrapper
+      mso_wrapper = <<~MSO
+        <!--[if mso]>
+        <table width="100%" cellpadding="0" cellspacing="0" border="0" style="border-spacing: 0; border-collapse: collapse; mso-table-lspace:0pt; mso-table-rspace:0pt;"><tr><td style="padding: 10px 0;" align="center">
+        #{vml_button.strip}
+        </td></tr></table>
+        <![endif]-->
+        <!--[if !mso]><!-->
+        #{button_html}
+        <!--<![endif]-->
+      MSO
+      # Final container div with class for primary CSS styling
+      parts << %(<div class="goodmail-button" style="text-align: center; margin: 24px 0;">#{mso_wrapper.strip.html_safe}</div>)
     end
 
     def image(src, alt = "", width: nil, height: nil)
-      style = "max-width:100%; height:auto;"
+      alt_text = alt.present? ? alt : Goodmail.config.company_name # Default alt text
+      style = "max-width:100%; height:auto; display: block; margin: 0 auto;"
       style += " width:#{width}px;" if width
       style += " height:#{height}px;" if height
-      # Use a class for easier styling via layout CSS
-      parts << %(<img class="goodmail-image" src="#{h src}" alt="#{h alt}" style="#{style}">)
+      # Standard image tag
+      img_tag = %(<img class="goodmail-image" src="#{h src}" alt="#{h alt_text}" style="#{style}">)
+      # MSO conditional wrapper for centering
+      mso_wrapper = <<~MSO
+        <!--[if mso]>
+        <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="border-spacing:0; border-collapse:collapse; mso-table-lspace:0pt; mso-table-rspace:0pt;"><tr><td style="padding: 20px 0;" align="center">
+        <![endif]-->
+        #{img_tag}
+        <!--[if mso]>
+        </td></tr></table>
+        <![endif]-->
+      MSO
+      parts << mso_wrapper.strip.html_safe
+    end
+
+    # Adds a simple price row as a styled paragraph.
+    # NOTE: This does not create a table structure.
+    def price_row(name, price)
+      parts << %(<p style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; font-size: 14px; font-weight:bold; text-align:center; border-top:1px solid #eaeaea; padding:14px 0; margin: 0;">#{h name} &nbsp; &ndash; &nbsp; #{h price}</p>)
+    end
+
+    # Adds a simple code box with background styling.
+    def code_box(text)
+      # Re-added background/padding; content is simple, should survive Premailer plain text.
+      parts << %(<p style="background:#F8F8F8; padding:20px; font-style:italic; text-align:center; color:#404040; margin:16px 0; border-radius: 4px;"><strong>#{h text}</strong></p>)
     end
 
     def space(px = 16)
@@ -52,9 +101,8 @@ module Goodmail
     end
 
     def sign(name = Goodmail.config.company_name)
-      # Directly add the paragraph with the raw styled span
-      # Name is escaped using h() to prevent injection if config is compromised
-      parts << %(<p style="margin:16px 0; line-height: 1.6;"><span style="color: #888;">– #{h name}</span></p>)
+      # Use #777 for better contrast than #888
+      parts << %(<p style="margin:16px 0; line-height: 1.6;"><span style="color: #777;">– #{h name}</span></p>)
     end
 
     %i[h1 h2 h3].each do |heading_tag|

data/lib/goodmail/configuration.rb

@@ -9,32 +9,33 @@ module Goodmail
       brand_color:  "#348eda",
       company_name: "Example Inc.",
       logo_url:     nil,
-      # Optional footer text (e.g., "Why you received this email")
-      footer_text:  nil,
+      # Optional: URL the header logo links to.
+      company_url:  nil,
       # Optional: Global default unsubscribe URL.
-      # Can be overridden per email via headers[:unsubscribe_url].
-      # User is responsible for providing a valid URL to manage email subscriptions.
       unsubscribe_url: nil,
+      # Optional: Default preheader text (appears after subject in inbox preview).
+      default_preheader: nil,
+      # Optional footer text (e.g., "Why you received this email")
+      footer_text:  nil,
       # Show a visible unsubscribe link in the footer?
       show_footer_unsubscribe_link: false,
       # Text for the footer unsubscribe link
       footer_unsubscribe_link_text: "Unsubscribe"
     ).freeze # Freeze the default object to prevent accidental modification
 
+    # Define required keys that MUST be set by the user (cannot be nil/empty)
+    REQUIRED_CONFIG_KEYS = %i[company_name].freeze
+
     # Provides the configuration block helper.
-    # Allows users to modify the configuration in an initializer:
-    #   Goodmail.configure do |config|
-    #     config.brand_color = "#ff0000"
-    #   end
+    # Ensures validation runs after the block is executed.
     def configure
-      # Ensure config is initialized before yielding
-      yield config
+      yield config # Ensures config is initialized via accessor
+      validate_config!(config)
     end
 
     # Returns the current configuration object.
     # Initializes with a copy of the defaults if not already configured.
     def config
-      # Use defined? check for more robust initialization in edge cases
       @config = DEFAULT_CONFIG.dup unless defined?(@config) && @config
       @config
     end
@@ -45,6 +46,21 @@ module Goodmail
       @config = nil
     end
 
-    # Removed attr_reader/writer - relying on explicit config method.
+    private
+
+    # Validates that required configuration keys are set.
+    # Raises Goodmail::Error if any required keys are missing or blank.
+    def validate_config!(current_config)
+      missing_keys = REQUIRED_CONFIG_KEYS.select do |key|
+        value = current_config[key]
+        value.nil? || (value.respond_to?(:strip) && value.strip.empty?)
+      end
+
+      unless missing_keys.empty?
+        raise Goodmail::Error, "Missing required Goodmail configuration keys: #{missing_keys.join(', ')}. Please set them in config/initializers/goodmail.rb"
+      end
+
+      # Optional: Add validation for URL formats if needed
+    end
   end
 end

data/lib/goodmail/dispatcher.rb

@@ -21,20 +21,21 @@ module Goodmail
       # 3. Determine the final unsubscribe URL (user-provided)
       unsubscribe_url = headers[:unsubscribe_url] || Goodmail.config.unsubscribe_url
 
-      # 4. Render the raw HTML body using the Layout
-      #    This raw HTML still has the <style> block needed by Premailer.
+      # 4. Determine preheader text (priority: header > config > subject)
+      preheader = headers[:preheader] || Goodmail.config.default_preheader || headers[:subject]
+
+      # 5. Render the raw HTML body using the Layout
       raw_html_body = Goodmail::Layout.render(
         builder.html_output,
         headers[:subject],
-        unsubscribe_url: unsubscribe_url
+        unsubscribe_url: unsubscribe_url,
+        preheader: preheader # Pass preheader to layout
       )
 
-      # 5. Slice standard headers for the mailer action
+      # 6. Slice standard headers for the mailer action
       mailer_headers = slice_mail_headers(headers)
 
-      # 6. Build the mail object via the internal Mailer class action.
-      #    Pass the raw HTML (for Premailer) and unsubscribe URL.
-      #    Plaintext is now generated by Premailer inside the mailer action.
+      # 7. Build the mail object via the internal Mailer class action.
       delivery_object = Goodmail::Mailer.compose_message(
         mailer_headers,
         raw_html_body,
@@ -42,13 +43,14 @@ module Goodmail
         unsubscribe_url
       )
 
-      # 7. Return the ActionMailer::MessageDelivery object
+      # 8. Return the ActionMailer::MessageDelivery object
       delivery_object
     end
 
     private
 
     # Whitelist standard headers to pass to ActionMailer's mail() method
+    # Excludes custom headers like :unsubscribe_url, :preheader
     def slice_mail_headers(h)
       h.slice(:to, :from, :cc, :bcc, :reply_to, :subject)
     end

data/lib/goodmail/email.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+require "premailer"
+require "cgi" # For unescaping HTML in plaintext generation (though Premailer might handle most)
+
+module Goodmail
+  # Simple struct to hold the rendered HTML and text parts of an email.
+  EmailParts = Struct.new(:html, :text, keyword_init: true)
+
+  # Renders the email content using the Goodmail DSL and returns HTML and text parts.
+  # This method does not send the email but prepares its content for sending.
+  #
+  # @param headers [Hash] Mail headers. Expected to contain :subject.
+  #                       Can also contain :unsubscribe_url and :preheader to override defaults.
+  # @param dsl_block [Proc] Block containing Goodmail DSL calls (text, button, etc.)
+  # @return [Goodmail::EmailParts] An object containing the :html and :text email parts.
+  def self.render(headers = {}, &dsl_block)
+    # 1. Initialize the Builder and execute the DSL block
+    builder = Goodmail::Builder.new
+    builder.instance_eval(&dsl_block) if block_given?
+    core_html_content = builder.html_output
+
+    # 2. Determine unsubscribe_url and preheader
+    #    These are removed from headers as they are Goodmail-specific, not standard mail headers.
+    current_headers = headers.dup # Avoid modifying the original headers hash directly
+    unsubscribe_url = current_headers.delete(:unsubscribe_url) || Goodmail.config.unsubscribe_url
+    preheader = current_headers.delete(:preheader) || Goodmail.config.default_preheader || current_headers[:subject]
+
+    # 3. Render the raw HTML body using the Layout
+    #    The subject is passed for the <title> tag and potentially other uses in layout.
+    #    Unsubscribe URL and preheader are passed for inclusion in the layout.
+    raw_html_body = Goodmail::Layout.render(
+      core_html_content,
+      current_headers[:subject], # Use subject from (potentially modified) current_headers
+      unsubscribe_url: unsubscribe_url,
+      preheader: preheader
+    )
+
+    # 4. Use Premailer to inline CSS and generate plaintext
+    premailer = Premailer.new(
+      raw_html_body,
+      with_html_string: true,
+      adapter: :nokogiri,
+      preserve_styles: false, # Force inlining and remove <style> block
+      remove_ids: true,       # Remove IDs
+      remove_comments: false  # Keep MSO conditional comments
+    )
+
+    final_inlined_html = premailer.to_inline_css
+    generated_plain_text = premailer.to_plain_text
+
+    # 5. Perform refined plaintext cleanup (ported from Goodmail::Mailer)
+    # 5.1. Remove logo alt text line (if logo exists and has associated URL)
+    if Goodmail.config.logo_url.present? && Goodmail.config.company_url.present? && Goodmail.config.company_name.present?
+      company_name_escaped = Regexp.escape(Goodmail.config.company_name)
+      company_url_escaped = Regexp.escape(Goodmail.config.company_url)
+      # Regex to match the typical alt text pattern for a linked logo image
+      logo_alt_pattern = /^\s*#{company_name_escaped}\s+Logo\s*\(.*?#{company_url_escaped}.*?\).*\n?/i
+      generated_plain_text.gsub!(logo_alt_pattern, "")
+    end
+
+    # 5.2. Remove any remaining standalone URL lines (often from logo links or similar artifacts)
+    # This targets lines that consist *only* of a URL.
+    generated_plain_text.gsub!(/^\s*https?:\/\/\S+\s*$\n?/i, "")
+
+    # 5.3. Compact excess blank lines (more than two consecutive newlines)
+    generated_plain_text.gsub!(/\n{3,}/, "\n\n")
+
+    # 6. Return the structured parts
+    EmailParts.new(html: final_inlined_html, text: generated_plain_text.strip)
+  end
+end

data/lib/goodmail/layout.erb

@@ -161,6 +161,11 @@
 
 <body itemscope itemtype="http://schema.org/EmailMessage" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none; width: 100% !important; height: 100%; line-height: 1.6em; background-color: #f6f6f6; margin: 0;" bgcolor="#f6f6f6">
 
+<!-- Hidden Preheader Text -->
+<span style="display:none !important; font-size:1px; color:#ffffff; line-height:1px; max-height:0px; max-width:0px; opacity:0; overflow:hidden;">
+  <%= preheader || subject %>
+</span>
+
 <table class="body-wrap" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; width: 100%; background-color: #f6f6f6; margin: 0;" bgcolor="#f6f6f6">
   <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
     <td style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0;" valign="top"></td>
@@ -172,16 +177,23 @@
           <table class="header" width="100%" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0 0 20px; text-align: left;" align="left">
             <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
               <td style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0;" valign="top">
-                <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="30" style="max-height: 30px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
+                <% if config.company_url.present? %>
+                  <a href="<%= config.company_url %>" style="text-decoration:none; border:0;">
+                    <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="20" style="max-height: 20px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
+                  </a>
+                <% else %>
+                  <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="20" style="max-height: 20px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
+                <% end %>
               </td>
             </tr>
           </table>
         <% end %>
 
         <!-- Main Content Body -->
-        <table class="main" width="100%" cellpadding="0" cellspacing="0" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; border-radius: 3px; background-color: #fff; margin: 0; border: 1px solid #e9e9e9;" bgcolor="#fff">
+        <table class="main" width="100%" cellpadding="0" cellspacing="0" itemprop="action" itemscope itemtype="http://schema.org/ConfirmAction" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; border-radius: 3px; background-color: #fff; margin: 0; border: 1px solid #e9e9e9;" bgcolor="#fff">
           <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
             <td class="content-wrap" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 30px;" valign="top">
+              <meta itemprop="name" content="<%= subject %>" />
               <table width="100%" cellpadding="0" cellspacing="0" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
                 <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
                   <td style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0;" valign="top">

data/lib/goodmail/layout.rb

@@ -16,8 +16,9 @@ module Goodmail
     # @param subject [String] The email subject line (used for the <title> tag).
     # @param layout_path [String, nil] Optional path to a custom layout ERB file.
     # @param unsubscribe_url [String, nil] Optional URL for the footer unsubscribe link.
+    # @param preheader [String, nil] Optional preheader text.
     # @return [String] The full HTML document string.
-    def render(body_html, subject, layout_path: nil, unsubscribe_url: nil)
+    def render(body_html, subject, layout_path: nil, unsubscribe_url: nil, preheader: nil)
       template_path = layout_path || DEFAULT_LAYOUT_PATH
 
       unless File.exist?(template_path)
@@ -31,7 +32,8 @@ module Goodmail
         body_html:       body_html,
         subject:         subject || "",
         config:          Goodmail.config, # Make config available
-        unsubscribe_url: unsubscribe_url  # Pass unsubscribe URL to template
+        unsubscribe_url: unsubscribe_url,  # Pass unsubscribe URL to template
+        preheader:       preheader # Pass preheader to template
       )
     rescue => e
       raise Goodmail::Error, "Failed to render layout template: #{e.message}"

data/lib/goodmail/mailer.rb

@@ -18,22 +18,38 @@ module Goodmail
     # Action Mailer wraps the result in a MessageDelivery object.
     # It uses Premailer to inline CSS and generate plaintext.
     # @api internal
-    def compose_message(headers, raw_html_body, raw_text_body, unsubscribe_url)
+    def compose_message(headers, raw_html_body, _raw_text_body, unsubscribe_url)
       # Initialize Premailer with the raw HTML body from the layout
       premailer = Premailer.new(
         raw_html_body,
         with_html_string: true,
         # Common options:
-        adapter: :nokogiri, # Faster parser
-        preserve_styles: true, # Keep <style> block for clients that support it
-        remove_ids: false, # Keep IDs if needed for anchors etc.
-        remove_comments: true
+        adapter: :nokogiri,
+        preserve_styles: false, # Set to false to force inlining *and* remove <style> block
+        remove_ids: true, # Can usually remove IDs
+        remove_comments: false, # KEEP conditional comments so MSO conditionals in the template work!
+        # Note: `plain_text_images: false` might exist but is not standard;
+        # relying on gsub cleanup below.
       )
 
       # Get processed content
       inlined_html = premailer.to_inline_css
+      # Generate plain text, skipping image conversion
       generated_plain_text = premailer.to_plain_text
 
+      # Clean up plaintext:
+      # 1. Remove logo alt text line (if logo exists and has associated URL)
+      if Goodmail.config.logo_url.present? && Goodmail.config.company_url.present? && Goodmail.config.company_name.present?
+        company_name_escaped = Regexp.escape(Goodmail.config.company_name)
+        company_url_escaped = Regexp.escape(Goodmail.config.company_url)
+        logo_alt_pattern = /^\s*#{company_name_escaped}\s+Logo\s+\(.*?#{company_url_escaped}.*?\).*\n?/i
+        generated_plain_text.gsub!(logo_alt_pattern, '')
+      end
+      # 2. Remove any remaining standalone URL lines (often from logo links)
+      generated_plain_text.gsub!(/^\s*https?:\/\/\S+\s*$\n?/i, '')
+      # 3. Compact excess blank lines created by gsubbing
+      generated_plain_text.gsub!(/\n{3,}/, "\n\n")
+
       # Add List-Unsubscribe header to the headers hash *before* calling mail()
       if unsubscribe_url.is_a?(String) && !unsubscribe_url.strip.empty?
         headers["List-Unsubscribe"] = "<#{unsubscribe_url.strip}>"
@@ -42,7 +58,7 @@ module Goodmail
       # Call the instance-level `mail` method
       mail(headers) do |format|
         # Use the premailer-generated plaintext
-        format.text { render plain: generated_plain_text }
+        format.text { render plain: generated_plain_text.strip }
         # Use the CSS-inlined HTML
         format.html { render html: inlined_html.html_safe }
       end

data/lib/goodmail/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Goodmail
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/goodmail.rb

@@ -10,6 +10,7 @@ require_relative "goodmail/configuration"
 require_relative "goodmail/error" # Load Error class explicitly if needed elsewhere
 require_relative "goodmail/builder"
 require_relative "goodmail/layout"
+require_relative "goodmail/email"
 require_relative "goodmail/mailer"     # Require the internal Mailer
 require_relative "goodmail/dispatcher"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: goodmail
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-05-02 00:00:00.000000000 Z
+date: 2025-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -96,11 +96,13 @@ files:
 - lib/goodmail/builder.rb
 - lib/goodmail/configuration.rb
 - lib/goodmail/dispatcher.rb
+- lib/goodmail/email.rb
 - lib/goodmail/error.rb
 - lib/goodmail/layout.erb
 - lib/goodmail/layout.rb
 - lib/goodmail/mailer.rb
 - lib/goodmail/version.rb
+- mailgood.webp
 - sig/goodmail.rbs
 homepage: https://github.com/rameerez/goodmail
 licenses: