supermail 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53951b27c057ea4419f1ffbbc3666189712d30449af65e539148d7df306de7d3
-  data.tar.gz: 789c9f9844880bae6611b9c5cdb958a4fb6b2d7c59888db016c503ebabec3573
+  metadata.gz: 4efb804624582618a2d1330b68b48030e27a0764f82bd8e5a99d01ba955d2174
+  data.tar.gz: 362d37bf770583b50c86e26cd280158cb8885e8725589ec68a4093ed5fabe79a
 SHA512:
-  metadata.gz: 4de9d3383587ea03cd2eb302c6db564d88972535f286ed3ed2181146a56cc815d893e2a84543435854f92f39b767598bd5cef348516865f6706d290961f38d27
-  data.tar.gz: 6364025594980a3ca8776970cd20be025cbe044cc69dc55766f89e874842f691e0d2b244a0dba773f92976ca6d69ab28bc0956233d25195e1afbbed67723d956
+  metadata.gz: d3d68858b41c793e45eda60b43f557bd0fc3e049f248d22352f8bd2e52544b10d2b374befca84fac46de283807352e59e2dbd8bb1e8c605fa7826b2b70789935
+  data.tar.gz: 799eca08e4b0997fda627688b0707442cf5a2d66dc8c42fdf10bfcef6d7a1a2d6e2b4641c00de898ffc1e4dbd78b2af50bd58de8926b6ffbe520c76058f2dc8d

data/README.md

@@ -1,6 +1,36 @@
 # Supermail
 
-Supermail is a slightly more intuitive way of organizing Emails in a Rails application.
+Organize emails with plain 'ol Ruby objects in a Rails application, like this:
+
+```ruby
+# ./app/email/user/welcome.rb
+class User::WelcomeEmail < ApplicationEmail
+  def initialize(person:)
+    @person = person
+  end
+
+  def to = @person.email
+  def subject = "Welcome to Beautiful Ruby"
+  def body
+    super do
+      <<~_
+      Hi #{@person.name},
+
+      You're going to learn a ton at https://beautifulruby.com.
+      _
+    end
+  end
+end
+```
+
+Contrast that with rails ActionMailer, where you will spend 20 minutes trying to figure out how to send an email. I created this gem because I got tired of digging through Rails docs to understand how to intialize an email and send it. PORO's FTW!
+
+## Support this project
+
+Learn how to build UI's out of Ruby classes and support this project by ordering the [Phlex on Rails video course](https://beautifulruby.com/phlex).
+
+[![](https://immutable.terminalwire.com/hmM9jvv7yF89frBUfjikUfRmdUsTVZ8YvXc7OnnYoERXfLJLzDcj5dFM7qdfMG2bqQLuw633Zt1gl3O7z0zKmH6k8QmifN7z0kJo.png)](https://beautifulruby.com/phlex/forms/introduction)
+
 
 ## Installation
 
@@ -16,22 +46,21 @@ Then install it in Rails.
 rails generate supermail:install
 ```
 
-This creates the `app/emails/application_email.rb` file that you can customize as the base for all emails.
+This creates the `ApplicationEmail` class at `app/emails/application_email.rb` where you can customize the base for all emails, including setting defaults like the `from` address.
 
 ```ruby
-class ApplicationEmail < Supermail::Email
-  def from = "Supermail <noreply@supermail.com>"
-
-  class HTML
-    def after_template
-      p { "Best, The Supermail Team" }
-    end
-  end
-
-  class Text
-    def after_template
-      "Best,\nThe Supermail Team"
-    end
+class ApplicationEmail < Supermail::Rails::Base
+  def from = "website@example.com"
+  def to = nil
+  def subject = nil
+  def body
+     <<~_
+     #{yield if block_given?}
+
+     Best,
+
+     The Example.com Team
+     _
   end
 end
 ```
@@ -44,32 +73,41 @@ To generate a new email, run the following command:
 rails generate supermail:email User::Welcome
 ```
 
-This will create a new email class in `app/mailers/user/welcome.rb`.
+This will create a new email class in `app/mailers/user/welcome_email.rb`.
 
 ```ruby
 # ./app/email/user/welcome.rb
-class User::Welcome < ApplicationEmail
-  def initialize(user:)
-    @user = user
-  end
-
-  def subject = "Welcome to Supermail!"
+class User::WelcomeEmail < ApplicationEmail
+  def body = <<~PLAIN
+    Hello there!
+  PLAIN
+end
+```
+You can customize the email by overriding the `to`, `from`, `subject`, and `body` methods.s
 
-  class HTML
-    def view_template
-      h1 { "Welcome, #{@user.name}!" }
-      p { "We're excited to have you on board." }
-    end
+```ruby
+# ./app/email/user/welcome.rb
+class User::WelcomeEmail < ApplicationEmail
+  def initialize(person:)
+    @person = person
   end
 
-  class Text
-    def view_template
-      "Welcome, #{@user.name}!\n\nWe're excited to have you on board."
+  def to = @person.email
+  def subject = "Welcome to the website"
+  def body
+    super do
+      <<~_
+      Hi #{@person.name},
+
+      Welcome to the website We're excited to have you on board.
+      _
     end
   end
 end
 ```
 
+### Send emails from the server
+
 Then, to send the email.
 
 ```ruby
@@ -82,6 +120,42 @@ If you want to tweak the message on the fly, you can modify the message, then de
 User::Welcome.new(user: User.first).message.tap do
   it.to << "another@example.com"
 end.deliver_now
+```
+
+### Launch the user's email client
+
+Supermail clases can be used to generate `mailto:` links with Rails helpers.
+
+```erb
+<%= link_to Support::OrderEmail.new(
+      user: current_user,
+      order: @order
+    ).mail_to s%>
+```
+
+This opens your users email client with prefilled information. A support email about an order might look like this:
+
+```ruby
+class Support::OrderEmail < ApplicationEmail
+  def initialize(user:, order:)
+    @user = user
+    @order = order
+  end
+
+  def to = "support@example.com"
+  def from = @user.email
+  def subject = "Question about order #{@order.id}"
+  def body = <<~BODY
+    Hi Support,
+
+    I need help with my order #{@order.id}.
+
+    Thanks,
+
+    #{@user.name}
+  BODY
+end
+```
 
 ## Development
 

data/lib/generators/supermail/email/email_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+
+module Supermail
+  class EmailGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
+
+    desc "Generate a new email class"
+
+    def create_email_file
+      template 'email.rb', "app/emails/#{file_path}_email.rb"
+    end
+
+    private
+
+    def file_path
+      name.underscore
+    end
+
+    def class_name
+      name.camelize
+    end
+  end
+end

data/lib/generators/supermail/email/templates/email.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Email < ApplicationEmail
+  def body = <<~PLAIN
+
+  PLAIN
+end

data/lib/generators/supermail/install/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module Supermail
+  class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Install Supermail in a Rails application"
+
+      def create_application_email
+        template 'application_email.rb', 'app/emails/application_email.rb'
+      end
+
+      def create_emails_directory
+        empty_directory 'app/emails'
+      end
+  end
+end

data/lib/generators/supermail/install/templates/application_email.rb.tt

@@ -0,0 +1,13 @@
+class ApplicationEmail < Supermail::Rails::Base
+  def from = "website@example.com"
+
+  def body
+     <<~_
+     #{yield if block_given?}
+
+     Best,
+
+     The Example.com Team
+     _
+  end
+end

data/lib/supermail/version.rb

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

data/lib/supermail.rb

@@ -1,85 +1,58 @@
 # frozen_string_literal: true
 
 require_relative "supermail/version"
-
-require 'mail'
-require "supermail/version"
+require "action_mailer"
+require "erb"
 
 module Supermail
   class Error < StandardError; end
 
-  # A simple Email builder that wraps Mail::Message
-  class Email
-    # Hook to ensure default initialization runs before any subclass initialize
-    module Defaults
-      def initialize(*args, &block)
-        # default fields
-        @cc = []
-        @bcc = []
-        @headers = {}
-        @attachments = []
-        super
+  module Rails
+    class Base
+      delegate \
+          :deliver,
+          :deliver_now,
+          :deliver_later,
+          :message,
+        to: :action_mailer_base_mail
+
+      def to = nil
+      def from = nil
+      def subject = nil
+      def cc = []
+      def bcc = []
+      def body = ""
+
+      # Generate a mailto: URL with appropriate escaping.
+      def mailto = MailTo.href(to:, from:, cc:, bcc:, subject:, body:)
+      alias :mail_to :mailto
+
+      private def action_mailer_base_mail
+        ActionMailer::Base.mail(to:, from:, cc:, bcc:, subject:, body:)
       end
     end
+  end
 
-    # Whenever subclassing, prepend Defaults to ensure it wraps initialize
-    def self.inherited(subclass)
-      subclass.prepend Defaults
-      super
-    end
-
-    attr_accessor :from, :to, :cc, :bcc, :subject,
-                  :reply_to, :return_path, :date, :message_id,
-                  :in_reply_to, :references, :headers,
-                  :text_body, :html_body, :attachments
-
-    # Builds a Mail::Message from this Email's attributes
-    # @return [Mail::Message]
-    def message
-      mail = Mail.new
-      mail.from        = Array(from) if from
-      mail.to          = Array(to)
-      mail.cc          = cc if cc.any?
-      mail.bcc         = bcc if bcc.any?
-      mail.reply_to    = Array(reply_to) if reply_to
-      mail.return_path = return_path if return_path
-      mail.date        = date if date
-      mail.message_id  = message_id if message_id
-      mail.in_reply_to = in_reply_to if in_reply_to
-      mail.references  = references if references
-
-      # Custom headers
-      headers.each { |key, value| mail.header[key] = value }
-
-      mail.subject = subject if subject
-
-      # Bodies
-      if text_body
-        mail.text_part = Mail::Part.new do
-          body text_body
-        end
-      end
-
-      if html_body
-        mail.html_part = Mail::Part.new do
-          content_type 'text/html; charset=UTF-8'
-          body html_body
-        end
-      end
+  module MailTo
+    extend self
 
-      # Attachments (each as a hash: { filename:, content: })
-      attachments.each do |att|
-        mail.add_file filename: att[:filename], content: att[:content]
-      end
+    def href(to:, **params)
+      q = query(**params)
+      q.empty? ? "mailto:#{to}" : "mailto:#{to}?#{q}"
+    end
 
-      mail
+    def query(**params)
+      params
+        .compact                          # drop nils
+        .reject { |k, v| v.is_a?(Array) && v.empty? }  # drop empty arrays
+        .map { |k, v| "#{k}=#{mailto_escape(v)}" }
+        .join("&")
     end
 
-    # Delivers the built Mail::Message via its configured delivery_method
-    # @return [Mail::Message]
-    def deliver
-      raise Error, "`to` address is required" unless to
-      message.deliver!
+    private
+
+    def mailto_escape(str)
+      ERB::Util.url_encode(str.to_s).tr("+", "%20")
     end
   end
 end

metadata

@@ -1,28 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: supermail
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Brad Gessler
 bindir: exe
 cert_chain: []
-date: 2025-04-17 00:00:00.000000000 Z
+date: 2025-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: mail
+  name: actionmailer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 description: Build emails with plain ol' Ruby objects.
 email:
 - bradgessler@gmail.com
@@ -33,16 +47,20 @@ files:
 - ".rspec"
 - README.md
 - Rakefile
+- lib/generators/supermail/email/email_generator.rb
+- lib/generators/supermail/email/templates/email.rb.tt
+- lib/generators/supermail/install/install_generator.rb
+- lib/generators/supermail/install/templates/application_email.rb.tt
 - lib/supermail.rb
 - lib/supermail/version.rb
 - sig/supermail.rbs
-homepage: https://github.com/rubymonolith/supermail
+homepage: https://github.com/beautifulruby/supermail
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/rubymonolith/supermail
-  source_code_uri: https://github.com/rubymonolith/supermail
-  changelog_uri: https://github.com/rubymonolith/supermail
+  homepage_uri: https://github.com/beautifulruby/supermail
+  source_code_uri: https://github.com/beautifulruby/supermail
+  changelog_uri: https://github.com/beautifulruby/supermail
 rdoc_options: []
 require_paths:
 - lib