Organize emails with plain 'ol Ruby objects in a Rails application:
classUser::WelcomeEmail < ApplicationEmaildefinitialize(user:)@user=userenddefto=@user.emaildefsubject="Welcome to Beautiful Ruby"defplain=<<~TEXT Hi #{@user.name}, You're going to learn a ton at https://beautifulruby.com. TEXTdefhtml=safe <<~HTML
<h1>Hi#{@user.name},</h1>
<p>You'regoingtolearnatonat <ahref="https://beautifulruby.com">BeautifulRuby</a>.</p>
HTMLendOr use ERB templates like Rails:
# app/emails/welcome_email.rbclassWelcomeEmail < ApplicationEmailincludeSupermail::Rails::Renderingdefinitialize(user:)@user=userenddefto=@user.emaildefsubject="Welcome!"# Templates automatically resolved from app/emails/welcome_email.html.erb and .text.erbend<!-- app/emails/welcome_email.html.erb --><h1>Hi <%=@user.name%>,</h1><p>Welcome to the app!</p>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 initialize an email and send it. PORO's FTW!
Learn how to build UI's out of Ruby classes and support this project by ordering the Phlex on Rails video course.
Install the gem and add to the application's Gemfile by executing:
bundle add supermailThen install it in Rails.
rails generate supermail:installThis creates the ApplicationEmail class at app/emails/application_email.rb.
Define emails by overriding to, from, subject, plain, and html methods:
classWelcomeEmail < ApplicationEmaildefinitialize(user:)@user=userenddefto=@user.emaildefsubject="Welcome!"defplain="Welcome to the app, #{@user.name}!"defhtml=safe"<h1>Welcome to the app, #{@user.name}!</h1>"end- If both
plainandhtmlare defined, a multipart email is sent - If only
plainis defined, a text-only email is sent - If only
htmlis defined, an HTML-only email is sent
Use before_* and after_* hooks in your base class to wrap all emails:
classApplicationEmail < Supermail::Rails::Basedeffrom="website@example.com"defbefore_html="<html><body>"defafter_html=<<~HTML<p>Best,<br>The Example.com Team</p></body></html> HTMLdefafter_plain=<<~TEXT Best, The Example.com Team TEXTendChild emails just define their content - the hooks handle the wrapping:
classWelcomeEmail < ApplicationEmaildefsubject="Welcome!"defplain="Welcome to the app!"defhtml=safe"<h1>Welcome!</h1>"endReturn any object that responds to #call from html:
classWelcomeEmail < ApplicationEmaildefhtml=WelcomeEmailView.new(user: @user)endOverride html_body for post-processing like CSS inlining:
classApplicationEmail < Supermail::Rails::Baseprotecteddefhtml_bodycontent=superreturnnilunlesscontentPremailer.new(content,with_html_string: true).to_inline_cssendendWelcomeEmail.new(user: User.first).deliver_nowWelcomeEmail.new(user: User.first).deliver_later<%= link_to "Contact Support", SupportEmail.new(user: current_user).mailto %>Generate a new email:
rails generate supermail:email User::WelcomeCreates app/emails/user/welcome_email.rb.
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. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/rubymonolith/supermail.