goodmail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fa74c986faf7a129fa8daa4546192918312488290ad46aff8f889009efdefbe4
+  data.tar.gz: 9d138231f61b68a137a2726b989788bd180d7c15e6fa6a4f414c929243c8b343
+SHA512:
+  metadata.gz: 66d62b19ff6baebd3512bc3d04f60b0b329fec2e36b90ccd8cc9701a955206b91f73f86af4ccdb9a74501f0e05d4f36c948d1683b54049fdebf821244965331c
+  data.tar.gz: a1c74368751fc8c5701f6aefc588a118ac1839691d5657475024343e0b007646271e9ffe1b7c23294245dfaedde263e421a4b24418a3df0fc74998a983f49ab3

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2025-05-02
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+# 💌 Goodmail - Make your transactional emails look beautiful
+[![Gem Version](https://badge.fury.io/rb/pay.svg)](https://badge.fury.io/rb/pay)
+
+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.
+
+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!)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "goodmail"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+You can (and should!) edit the default strings in the Goodmail initializer.
+
+Create an initializer file at `config/initializers/goodmail.rb`:
+
+```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
+
+  # The company name displayed in the email footer and used by the default `sign` helper.
+  # Default: "Example Inc."
+  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.
+  # 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.
+  # Default: nil
+  config.footer_text = "You are receiving this email because you signed up for an account at MyApp."
+
+  # Optional: Global default URL for unsubscribe links (both the List-Unsubscribe
+  # header and the optional visible link in the footer).
+  # 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: Whether to show a visible unsubscribe link in the footer.
+  # Requires an unsubscribe URL to be set (globally or per-email).
+  # Default: false
+  config.show_footer_unsubscribe_link = true
+
+  # Optional: The text for the visible footer unsubscribe link.
+  # Default: "Unsubscribe"
+  config.footer_unsubscribe_link_text = "Click here to unsubscribe"
+end
+```
+
+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)
+
+### Basic Example
+
+```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
+```
+
+### Deliver Later (Background Job)
+
+```ruby
+mail = Goodmail.compose(
+  to: @user.email,
+  from: ..., # etc.
+  subject: "Your password has been reset"
+) do
+  # ... DSL content ...
+end
+
+mail.deliver_later
+```
+
+*(Requires Active Job configured.)*
+
+### 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.
+*   `space(pixels = 16)`: Adds vertical whitespace.
+*   `line`: Adds a horizontal rule (`<hr>`).
+*   `center { ... }`: Centers the content generated within the block.
+*   `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.
+
+### 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.
+
+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.
+
+    ```ruby
+    # Example using per-email override
+    mail = Goodmail.compose(
+      to: recipient.email,
+      # ... other headers ...
+      unsubscribe_url: manage_subscription_url(recipient) # Your app's URL helper
+    ) do
+      # ... email content ...
+    end
+    ```
+    *If an `unsubscribe_url` is provided (either globally or per-email), Goodmail will automatically add the standard `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.* 
+
+    ```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
+    ```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/goodmail. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/goodmail/builder.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+require "erb"
+require "rails-html-sanitizer" # Require the sanitizer
+
+module Goodmail
+  # Builds the HTML content string based on DSL method calls.
+  class Builder
+    include ERB::Util # For the h() helper
+
+    # Initialize a basic sanitizer allowing only <a> tags with href
+    HTML_SANITIZER = Rails::Html::SafeListSanitizer.new
+    ALLOWED_TAGS = %w(a).freeze
+    ALLOWED_ATTRIBUTES = %w(href).freeze
+
+    attr_reader :parts
+
+    def initialize
+      @parts = []
+    end
+
+    # DSL Methods
+
+    # Adds a paragraph of text. Handles newline characters for <br> tags.
+    # Allows safe inline <a> tags with href attributes; strips other HTML.
+    def text(str)
+      # Sanitize first, allowing only safe tags like <a>
+      sanitized_content = HTML_SANITIZER.sanitize(
+        str.to_s, # Ensure input is a string
+        tags: ALLOWED_TAGS,
+        attributes: ALLOWED_ATTRIBUTES
+      )
+      # Then handle newlines and wrap in paragraph
+      parts << tag(:p, sanitized_content.gsub(/\n/, "<br>"), style: "margin:16px 0; line-height: 1.6;")
+    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>)
+    end
+
+    def image(src, alt = "", width: nil, height: nil)
+      style = "max-width:100%; height: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}">)
+    end
+
+    def space(px = 16)
+      # Rely on CSS height for spacing, avoid &nbsp; if possible
+      parts << %(<div style="height:#{Integer(px)}px; line-height: #{Integer(px)}px; font-size: 1px;"></div>)
+    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>)
+    end
+
+    %i[h1 h2 h3].each do |heading_tag|
+      define_method(heading_tag) do |str|
+        # Added basic heading styles, consistent with layout.erb
+        style = case heading_tag
+                when :h1 then "margin: 40px 0 10px; font-size: 32px; font-weight: 500; line-height: 1.2em;"
+                when :h2 then "margin: 40px 0 10px; font-size: 24px; font-weight: 400; line-height: 1.2em;"
+                when :h3 then "margin: 40px 0 10px; font-size: 18px; font-weight: 400; line-height: 1.2em;"
+                else "margin: 16px 0; line-height: 1.6;"
+                end
+        # Headings should still have their content escaped
+        parts << tag(heading_tag, h(str), style: style)
+      end
+    end
+
+    def center(&block)
+      wrap("div", "text-align:center;", &block)
+    end
+
+    def line
+      # Use a class for easier styling via layout CSS
+      parts << %(<hr class="goodmail-hr">)
+    end
+
+    # Allows inserting raw, *trusted* HTML. Use with extreme caution.
+    def html(raw_html_string)
+      parts << raw_html_string.to_s
+    end
+
+    # Returns the collected HTML parts joined together.
+    def html_output
+      parts.join("\n")
+    end
+
+    private
+
+    # Helper for creating simple HTML tags with optional style
+    # Assumes content is already appropriately escaped or marked safe.
+    def tag(name, content, style: nil)
+      style_attr = style ? " style=\"#{h style}\"" : ""
+      "<#{name}#{style_attr}>#{content}</#{name}>"
+    end
+
+    # Temporarily captures parts generated within a block into a wrapped tag.
+    def wrap(tag_name, style, &block)
+      original_parts = @parts
+      @parts = []
+      yield # Execute the block, collecting parts into the temporary @parts
+      inner_html = @parts.join("\n")
+      @parts = original_parts # Restore original parts array
+      @parts << tag(tag_name, inner_html, style: style)
+    ensure
+      # Ensure parts are restored even if the block raises an error
+      @parts = original_parts if defined?(original_parts)
+    end
+
+    # Prevent external modification of the parts array directly
+    attr_writer :parts
+  end
+end

data/lib/goodmail/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+require "ostruct"
+
+module Goodmail
+  # Handles configuration settings for the Goodmail gem.
+  module Configuration
+    # Default configuration values
+    DEFAULT_CONFIG = OpenStruct.new(
+      brand_color:  "#348eda",
+      company_name: "Example Inc.",
+      logo_url:     nil,
+      # Optional footer text (e.g., "Why you received this email")
+      footer_text:  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,
+      # 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
+
+    # Provides the configuration block helper.
+    # Allows users to modify the configuration in an initializer:
+    #   Goodmail.configure do |config|
+    #     config.brand_color = "#ff0000"
+    #   end
+    def configure
+      # Ensure config is initialized before yielding
+      yield 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
+
+    # Resets the configuration back to the default values.
+    # Primarily useful for testing environments.
+    def reset_config!
+      @config = nil
+    end
+
+    # Removed attr_reader/writer - relying on explicit config method.
+  end
+end

data/lib/goodmail/dispatcher.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+require "action_mailer"
+require "cgi" # For unescaping HTML in plaintext generation
+require_relative "mailer" # Require the internal mailer
+
+module Goodmail
+  # Responsible for orchestrating the building of the Mail::Message object.
+  module Dispatcher
+    extend self
+
+    # Builds the Mail::Message object with HTML and Text parts, wrapped in
+    # an ActionMailer::MessageDelivery object.
+    # @api private
+    def build_message(headers, &block)
+      # 1. Initialize the Builder
+      builder = Goodmail::Builder.new
+
+      # 2. Execute the DSL block within the Builder instance
+      builder.instance_eval(&block) if block_given?
+
+      # 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.
+      raw_html_body = Goodmail::Layout.render(
+        builder.html_output,
+        headers[:subject],
+        unsubscribe_url: unsubscribe_url
+      )
+
+      # 5. 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.
+      delivery_object = Goodmail::Mailer.compose_message(
+        mailer_headers,
+        raw_html_body,
+        nil, # Pass nil for raw_text_body - Premailer generates it
+        unsubscribe_url
+      )
+
+      # 7. Return the ActionMailer::MessageDelivery object
+      delivery_object
+    end
+
+    private
+
+    # Whitelist standard headers to pass to ActionMailer's mail() method
+    def slice_mail_headers(h)
+      h.slice(:to, :from, :cc, :bcc, :reply_to, :subject)
+    end
+
+    # Removed generate_plaintext - now handled by Premailer in Mailer#compose_message
+  end
+end

data/lib/goodmail/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Goodmail
+  # Base error class for Goodmail specific exceptions.
+  # This allows users to rescue Goodmail::Error specifically.
+  class Error < StandardError; end
+end

data/lib/goodmail/layout.erb

@@ -0,0 +1,235 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
+<head>
+  <meta name="viewport" content="width=device-width" />
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+  <title><%= subject %></title>
+  <style type="text/css">
+    /* Base Styles */
+    img {
+      max-width: 100%;
+    }
+    body {
+      -webkit-font-smoothing: antialiased;
+      -webkit-text-size-adjust: none;
+      width: 100% !important;
+      height: 100%;
+      line-height: 1.6em;
+      background-color: #f6f6f6; /* Body background */
+      margin: 0;
+      padding: 0;
+    }
+    table td {
+      vertical-align: top;
+    }
+    .body-wrap {
+      background-color: #f6f6f6;
+      width: 100%;
+    }
+    .container {
+      display: block !important;
+      max-width: 600px !important;
+      margin: 0 auto !important; /* Center the container */
+      clear: both !important;
+    }
+    .content {
+      max-width: 600px;
+      margin: 0 auto;
+      display: block;
+      padding: 20px;
+    }
+    .main {
+      background-color: #ffffff; /* Email body background */
+      border: 1px solid #e9e9e9;
+      border-radius: 3px;
+    }
+    .content-wrap {
+      padding: 30px; /* Padding inside the white content area */
+    }
+    .header {
+      width: 100%;
+      margin-bottom: 20px;
+      text-align: left;
+    }
+    .footer {
+      width: 100%;
+      clear: both;
+      color: #999;
+      padding: 20px;
+      margin-top: 20px;
+    }
+    .footer p,
+    .footer a,
+    .footer td {
+      color: #999;
+      font-size: 12px;
+      text-align: center;
+      padding: 0 0 10px; /* Add padding between footer lines */
+    }
+    .footer a {
+        text-decoration: underline;
+        color: #999; /* Keep footer links grey */
+    }
+
+    /* Typography */
+    h1, h2, h3 {
+      font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+      color: #000000;
+      margin: 40px 0 10px;
+      line-height: 1.2em;
+      font-weight: 400;
+    }
+    h1 { font-size: 32px; font-weight: 500; }
+    h2 { font-size: 24px; }
+    h3 { font-size: 18px; }
+    p, ul, ol {
+      font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+      font-size: 15px; /* Slightly larger base font */
+      font-weight: normal;
+      margin-bottom: 15px;
+      line-height: 1.6;
+    }
+    a {
+      color: <%= config.brand_color %>; /* Use brand color for links */
+      text-decoration: underline;
+    }
+
+    /* Elements generated by Builder */
+    .goodmail-button a {
+      font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif;
+      box-sizing: border-box;
+      font-size: 14px;
+      color: #FFF !important; /* Ensure button text is white */
+      text-decoration: none;
+      line-height: 2em;
+      font-weight: bold;
+      text-align: center;
+      cursor: pointer;
+      display: inline-block;
+      border-radius: 5px;
+      text-transform: capitalize;
+      background-color: <%= config.brand_color %>;
+      margin: 0;
+      border-color: <%= config.brand_color %>;
+      border-style: solid;
+      border-width: 10px 20px;
+    }
+    .goodmail-hr {
+        border: none;
+        border-top: 1px solid #e9e9e9; /* Match main border color */
+        margin: 30px 0;
+    }
+    .goodmail-image {
+        display: block;
+        margin: 20px auto; /* Center images added via image() */
+        max-width: 100%;
+        height: auto;
+    }
+    /* Add styles for headings from builder if needed, or rely on base H tags */
+
+    /* Responsive Styles */
+    @media only screen and (max-width: 640px) {
+      body {
+        padding: 0 !important;
+      }
+      h1, h2, h3 {
+        font-weight: 800 !important; margin: 20px 0 5px !important;
+      }
+      h1 { font-size: 22px !important; }
+      h2 { font-size: 18px !important; }
+      h3 { font-size: 16px !important; }
+      .container {
+        padding: 0 !important; width: 100% !important;
+      }
+      .content {
+        padding: 0 !important;
+      }
+      .content-wrap {
+        padding: 15px !important; /* Reduced padding on mobile */
+      }
+      .goodmail-button a {
+          padding: 8px 16px !important; /* Slightly smaller button padding */
+          font-size: 13px !important;
+      }
+    }
+
+    /* Outlook/MSO Specific Fixes */
+    /* Add any necessary MSO fixes here if testing reveals issues */
+
+  </style>
+</head>
+
+<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">
+
+<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>
+    <td class="container" width="600" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; display: block !important; max-width: 600px !important; clear: both !important; margin: 0 auto;" valign="top">
+      <div class="content" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; max-width: 600px; display: block; margin: 0 auto; padding: 20px;">
+
+        <!-- Optional Header Section -->
+        <% if config.logo_url %>
+          <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;" />
+              </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">
+          <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">
+              <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">
+                    <!-- DSL Content Goes Here -->
+                    <%= body_html %>
+                  </td>
+                </tr>
+              </table>
+            </td>
+          </tr>
+        </table>
+
+        <!-- Footer Section -->
+        <div class="footer" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; width: 100%; clear: both; color: #999; margin: 20px 0 0; padding: 20px;">
+          <table width="100%" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
+            <!-- Copyright -->
+            <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
+              <td class="aligncenter content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 12px; vertical-align: top; text-align: center; margin: 0; padding: 0 0 10px; color: #999;" align="center" valign="top">
+                &copy; <%= Date.today.year %> <%= config.company_name %>
+              </td>
+            </tr>
+
+            <!-- Optional Footer Text -->
+            <% if config.footer_text.present? %>
+              <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
+                <td class="aligncenter content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 12px; vertical-align: top; text-align: center; margin: 0; padding: 0 0 10px; color: #999;" align="center" valign="top">
+                  <%= config.footer_text %>
+                </td>
+              </tr>
+            <% end %>
+
+            <!-- Optional Unsubscribe Link -->
+            <% if config.show_footer_unsubscribe_link && defined?(unsubscribe_url) && unsubscribe_url.present? %>
+              <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
+                <td class="aligncenter content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 12px; vertical-align: top; text-align: center; margin: 0; padding: 0 0 10px; color: #999;" align="center" valign="top">
+                  <a href="<%= unsubscribe_url %>" style="color: #999;"><%= config.footer_unsubscribe_link_text %></a>
+                </td>
+              </tr>
+            <% end %>
+
+          </table>
+        </div>
+
+      </div> <!-- /.content -->
+    </td>
+    <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>
+  </tr>
+</table>
+
+</body>
+</html> 

data/lib/goodmail/layout.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+require "erb"
+
+module Goodmail
+  # Handles rendering the final HTML email by injecting
+  # the built content into the main layout template.
+  module Layout
+    extend self
+
+    # Path to the default layout template within the gem
+    DEFAULT_LAYOUT_PATH = File.expand_path("layout.erb", __dir__)
+
+    # Renders the email content within the layout template.
+    #
+    # @param body_html [String] The HTML content generated by the Builder.
+    # @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.
+    # @return [String] The full HTML document string.
+    def render(body_html, subject, layout_path: nil, unsubscribe_url: nil)
+      template_path = layout_path || DEFAULT_LAYOUT_PATH
+
+      unless File.exist?(template_path)
+        raise Goodmail::Error, "Layout template not found at #{template_path}"
+      end
+
+      template_content = File.read(template_path)
+
+      # Use ERB#result_with_hash for cleaner variable passing (Ruby 2.5+)
+      ERB.new(template_content).result_with_hash(
+        body_html:       body_html,
+        subject:         subject || "",
+        config:          Goodmail.config, # Make config available
+        unsubscribe_url: unsubscribe_url  # Pass unsubscribe URL to template
+      )
+    rescue => e
+      raise Goodmail::Error, "Failed to render layout template: #{e.message}"
+    end
+  end
+end

data/lib/goodmail/mailer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require "action_mailer"
+require "premailer" # Require premailer library
+
+module Goodmail
+  # Internal Mailer class.
+  # Inherits from ActionMailer::Base to provide the necessary context
+  # for building Mail::Message objects, but without relying on any
+  # host application views or layouts.
+  class Mailer < ActionMailer::Base
+    # No explicit default settings needed here usually,
+    # as headers (:from, etc.) should be provided in Goodmail.compose
+    # It will, however, inherit default ActionMailer settings from the Rails app
+    # (like delivery_method, smtp_settings, default_url_options) which is good.
+
+    # This instance method acts as the mailer action.
+    # It's called via Goodmail::Mailer.compose_message(...)
+    # 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)
+      # 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
+      )
+
+      # Get processed content
+      inlined_html = premailer.to_inline_css
+      generated_plain_text = premailer.to_plain_text
+
+      # 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}>"
+      end
+
+      # Call the instance-level `mail` method
+      mail(headers) do |format|
+        # Use the premailer-generated plaintext
+        format.text { render plain: generated_plain_text }
+        # Use the CSS-inlined HTML
+        format.html { render html: inlined_html.html_safe }
+      end
+      # Action Mailer automatically returns the MessageDelivery object
+    end
+  end
+end

data/lib/goodmail/version.rb

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

data/lib/goodmail.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Order matters: Load dependencies and base modules first.
+require "action_mailer"
+require "ostruct"
+
+# Load Goodmail components
+require_relative "goodmail/version"
+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/mailer"     # Require the internal Mailer
+require_relative "goodmail/dispatcher"
+
+# The main namespace for the Goodmail gem.
+# Provides configuration and the primary .compose method.
+module Goodmail
+  # Extend self with Configuration module methods (config, configure, reset_config!)
+  extend Configuration
+
+  # Composes a Mail::Message object using the Goodmail DSL and layout.
+  #
+  # This is the primary entry point for creating emails with Goodmail.
+  # The returned Mail::Message object can then have `.deliver_now` or
+  # `.deliver_later` called on it.
+  #
+  # @param headers [Hash] Mail headers (:to, :from, :subject, etc.)
+  #                       Also accepts :unsubscribe (true or String URL).
+  # @param block [Proc] Block containing Goodmail DSL calls (text, button, etc.)
+  # @return [Mail::Message] The generated Mail object, ready for delivery.
+  #
+  # @example
+  #   mail = Goodmail.compose(to: 'user@example.com', subject: 'Hello!') do
+  #     text "This is the email body."
+  #     button "Click Me", "https://example.com"
+  #   end
+  #
+  #   mail.deliver_now
+  #   # or
+  #   mail.deliver_later
+  #
+  def self.compose(headers = {}, &block)
+    # Delegate the actual building process to the Dispatcher
+    Dispatcher.build_message(headers, &block)
+  end
+
+  # Error class is defined in lib/goodmail/error.rb
+end

data/sig/goodmail.rbs

@@ -0,0 +1,4 @@
+module Goodmail
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: goodmail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+bindir: exe
+cert_chain: []
+date: 2025-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rails-html-sanitizer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: premailer-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Send beautiful, simple transactional emails with zero HTML hell. Goodmail
+  is a minimal, opinionated, expressive Ruby DSL for sending production-grade transactional
+  emails in Rails apps that look good in any email client out of the box.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/goodmail.rb
+- lib/goodmail/builder.rb
+- lib/goodmail/configuration.rb
+- lib/goodmail/dispatcher.rb
+- lib/goodmail/error.rb
+- lib/goodmail/layout.erb
+- lib/goodmail/layout.rb
+- lib/goodmail/mailer.rb
+- lib/goodmail/version.rb
+- sig/goodmail.rbs
+homepage: https://github.com/rameerez/goodmail
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rameerez/goodmail
+  source_code_uri: https://github.com/rameerez/goodmail
+  changelog_uri: https://github.com/rameerez/goodmail/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Make your transactional emails look beautiful
+test_files: []