Rails plugin for GOV.UK Notify.
Great products and services like yours use mail-notify!
Add this line to your application's Gemfile:
gem 'mail-notify'And then execute:
$ bundle
Configure in each environment config/environments/*.rb (where * is test,
development, production or whatever other environment(s) you have) file(s):
config.action_mailer.delivery_method = :notify
config.action_mailer.notify_settings = {
api_key: YOUR_NOTIFY_API_KEY
}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), you can also specify the Base URL in your setup:
config.action_mailer.delivery_method = :notify
config.action_mailer.notify_settings = {
api_key: YOUR_NOTIFY_API_KEY,
base_url: 'https://api.notification.alpha.canada.ca'
}There are two options for using mail-notify, manage the content in Notify with template mailers or in Rails with 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:
class MyCustomMailer < Mail::Notify::Mailer
endWe recommend going 'all in' with Notify and having ApplicationMailer inherit
for mail-notify:
class ApplicationMailer < Mail::Notify::Mailer
endthen have each mailer inherit from ApplicationMailer:
class MyCustomMailer < ApplicationMailer
endTemplate mailers only require the template ID from Notify and an to email address, all of the content for the email is managed in Notify:
class MyCustomMailer < ApplicationMailer
def welcome_email
to = params[:to]
template_mail("NOTIFY_TEMPLATE_ID", to: to)
end
end
# call the template mailer
MyCustomMailer.with(to: "[email protected]").welcome_email.deliver_now!You can add any number of personalisations to template mailers:
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: "[email protected]",
name: "First Last",
appointment_date: Date.new(2024, 01, 01)
).appointment_email.deliver_now!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:
MyCustomMailer.with(
to: "[email protected]", name: blank_allowed(user.name)).welcome_email.deliver_now!Or use params as the examples above.
View mailers let you manage the content of emails with a Rails text view, with Notify's markdown like formatting supported.
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:
Your view mailer is then setup like this:
class MyCustomMailer < ApplicationMailer
def welcome_email
to = params[:to]
subject= params[:subject]
view_mail("NOTIFY_TEMPLATE_ID", to: to, subject: subject)
endWith a subject being required.
Add the view named appropriately and in the conventional location:
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:
MyCustomMailer.with(
to: "[email protected]",
subject: "Welcome to service"
).welcome_email.deliver_now!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.
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 usersreference: A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications
More information can be found in the Notify docs
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: "[email protected]",
reference: "YOUR_REFERENCE",
reply_to_id: "YOUR_REPLY_TO"
).welcome_email.deliver_now!Rails previews 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
by the Notify API.
Mail-notify is compatible with anything that uses ActionMailer, Devise is a popular authentication gem that uses ActionMailer to send emails relating to accounts, see instructions in the wiki for more details of using mail-notify with Devise.
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 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.
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 code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Mail::Notify project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent