{"id":15890363,"url":"https://github.com/dxw/mail-notify","last_synced_at":"2025-04-06T13:09:02.629Z","repository":{"id":37550393,"uuid":"168383163","full_name":"dxw/mail-notify","owner":"dxw","description":"Rails plugin, send and preview email with GOV.UK Notify","archived":false,"fork":false,"pushed_at":"2025-03-24T12:22:36.000Z","size":519,"stargazers_count":5,"open_issues_count":3,"forks_count":15,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-30T12:09:44.983Z","etag":null,"topics":["actionmailer","delivery-plus","gem","govuk","govuk-notify","rails","ruby"],"latest_commit_sha":null,"homepage":"https://www.notifications.service.gov.uk/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dxw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-30T17:17:09.000Z","updated_at":"2025-03-24T12:20:38.000Z","dependencies_parsed_at":"2024-03-22T11:55:56.782Z","dependency_job_id":"20d34ce5-1a1b-4bad-be38-0a98707d4bad","html_url":"https://github.com/dxw/mail-notify","commit_stats":{"total_commits":199,"total_committers":17,"mean_commits":"11.705882352941176","dds":0.6080402010050252,"last_synced_commit":"c9514b238b0cfeae9e671920741708acbe274910"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxw%2Fmail-notify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxw%2Fmail-notify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxw%2Fmail-notify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxw%2Fmail-notify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dxw","download_url":"https://codeload.github.com/dxw/mail-notify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485287,"owners_count":20946398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actionmailer","delivery-plus","gem","govuk","govuk-notify","rails","ruby"],"created_at":"2024-10-06T07:05:25.131Z","updated_at":"2025-04-06T13:09:02.610Z","avatar_url":"https://github.com/dxw.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![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)\n[![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)\n[![Gem Version](http://img.shields.io/gem/v/mail-notify.svg?style=flat-square)](https://rubygems.org/gems/mail-notify)\n[![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)\n[![License](http://img.shields.io/:license-mit-blue.svg)](https://mit-license.org/)\n\n# mail-notify\n\nRails plugin for [GOV.UK Notify](https://www.notifications.service.gov.uk).\n\n[Great products and services like yours use mail-notify!](https://github.com/dxw/mail-notify/wiki#some-services-and-products-that-use-mail-notify)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'mail-notify'\n```\n\nAnd then execute:\n\n    $ bundle\n\n## Configuration\n\nConfigure in each environment `config/environments/*.rb` (where * is `test`,\n`development`, `production` or whatever other environment(s) you have) file(s):\n\n```ruby\nconfig.action_mailer.delivery_method = :notify\nconfig.action_mailer.notify_settings = {\n  api_key: YOUR_NOTIFY_API_KEY\n}\n```\n\nWe recommend using separate Notify 'test' API keys (email will not be sent but\ncan be seen in Notify) in all environments except production so you can confirm\nthe integration and generate previews without actually sending any email.\n\nIf you're using a different Notify service to GOV.UK Notify (for example [GOV.CA\nNotify](https://notification.alpha.canada.ca/)), you can also specify the Base\nURL in your setup:\n\n```ruby\nconfig.action_mailer.delivery_method = :notify\nconfig.action_mailer.notify_settings = {\n  api_key: YOUR_NOTIFY_API_KEY,\n  base_url: 'https://api.notification.alpha.canada.ca'\n}\n```\n\n### Mailers\n\nThere are two options for using mail-notify, manage the content in Notify\nwith [template mailers](#template-mailers) or in Rails with [view\nmailers](#view-mailers) you can mix the two approaches as you need.\n\nWhichever you choose, you'll need your mailers to inherit from `Mail::Notify::Mailer` like so:\n\n```ruby\nclass MyCustomMailer \u003c Mail::Notify::Mailer\nend\n```\n\nWe recommend going 'all in' with Notify and having `ApplicationMailer` inherit\nfor mail-notify:\n\n```ruby\nclass ApplicationMailer \u003c Mail::Notify::Mailer\nend\n```\n\nthen have each mailer inherit from `ApplicationMailer`:\n\n```ruby\nclass MyCustomMailer \u003c ApplicationMailer\nend\n```\n\n#### Template mailers\n\nTemplate mailers only require the template ID from Notify and an to email\naddress, all of the content for the email is managed in Notify:\n\n```ruby\nclass MyCustomMailer \u003c ApplicationMailer\n    def welcome_email\n        to = params[:to]\n\n        template_mail(\"NOTIFY_TEMPLATE_ID\", to: to)\n    end\nend\n\n# call the template mailer\nMyCustomMailer.with(to: \"first.last@example.com\").welcome_email.deliver_now!\n```\n\nYou can add any number of\n[personalisations](https://www.notifications.service.gov.uk/using-notify/personalisation) to template mailers:\n\n```ruby\nclass MyCustomMailer \u003c ApplicationMailer\n    def appointment_email\n        to = params[:to]\n        name = params[:name]\n        appointment_date = params[:appointment_date]\n\n        template_mail(\n            \"NOTIFY_TEMPLATE_ID\", \n            to: to,\n            personalisation: {\n                name: name,\n                appointment_date: date.to_s\n            }\n        )\n    end\nend\n\n# call the template mailer with personalisation options\nMyCustomMailer.with(\n    to: \"first.last@example.com\", \n    name: \"First Last\", \n    appointment_date: Date.new(2024, 01, 01)\n).appointment_email.deliver_now!\n```\n\nA note on blank personalisation; The Notify API will not allow `nil`\npersonalisation, if you expect `nil` values, you can wrap them in\n`blank_allowed` which converts them to an empty string:\n\n```ruby\nMyCustomMailer.with(\n    to: \"first.last@example.com\", name: blank_allowed(user.name)).welcome_email.deliver_now!\n```\n\nOr use params as the examples above.\n\n#### View mailers\n\nView mailers let you manage the content of emails with a Rails text view, with\nNotify's markdown like\n[formatting](https://www.notifications.service.gov.uk/using-notify/formatting)\nsupported.\n\nYou will still require a template in Notify, the template must be setup with\n`subject` and `body` personalisations, which will be replaced with those from\nyour mailer and view:\n\n![Screenshot of a view mailer template in Notify](docs/assets/images/view_template_in_notify.png)\n\nYour view mailer is then setup like this:\n\n```ruby\nclass MyCustomMailer \u003c ApplicationMailer\n    def welcome_email\n        to = params[:to]\n        subject= params[:subject]\n\n        view_mail(\"NOTIFY_TEMPLATE_ID\", to: to, subject: subject)\n    end\n```\n\nWith a `subject` being required.\n\nAdd the view named appropriately and in the conventional location:\n\n`app/views/my_custom_mailer/welcome_email.text.erb`\n\nAdd content to the view:\n\n```\nDear \u003c%= @user.name %\u003e\n\n# Welcome to the service.\n\nHere are some points to note:\n\n* point one\n* point two\n* point three\n\n^ Don't forget this.\n\n```\n\nThen call the mailer as usual:\n\n```ruby\nMyCustomMailer.with(\n    to: \"first.last@example.com\", \n    subject: \"Welcome to service\"\n).welcome_email.deliver_now!\n\n```\n\nOnly plain text views can be used, with the Notify markdown like formatting\noptions. The email is sent as both HTML and plain text by Notify.\n\n#### With optional Notify arguments\n\nIt's possible to pass two optional arguments to Notify with either template or\nview mailers.\n\n- `reply_to_id`: This is an email reply-to address specified by you to receive\n  replies from your users\n- `reference`: A unique identifier you can create if necessary. This reference\n  identifies a single unique notification or a batch of notifications\n- `one_click_unsubscribe_url`: The URL email client will POST to in order to\n  unsubscribe from the mailing list\n\nMore information can be [found in the\nNotify docs](https://docs.notifications.service.gov.uk/ruby.html#send-an-email-arguments-personalisation-optional)\n\n```ruby\nclass MyCustomMailer \u003c ApplicationMailer\n    def welcome_email\n        to = params[:to]\n        reference = params[:reference]\n        reply_to_id = params[:reply_to_id]\n\n        template_mail(\"NOTIFY_TEMPLATE_ID\", to: to, reply_to_id: reply_to_id, reference: reference)\n    end\nend\n\n# call the mailer\nMyCustomMailer.with(\n        to: \"first.last@example.com\", \n        reference: \"YOUR_REFERENCE\",\n        reply_to_id: \"YOUR_REPLY_TO\"\n    ).welcome_email.deliver_now!\n```\n\n## Previews\n\nRails [previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails)\nare supported.\n\nThe Rails delivery method must be set to `:notify` and a Notify API key will be\nrequired for previews to work as the [preview is\ngenerated](https://docs.notifications.service.gov.uk/ruby.html#generate-a-preview-template)\nby the Notify API.\n\n## With Devise\n\nMail-notify is compatible with anything that uses ActionMailer,\n[Devise](https://github.com/heartcombo/devise) is a popular authentication gem\nthat uses ActionMailer to send emails relating to\naccounts, see [instructions in the\nwiki](https://github.com/dxw/mail-notify/wiki/Use-with-Devise) for more details\nof using mail-notify with Devise.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`bin/rspec` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo release a new version, update the version number in `version.rb`, and then\ntag the commit on main - the release will be built and published by the\n`publish.yml` GitHub action.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/dxw/mail-notify. This project is intended to be a safe,\nwelcoming space for collaboration, and contributors are expected to adhere to\nthe [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT\nLicense](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Mail::Notify project’s codebases, issue trackers,\nchat rooms and mailing lists is expected to follow the [code of\nconduct](https://github.com/pezholio/mail-notify/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdxw%2Fmail-notify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdxw%2Fmail-notify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdxw%2Fmail-notify/lists"}