mail-notify 1.2.0 → 2.1.0

data/README.md

@@ -1,11 +1,14 @@
-[![Build Status](https://github.com/dxw/mail-notify/workflows/Build/badge.svg)](https://github.com/dxw/mail-notify/actions)
-[![Coverage Status](https://img.shields.io/coveralls/github/pezholio/mail-notify.svg?style=flat-square)](https://coveralls.io/github/pezholio/mail-notify)
+[![Build status](https://github.com/dxw/mail-notify/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/dxw/mail-notify/actions/workflows/unit-tests.yml)
+[![Coverage status](https://coveralls.io/repos/github/dxw/mail-notify/badge.svg?branch=fix-coveralls)](https://coveralls.io/github/dxw/mail-notify?branch=fix-coveralls)
 [![Gem Version](http://img.shields.io/gem/v/mail-notify.svg?style=flat-square)](https://rubygems.org/gems/mail-notify)
+[![Rails integration tests](https://github.com/dxw/mail-notify/actions/workflows/rails-integration-tests.yml/badge.svg)](https://github.com/dxw/mail-notify/actions/workflows/rails-integration-tests.yml)
 [![License](http://img.shields.io/:license-mit-blue.svg)](https://mit-license.org/)
 
-# Mail::Notify
+# mail-notify
 
-Rails / ActionMailer support for the [GOV.UK Notify API](https://www.notifications.service.gov.uk).
+Rails plugin for [GOV.UK Notify](https://www.notifications.service.gov.uk).
+
+[Great products and services like yours use mail-notify!](https://github.com/dxw/mail-notify/wiki#some-services-and-products-that-use-mail-notify)
 
 ## Installation
 
@@ -19,11 +22,10 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
-
-    $ gem install mail-notify
+## Configuration
 
-Then, add the following to your `config/environments/*.rb` (where * is `test`, `development`, `production` or whatever other environment(s) you have) file(s):
+Configure in each environment `config/environments/*.rb` (where * is `test`,
+`development`, `production` or whatever other environment(s) you have) file(s):
 
 ```ruby
 config.action_mailer.delivery_method = :notify
@@ -32,7 +34,13 @@ config.action_mailer.notify_settings = {
 }
 ```
 
-If you're using a different Notify service to GOV.UK Notify (for example [GOV.CA Notify](https://notification.alpha.canada.ca/)), you can also specify the Base URL in your setup:
+We recommend using separate Notify 'test' API keys (email will not be sent but
+can be seen in Notify) in all environments except production so you can confirm
+the integration and generate previews without actually sending any email.
+
+If you're using a different Notify service to GOV.UK Notify (for example [GOV.CA
+Notify](https://notification.alpha.canada.ca/)), you can also specify the Base
+URL in your setup:
 
 ```ruby
 config.action_mailer.delivery_method = :notify
@@ -44,131 +52,228 @@ config.action_mailer.notify_settings = {
 
 ### Mailers
 
-There are two options for using `Mail::Notify`, either templating in Rails with a view, or templating in Notify. Whichever way you choose, you'll need your mailers to inherit from `Mail::Notify::Mailer` like so:
+There are two options for using mail-notify, manage the content in Notify
+with [template mailers](#template-mailers) or in Rails with [view
+mailers](#view-mailers) you can mix the two approaches as you need.
+
+Whichever you choose, you'll need your mailers to inherit from `Mail::Notify::Mailer` like so:
 
 ```ruby
-class MyMailer < Mail::Notify::Mailer
+class MyCustomMailer < Mail::Notify::Mailer
 end
 ```
 
-#### With a view
+We recommend going 'all in' with Notify and having `ApplicationMailer` inherit
+for mail-notify:
+
+```ruby
+class ApplicationMailer < Mail::Notify::Mailer
+end
+```
 
-Out of the box, Notify offers support for templating, with some rudimentary logic included. If you'd rather have your templating logic included with your source code for ease of access, or you want to do some more complex logic that's not supported by Notify, you can template your mailer views in erb.
+then have each mailer inherit from `ApplicationMailer`:
 
-For this to work with Notify, you'll need a very simple template set up in Notify, with a `((subject))` variable in the subject line, and a `((body))` variable in the body field, as below:
+```ruby
+class MyCustomMailer < ApplicationMailer
+end
+```
 
-![Example screenshot](docs/screenshot.png)
+#### Template mailers
 
-Next, in your mailer you'll need to call `view_mail` with the first parameter being the ID of the notify template, followed by a hash of email headers e.g:
+Template mailers only require the template ID from Notify and an to email
+address, all of the content for the email is managed in Notify:
 
 ```ruby
-class MyMailer < Mail::Notify::Mailer
-    def send_email
-        view_mail('YOUR_TEMPLATE_ID_GOES_HERE',
-          to: 'mail@somewhere.com',
-          subject: 'Subject line goes here'
-        )
+class MyCustomMailer < ApplicationMailer
+    def welcome_email
+        to = params[:to]
+
+        template_mail("NOTIFY_TEMPLATE_ID", to: to)
     end
 end
-```
-
-Your view can then be a simple `text.erb` file. You can add some markdown for headers, bullet points and links etc. These are handled in the same way as standard action_mailer views.
 
-#### With Notify templating
+# call the template mailer
+MyCustomMailer.with(to: "first.last@example.com").welcome_email.deliver_now!
+```
 
-You can also send your customisations in the more traditional way, and do your templating in Notify if you prefer. For this, you'll need to call `template_mail`, again with the first parameter being the ID of the template, and a hash of email headers, including your personalisations, e.g:
+You can add any number of
+[personalisations](https://www.notifications.service.gov.uk/using-notify/personalisation) to template mailers:
 
 ```ruby
-class MyMailer < Mail::Notify::Mailer
-    def send_email
-        template_mail('YOUR_TEMPLATE_ID_GOES_HERE',
-          to: 'mail@somewhere.com',
-          personalisation: {
-              foo: 'bar'
-          }
+class MyCustomMailer < ApplicationMailer
+    def appointment_email
+        to = params[:to]
+        name = params[:name]
+        appointment_date = params[:appointment_date]
+
+        template_mail(
+            "NOTIFY_TEMPLATE_ID", 
+            to: to,
+            personalisation: {
+                name: name,
+                appointment_date: date.to_s
+            }
         )
     end
 end
+
+# call the template mailer with personalisation options
+MyCustomMailer.with(
+    to: "first.last@example.com", 
+    name: "First Last", 
+    appointment_date: Date.new(2024, 01, 01)
+).appointment_email.deliver_now!
 ```
 
-By default, any blank personalisation are removed from the request, which will trigger mail template validation. This is to avoid accidental blanks in the email. If you want to send a blank value, you need to explicitly state that the personalization can be blank:  
+A note on blank personalisation; The Notify API will not allow `nil`
+personalisation, if you expect `nil` values, you can wrap them in
+`blank_allowed` which converts them to an empty string:
 
 ```ruby
-class MyMailer < Mail::Notify::Mailer
-  def send_email
-    template_mail('YOUR_TEMPLATE_ID_GOES_HERE',
-                  to: 'mail@somewhere.com',
-                  personalisation: {
-                    foo: foo.name, # This will trigger template validation error when blank
-                    bar: blank_allowed(bar.name) # This will inject empty string in the template when blank
-                  }
-    )
-  end
-end
+MyCustomMailer.with(
+    to: "first.last@example.com", name: blank_allowed(user.name)).welcome_email.deliver_now!
 ```
 
+Or use params as the examples above.
 
-#### With optional Notify arguments
+#### View mailers
+
+View mailers let you manage the content of emails with a Rails text view, with
+Notify's markdown like
+[formatting](https://www.notifications.service.gov.uk/using-notify/formatting)
+supported.
 
-It's possible to pass two optional arguments to Notify:
+You will still require a template in Notify, the template must be setup with
+`subject` and `body` personalisations, which will be replaced with those from
+your mailer and view:
 
-- `reply_to_id`: This is an email reply-to address specified by you to receive replies from your users
-- `reference`: A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications
+![Screenshot of a view mailer template in Notify](docs/assets/images/view_template_in_notify.png)
 
-More information can be [found in the docs](https://docs.notifications.service.gov.uk/ruby.html#send-an-email-arguments-personalisation-optional)
+Your view mailer is then setup like this:
 
 ```ruby
-class MyMailer < Mail::Notify::Mailer
-    def send_email
-        view_mail('YOUR_TEMPLATE_ID_GOES_HERE',
-          to: 'mail@somewhere.com',
-          subject: 'Subject line goes here',
-          reply_to_id: 'YOUR_REPLY_TO_ID_GOES_HERE',
-          reference: 'ABC123XYZ'
-        )
+class MyCustomMailer < ApplicationMailer
+    def welcome_email
+        to = params[:to]
+        subject= params[:subject]
+
+        view_mail("NOTIFY_TEMPLATE_ID", to: to, subject: subject)
     end
-end
 ```
 
-#### With Devise
+With a `subject` being required.
 
-If you're using [Devise](https://github.com/heartcombo/devise), you can overwrite your Devise mailer to use mail-notify for password reset emails etc.
+Add the view named appropriately and in the conventional location:
 
-In `config/initializers/devise.rb`:
+`app/views/my_custom_mailer/welcome_email.text.erb`
+
+Add content to the view:
+
+```
+Dear <%= @user.name %>
+
+# Welcome to the service.
+
+Here are some points to note:
+
+* point one
+* point two
+* point three
+
+^ Don't forget this.
+
+```
+
+Then call the mailer as usual:
 
 ```ruby
-config.mailer = 'DeviseMailer'
+MyCustomMailer.with(
+    to: "first.last@example.com", 
+    subject: "Welcome to service"
+).welcome_email.deliver_now!
+
 ```
 
-in `app/mailers/devise_mailer.rb`:
+Only plain text views can be used, with the Notify markdown like formatting
+options. The email is sent as both HTML and plain text by Notify.
+
+#### With optional Notify arguments
+
+It's possible to pass two optional arguments to Notify with either template or
+view mailers.
+
+- `reply_to_id`: This is an email reply-to address specified by you to receive
+  replies from your users
+- `reference`: A unique identifier you can create if necessary. This reference
+  identifies a single unique notification or a batch of notifications
+- `one_click_unsubscribe_url`: The URL email client will POST to in order to
+  unsubscribe from the mailing list
+
+More information can be [found in the
+Notify docs](https://docs.notifications.service.gov.uk/ruby.html#send-an-email-arguments-personalisation-optional)
 
 ```ruby
-class DeviseMailer < Devise::Mailer
-  def devise_mail(record, action, opts = {}, &block)
-    initialize_from_record(record)
-    view_mail(ENV['NOTIFY_TEMPLATE_ID'], headers_for(action, opts))
-  end
+class MyCustomMailer < ApplicationMailer
+    def welcome_email
+        to = params[:to]
+        reference = params[:reference]
+        reply_to_id = params[:reply_to_id]
+
+        template_mail("NOTIFY_TEMPLATE_ID", to: to, reply_to_id: reply_to_id, reference: reference)
+    end
 end
+
+# call the mailer
+MyCustomMailer.with(
+        to: "first.last@example.com", 
+        reference: "YOUR_REFERENCE",
+        reply_to_id: "YOUR_REPLY_TO"
+    ).welcome_email.deliver_now!
 ```
 
 ## Previews
 
-If you're using ActionMailer with Rails, [previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails) are supported too, and work in the same way as standard previews. Currently they're shown without any branding, but this may change in future.
+Rails [previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails)
+are supported.
+
+The Rails delivery method must be set to `:notify` and a Notify API key will be
+required for previews to work as the [preview is
+generated](https://docs.notifications.service.gov.uk/ruby.html#generate-a-preview-template)
+by the Notify API.
+
+## With Devise
+
+Mail-notify is compatible with anything that uses ActionMailer,
+[Devise](https://github.com/heartcombo/devise) is a popular authentication gem
+that uses ActionMailer to send emails relating to
+accounts, see [instructions in the
+wiki](https://github.com/dxw/mail-notify/wiki/Use-with-Devise) for more details
+of using mail-notify with Devise.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/rspec` 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version, update the version number in `version.rb`, and then
+tag the commit on main - the release will be built and published by the
+`publish.yml` GitHub action.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/dxw/mail-notify. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/dxw/mail-notify. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to
+the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## 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).
 
 ## Code of Conduct
 
-Everyone interacting in the Mail::Notify project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/pezholio/mail-notify/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Mail::Notify project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the [code of
+conduct](https://github.com/pezholio/mail-notify/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,12 +1,7 @@
-# frozen_string_literal: true
-
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "standard/rake"
-require "coveralls/rake/task"
-
-Coveralls::RakeTask.new
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: %i[standard spec coveralls:push]
+task default: %i[standard spec]

data/{lib/mail/notify → app/views}/layouts/govuk_notify_layout.html.erb

@@ -1,14 +1,14 @@
-<%# Copied from GOV.UK Notify: https://raw.githubusercontent.com/alphagov/notifications-utils/d69de041d1be7b826e7d9cc56450e157ad361799/notifications_utils/jinja_templates/email_template.jinja2 %>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<!-- Template sourced from https://github.com/alphagov/notifications-utils/blob/main/notifications_utils/jinja_templates/email_template.jinja2 -->
+<!DOCTYPE html>
+<html lang="en">
 
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-  <meta content="telephone=no" name="format-detection" /> <!-- need to add formatting for real phone numbers -->
-  <meta name="viewport" content="width=device-width" />
-  <title>Page title</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+  <meta content="telephone=no" name="format-detection"> <!-- need to add formatting for real phone numbers -->
+  <meta name="viewport" content="width=device-width">
+  <title>{{ subject }}</title>
 
-  <style type="text/css">
+  <style>
     @media only screen and (min-device-width: 581px) {
       .content {
         width: 580px !important;
@@ -19,7 +19,7 @@
   </style>
 
   <!--[if gte mso 9]>
-    <style type="text/css">
+    <style>
       li {
         margin-left: 4px !important;
       }
@@ -33,8 +33,7 @@
 </head>
 
 <body style="font-family: Helvetica, Arial, sans-serif;font-size: 16px;margin: 0;color:#0b0c0c;">
-
-<span style="display: none;font-size: 1px;color: #fff; max-height: 0;"></span>
+<span style="display: none;font-size: 1px;color: #fff; max-height: 0;" hidden>{{ preheader }}…</span>
   <table role="presentation" width="100%" style="border-collapse: collapse;min-width: 100%;width: 100% !important;" cellpadding="0" cellspacing="0" border="0">
     <tr>
       <td width="100%" height="53" bgcolor="#0b0c0c">
@@ -51,20 +50,20 @@
                   <tr>
                     <td style="padding-left: 10px">
                       <img
-                        src="https://static.notifications.service.gov.uk/images/gov.uk_logotype_crown.png"
-                        alt=" "
+                        src="https://static.notifications.service.gov.uk/images/govuk-logotype-tudor-crown.png"
+                        alt=""
                         height="32"
                         border="0"
-                        style="Margin-top: 4px;"
-                      />
+                        style="Margin-top: 2px;"
+                      >
                     </td>
-                    <td style="font-size: 28px; line-height: 1.315789474; Margin-top: 4px; padding-left: 10px;">
+                    <td style="font-size: 28px; line-height: 1.315789474; Margin-top: 4px; padding-left: 8px;">
                       <span style="
                         font-family: Helvetica, Arial, sans-serif;
                         font-weight: 700;
                         color: #ffffff;
                         text-decoration: none;
-                        vertical-align:top;
+                        vertical-align:middle;
                         display: inline-block;
                           ">GOV.UK</span>
                     </td>
@@ -102,7 +101,7 @@
         <![endif]-->
                 <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="border-collapse: collapse;">
                   <tr>
-                    <td bgcolor="#005EA5" width="100%" height="10"></td>
+                    <td bgcolor="#1D70B8" width="100%" height="10"></td>
                   </tr>
                 </table>
         <!--[if (gte mso 9)|(IE)]>
@@ -114,7 +113,6 @@
       <td width="10" valign="middle" height="10"></td>
     </tr>
   </table>
-
   <table
       role="presentation"
       class="content"
@@ -126,27 +124,27 @@
       width="100%"
   >
     <tr>
-      <td height="30"><br /></td>
+      <td height="30"><br></td>
     </tr>
     <tr>
-      <td width="10" valign="middle"><br /></td>
+      <td width="10" valign="middle"><br></td>
       <td style="font-family: Helvetica, Arial, sans-serif; font-size: 19px; line-height: 1.315789474; max-width: 560px;">
         <!--[if (gte mso 9)|(IE)]>
           <table role="presentation" width="560" align="center" cellpadding="0" cellspacing="0" border="0" style="border-collapse: collapse;width: 560px;">
             <tr>
               <td style="font-family: Helvetica, Arial, sans-serif; font-size: 19px; line-height: 1.315789474;">
-        <![endif]-->
-            <%= yield %>
+                <![endif]-->
+        <%= yield %>
         <!--[if (gte mso 9)|(IE)]>
               </td>
             </tr>
           </table>
         <![endif]-->
       </td>
-      <td width="10" valign="middle"><br /></td>
+      <td width="10" valign="middle"><br></td>
     </tr>
     <tr>
-      <td height="30"><br /></td>
+      <td height="30"><br></td>
     </tr>
   </table>
 </body>

data/bin/console

@@ -2,14 +2,9 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
+require 'action_mailer'
+require 'action_controller'
 require 'mail/notify'
+require 'pry'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)
+Pry.start

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/standardrb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'standardrb' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("standard", "standardrb")

data/lib/mail/notify/delivery_method.rb

@@ -6,20 +6,29 @@ module Mail
       attr_accessor :settings, :response
 
       def initialize(settings)
-        raise ArgumentError, "You must specify an API key" if settings[:api_key].blank?
+        raise ArgumentError, "You must specify a Notify API key" if settings[:api_key].blank?
 
         @settings = settings
       end
 
-      def deliver!(mail)
-        @mail = mail
-        @personalisation = Personalisation.new(mail)
-        send_email
+      def deliver!(message)
+        params = {
+          template_id: message.template_id,
+          email_address: message.to.first,
+          personalisation: message.personalisation,
+          email_reply_to_id: message.reply_to_id,
+          reference: message.reference,
+          one_click_unsubscribe_url: message.one_click_unsubscribe_url
+        }
+
+        client.send_email(params.compact)
       end
 
-      def preview(mail)
-        personalisation = Personalisation.new(mail).to_h
-        template_id = mail[:template_id].to_s
+      def preview(message)
+        template_id = message.template_id
+        personalisation = message.personalisation
+
+        Rails.logger.info("Getting Notify preview for template id #{template_id}")
         client.generate_template_preview(template_id, personalisation: personalisation)
       end
 
@@ -28,24 +37,6 @@ module Mail
       def client
         @client ||= Notifications::Client.new(@settings[:api_key], @settings[:base_url])
       end
-
-      def email_params
-        {
-          email_address: @mail.to.first,
-          template_id: @mail[:template_id].to_s,
-          personalisation: @personalisation.to_h,
-          email_reply_to_id: optional_param(:reply_to_id),
-          reference: optional_param(:reference)
-        }
-      end
-
-      def optional_param(name)
-        @mail[name].presence&.to_s
-      end
-
-      def send_email
-        @response = client.send_email(email_params.compact)
-      end
     end
   end
 end

data/lib/mail/notify/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mail
+  module Notify
+    class Engine < Rails::Engine
+      initializer "mail-notify.add_delivery_method", before: "action_mailer.set_configs" do
+        ActionMailer::Base.add_delivery_method(:notify, Mail::Notify::DeliveryMethod)
+
+        config.action_mailer.preview_interceptors = [:mail_notify_preview_interceptor]
+      end
+    end
+  end
+end