mail-notify 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c412b0f242555ce3f351f10a14e854cdf32cb66198e3e3c269bef95f24f99e3c
4
- data.tar.gz: 91c8452c20b65db1cb90f59b3158e70064890e58dfb2261545373f9489dea4c5
3
+ metadata.gz: 60127d37531f075fc9b21ffc6827798bbdfb30988e5ae340b9b482ea0ac16cc4
4
+ data.tar.gz: e11f5dc38d11626da357eb59e04d53936fc15fdbc94301ca84815c279aa26c80
5
5
  SHA512:
6
- metadata.gz: 8d37cc3ef9b1f522b9f0b08d691e422b587bb5dc5d9392d1464fe7ba851607df1578d2234c02cde82f067c30e921710b208a8de126a516220ddb4046811fe125
7
- data.tar.gz: feee1c413377caf9b55aec343f60c0b5090d2c354755c6868258f7aa4979a8be028c5da555c6432611982cb0bc33499e2a58439b0ece3ca170f3cdbad739a489
6
+ metadata.gz: 74899baafc7538944dde8665b130b0b9712db0fdf3e94fd0b9ce34eb2dbbd9dcab2719706a1f2cb995a456675e5bdd9a94ea3cf60d3a52e2cd5966de76031db6
7
+ data.tar.gz: 5a1134adfddc2842aeb51f2f82200d4c21c0128f775c19f4c6ee7082106235e902e4f2b43a251f089addb71c61cc792b5364415b87d42404c1ea35de8a7586bc
@@ -0,0 +1,24 @@
1
+ name: Linting
2
+
3
+ permissions: {}
4
+
5
+ on:
6
+ pull_request:
7
+ push:
8
+ branches:
9
+ - main
10
+ jobs:
11
+ lint:
12
+ name: Run Standard.rb
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - name: Checkout code
16
+ uses: actions/checkout@v4
17
+ with:
18
+ persist-credentials: false
19
+ - name: Set up Ruby
20
+ uses: ruby/setup-ruby@v1
21
+ with:
22
+ bundler-cache: true
23
+ - name: Run linting
24
+ run: bin/standardrb
@@ -1,5 +1,7 @@
1
1
  name: Publish to rubygems
2
2
 
3
+ permissions: {}
4
+
3
5
  on:
4
6
  push:
5
7
  tags:
@@ -10,6 +12,8 @@ jobs:
10
12
  runs-on: ubuntu-latest
11
13
  steps:
12
14
  - uses: actions/checkout@v4
15
+ with:
16
+ persist-credentials: false
13
17
  - name: Set up Ruby
14
18
  uses: ruby/setup-ruby@v1
15
19
  - name: Setup Rubygems
@@ -1,231 +1,169 @@
1
1
  name: Rails integration tests
2
2
 
3
+ permissions: {}
3
4
  on:
4
- pull_request:
5
- push:
6
- branches:
7
- - v2
5
+ pull_request_target:
6
+ types: [opened, synchronize] # zizmor: ignore[dangerous-triggers] - we have permission checks to ensure only owners can trigger this action
8
7
 
9
8
  jobs:
10
- build-rails-5:
11
- name: Build Rails 5
9
+ check-user-permission:
12
10
  runs-on: ubuntu-latest
11
+ name: Check user permission
13
12
  steps:
14
- -
15
- name: Checkout
16
- uses: actions/checkout@v4
17
- -
18
- name: Set up Docker Buildx
19
- uses: docker/setup-buildx-action@v3
20
- -
21
- name: Build and cache
22
- uses: docker/build-push-action@v5
13
+ - name: Get User Permission
14
+ id: checkAccess
15
+ uses: actions-cool/check-user-permission@v2
23
16
  with:
24
- context: .
25
- file: ./Dockerfile
26
- build-args: |
27
- RAILS_VERSION=5.2.8.1
28
- MAIL_NOTIFY_BRANCH=${{ github.ref }}
29
- push: false
30
- tags: mail-notify-integration-rails-5:latest
31
- outputs: type=docker, dest=/tmp/rails-5-image.tar
32
- cache-from: type=gha
33
- cache-to: type=gha,mode=min
34
- - name: Upload artifact
35
- uses: actions/upload-artifact@v4
36
- with:
37
- name: rails-5-image
38
- path: /tmp/rails-5-image.tar
39
-
40
- rails-5-previews:
41
- name: Rails 5 mailer previews
42
- runs-on: ubuntu-latest
43
- needs: build-rails-5
44
- steps:
45
- -
46
- name: Download image
47
- uses: actions/download-artifact@v4
48
- with:
49
- name: rails-5-image
50
- path: /tmp
51
- -
52
- name: Load image
53
- run: docker load --input /tmp/rails-5-image.tar
54
- -
55
- name: Run integration tests
17
+ require: write
18
+ username: ${{ github.triggering_actor }}
19
+ - name: Check User Permission
20
+ if: steps.checkAccess.outputs.require-result == 'false'
56
21
  env:
57
- NOTIFY_API_KEY: ${{ secrets.NOTIFY_API_KEY }}
22
+ trigger-actor: ${{ github.triggering_actor }}
23
+ actor-name: ${{ github.actor }}
24
+ permission: ${{ steps.checkAccess.outputs.user-permission }}
58
25
  run: |
59
- docker run --rm -e "NOTIFY_API_KEY=$NOTIFY_API_KEY" \
60
- mail-notify-integration-rails-5:latest bin/rails test:system
61
-
62
-
63
- rails-5-sending:
64
- name: Rails 5 sending
26
+ echo "${ trigger-actor } does not have permissions on this repo."
27
+ echo "Current permission level is ${ permission }"
28
+ echo "Job originally triggered by ${ actor-name }"
29
+ exit 1
30
+ set-matrix:
65
31
  runs-on: ubuntu-latest
66
- needs: build-rails-5
32
+ name: Set Rails versions
33
+ needs:
34
+ - check-user-permission
35
+ outputs:
36
+ RAILS_VERSIONS: ${{ steps.compute-outputs.outputs.RAILS_VERSIONS }}
67
37
  steps:
68
- -
69
- name: Download image
70
- uses: actions/download-artifact@v4
71
- with:
72
- name: rails-5-image
73
- path: /tmp
74
- -
75
- name: Load image
76
- run: docker load --input /tmp/rails-5-image.tar
77
- -
78
- name: Run integration tests
79
- env:
80
- NOTIFY_API_KEY: ${{ secrets.NOTIFY_API_KEY }}
38
+ # Get latest Rails versions for 6.x.x and 7.x.x
39
+ - id: compute-outputs
40
+ name: Compute outputs
41
+ # fetches current Rails versions numbers > 6 and not 'beta'
81
42
  run: |
82
- docker run --rm -e "NOTIFY_API_KEY=$NOTIFY_API_KEY" \
83
- mail-notify-integration-rails-5:latest bin/rails test
84
-
85
- build-rails-6:
86
- name: Build Rails 6
43
+ rails_versions=$(curl https://rubygems.org/api/v1/versions/rails.json | jq '[.[] | select(.number | test("beta") | not)] | group_by(.number[:1])[] | (.[0].number) | select(.[:1]|tonumber > 6)' | jq -s -c)
44
+ echo "RAILS_VERSIONS=$rails_versions" >> $GITHUB_OUTPUT
45
+ set-ruby-version:
87
46
  runs-on: ubuntu-latest
47
+ name: Set Ruby version
48
+ needs:
49
+ - check-user-permission
50
+ outputs:
51
+ RUBY_VERSION: ${{ steps.set-ruby-version.outputs.RUBY_VERSION }}
88
52
  steps:
89
- -
90
- name: Checkout
53
+ - name: Checkout
91
54
  uses: actions/checkout@v4
92
- -
93
- name: Set up Docker Buildx
94
- uses: docker/setup-buildx-action@v3
95
- -
96
- name: Build and cache
97
- uses: docker/build-push-action@v5
98
55
  with:
99
- context: .
100
- file: ./Dockerfile
101
- build-args: |
102
- RAILS_VERSION=6.1.7.6
103
- MAIL_NOTIFY_BRANCH=${{ github.ref }}
104
- push: false
105
- tags: mail-notify-integration-rails-6:latest
106
- outputs: type=docker, dest=/tmp/rails-6-image.tar
107
- cache-from: type=gha
108
- cache-to: type=gha,mode=min
109
- - name: Upload artifact
110
- uses: actions/upload-artifact@v4
111
- with:
112
- name: rails-6-image
113
- path: /tmp/rails-6-image.tar
114
-
115
- rails-6-previews:
116
- name: Rails 6 mailer previews
117
- runs-on: ubuntu-latest
118
- needs: build-rails-6
119
- steps:
120
- -
121
- name: Download image
122
- uses: actions/download-artifact@v4
123
- with:
124
- name: rails-6-image
125
- path: /tmp
126
- -
127
- name: Load image
128
- run: docker load --input /tmp/rails-6-image.tar
129
- -
130
- name: Run integration tests
131
- env:
132
- NOTIFY_API_KEY: ${{ secrets.NOTIFY_API_KEY }}
56
+ persist-credentials: false
57
+ - id: set-ruby-version
58
+ name: Set Ruby version
133
59
  run: |
134
- docker run --rm -e "NOTIFY_API_KEY=$NOTIFY_API_KEY" \
135
- mail-notify-integration-rails-6:latest bin/rails test:system
136
-
137
- rails-6-sending:
138
- name: Rails 6 sending
60
+ echo "RUBY_VERSION=$(cat .ruby-version)" >> $GITHUB_OUTPUT
61
+ build-rails:
62
+ strategy:
63
+ fail-fast: false
64
+ matrix:
65
+ # Build containers with the latest 6.x.x and 7.x.x Rails versions
66
+ rails: ${{ fromJSON(needs.set-matrix.outputs.RAILS_VERSIONS) }}
139
67
  runs-on: ubuntu-latest
140
- needs: build-rails-6
68
+ name: Build and cache Docker containers
69
+ needs:
70
+ - set-matrix
71
+ - set-ruby-version
141
72
  steps:
142
- -
143
- name: Download image
144
- uses: actions/download-artifact@v4
145
- with:
146
- name: rails-6-image
147
- path: /tmp
148
- -
149
- name: Load image
150
- run: docker load --input /tmp/rails-6-image.tar
151
- -
152
- name: Run integration tests
153
- env:
154
- NOTIFY_API_KEY: ${{ secrets.NOTIFY_API_KEY }}
155
- run: |
156
- docker run --rm -e "NOTIFY_API_KEY=$NOTIFY_API_KEY" \
157
- mail-notify-integration-rails-6:latest bin/rails test
158
-
159
- build-rails-7:
160
- name: Build Rails 7
161
- runs-on: ubuntu-latest
162
- steps:
163
- -
164
- name: Checkout
73
+ - name: Checkout
165
74
  uses: actions/checkout@v4
166
- -
167
- name: Set up Docker Buildx
75
+ with:
76
+ persist-credentials: false
77
+ - name: Set up Docker Buildx
168
78
  uses: docker/setup-buildx-action@v3
169
- -
170
- name: Build and cache
171
- uses: docker/build-push-action@v5
79
+ - name: Build and cache
80
+ uses: docker/build-push-action@v6
172
81
  with:
173
82
  context: .
174
83
  file: ./Dockerfile
175
84
  build-args: |
176
- RAILS_VERSION=7.1.3.2
177
- MAIL_NOTIFY_BRANCH=${{ github.ref }}
85
+ RAILS_VERSION=${{ matrix.rails }}
86
+ RUBY_VERSION=${{ needs.set-ruby-version.outputs.RUBY_VERSION }}
178
87
  push: false
179
- tags: mail-notify-integration-rails-7:latest
180
- outputs: type=docker, dest=/tmp/rails-7-image.tar
181
- cache-from: type=gha
182
- cache-to: type=gha,mode=min
88
+ tags: mail-notify-integration-rails-${{ matrix.rails }}-${{ needs.set-ruby-version.outputs.RUBY_VERSION }}:latest
89
+ outputs: type=docker, dest=/tmp/rails-${{ matrix.rails }}-${{ needs.set-ruby-version.outputs.RUBY_VERSION }}-image.tar
90
+ cache-from: type=gha,scope=build-${{ matrix.rails }}-${{ needs.set-ruby-version.outputs.RUBY_VERSION }}
91
+ cache-to: type=gha,mode=min,scope=build-${{ matrix.rails }}-${{ needs.set-ruby-version.outputs.RUBY_VERSION }}
183
92
  - name: Upload artifact
184
93
  uses: actions/upload-artifact@v4
185
94
  with:
186
- name: rails-7-image
187
- path: /tmp/rails-7-image.tar
188
-
189
- rails-7-previews:
190
- name: Rails 7 mailer previews
95
+ name: rails-${{ matrix.rails }}-${{ needs.set-ruby-version.outputs.RUBY_VERSION }}-image
96
+ path: /tmp/rails-${{ matrix.rails }}-${{ needs.set-ruby-version.outputs.RUBY_VERSION }}-image.tar
97
+ mailer-previews:
98
+ strategy:
99
+ fail-fast: false
100
+ # Run against the latest 6.x.x and 7.x.x Rails versions
101
+ matrix:
102
+ rails: ${{ fromJSON(needs.set-matrix.outputs.RAILS_VERSIONS) }}
103
+ env:
104
+ MATRIX_RAILS: ${{ matrix.rails }}
105
+ RUBY_VERSION: ${{ needs.set-ruby-version.outputs.RUBY_VERSION }}
191
106
  runs-on: ubuntu-latest
192
- needs: build-rails-7
107
+ needs:
108
+ - set-matrix
109
+ - set-ruby-version
110
+ - build-rails
193
111
  steps:
194
- -
195
- name: Download image
112
+ - name: Download image
196
113
  uses: actions/download-artifact@v4
197
114
  with:
198
- name: rails-7-image
115
+ name: rails-${{ env.MATRIX_RAILS }}-${{ env.RUBY_VERSION }}-image
199
116
  path: /tmp
200
- -
201
- name: Load image
202
- run: docker load --input /tmp/rails-7-image.tar
203
- -
204
- name: Run integration tests
117
+ - name: Load image
118
+ run: docker load --input /tmp/rails-${MATRIX_RAILS}-${RUBY_VERSION}-image.tar
119
+ - name: Run integration tests
205
120
  env:
206
121
  NOTIFY_API_KEY: ${{ secrets.NOTIFY_API_KEY }}
207
122
  run: |
208
123
  docker run --rm -e "NOTIFY_API_KEY=$NOTIFY_API_KEY" \
209
- mail-notify-integration-rails-7:latest bin/rails test:system
210
-
211
- rails-7-sending:
212
- name: Rails 7 sending
124
+ mail-notify-integration-rails-${MATRIX_RAILS}-${RUBY_VERSION}:latest bin/rails test:system
125
+ sending:
126
+ strategy:
127
+ fail-fast: false
128
+ # Run against the latest 5.x.x, 6.x.x and 7.x.x Rails versions
129
+ matrix:
130
+ rails: ${{ fromJSON(needs.set-matrix.outputs.RAILS_VERSIONS) }}
131
+ env:
132
+ MATRIX_RAILS: ${{ matrix.rails }}
133
+ RUBY_VERSION: ${{ needs.set-ruby-version.outputs.RUBY_VERSION }}
213
134
  runs-on: ubuntu-latest
214
- needs: build-rails-7
135
+ needs:
136
+ - set-matrix
137
+ - set-ruby-version
138
+ - build-rails
215
139
  steps:
216
- -
217
- name: Download image
140
+ - name: Download image
218
141
  uses: actions/download-artifact@v4
219
142
  with:
220
- name: rails-7-image
143
+ name: rails-${{ env.MATRIX_RAILS }}-${{ env.RUBY_VERSION }}-image
221
144
  path: /tmp
222
- -
223
- name: Load image
224
- run: docker load --input /tmp/rails-7-image.tar
225
- -
226
- name: Run integration tests
145
+ - name: Load image
146
+ run: docker load --input /tmp/rails-${MATRIX_RAILS}-${RUBY_VERSION}-image.tar
147
+ - name: Run integration tests
227
148
  env:
228
149
  NOTIFY_API_KEY: ${{ secrets.NOTIFY_API_KEY }}
229
150
  run: |
230
151
  docker run --rm -e "NOTIFY_API_KEY=$NOTIFY_API_KEY" \
231
- mail-notify-integration-rails-7:latest bin/rails test
152
+ mail-notify-integration-rails-${MATRIX_RAILS}-${RUBY_VERSION}:latest bin/rails test
153
+ results:
154
+ if: ${{ always() }}
155
+ runs-on: ubuntu-latest
156
+ name: All integration tests
157
+ needs:
158
+ - mailer-previews
159
+ - sending
160
+ steps:
161
+ # If any of the previous actions failed, we return a non-zero exit code
162
+ - run: exit 1
163
+ if: >-
164
+ ${{
165
+ contains(needs.*.result, 'failure')
166
+ || contains(needs.*.result, 'cancelled')
167
+ || contains(needs.*.result, 'skipped')
168
+ }}
169
+ - run: echo "integration tests passed"
@@ -0,0 +1,43 @@
1
+ name: Unit tests
2
+ permissions: {}
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches:
7
+ - main
8
+ jobs:
9
+ unit-tests:
10
+ strategy:
11
+ fail-fast: false
12
+ matrix:
13
+ ruby: [ 3.1, 3.2, 3.3 ]
14
+ runs-on: ubuntu-latest
15
+ name: Run specs and coverage report
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ with:
19
+ persist-credentials: false
20
+ - uses: ruby/setup-ruby@v1
21
+ with:
22
+ ruby-version: ${{ matrix.ruby }}
23
+ bundler-cache: true
24
+ - name: Run specs
25
+ run: bin/rspec
26
+ - name: Run coverage report
27
+ uses: coverallsapp/github-action@v2
28
+ with:
29
+ fail-on-error: false
30
+ results:
31
+ if: ${{ always() }}
32
+ runs-on: ubuntu-latest
33
+ name: All unit tests
34
+ needs: [ unit-tests ]
35
+ steps:
36
+ # If any of the previous actions failed, we return a non-zero exit code
37
+ - run: exit 1
38
+ if: >-
39
+ ${{
40
+ contains(needs.*.result, 'failure')
41
+ || contains(needs.*.result, 'cancelled')
42
+ || contains(needs.*.result, 'skipped')
43
+ }}
data/.ruby-version CHANGED
@@ -1 +1 @@
1
- 2.7.8
1
+ 3.4.2
data/CHANGELOG.md CHANGED
@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog]
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [2.1.0] - 2025-03-24
10
+
11
+ - Support one click unsubscribe - thanks to @asmega ([#168](https://github.com/dxw/mail-notify/pull/168))
12
+ - Fixed a bug in `view_mail` and `template_mail` that meant the options were being
13
+ included in the preview email headers for no reason - thanks to @inulty-dfe ([#165](https://github.com/dxw/mail-notify/pull/165))
14
+ - Fixed a bug in `view_mail` that meant custom headers in the preview email were
15
+ duplicated - thanks to @inulty-dfe ([#165](https://github.com/dxw/mail-notify/pull/165))
16
+
9
17
  ## [2.0.0] - 2024-04-01
10
18
 
11
19
  - Version 2.0.0 rewrites most of the gem, without altering the API
data/Dockerfile CHANGED
@@ -1,22 +1,18 @@
1
- # We want to support older Rubies
2
- ARG RUBY_VERSION=2.7.8
3
- FROM registry.docker.com/library/ruby:$RUBY_VERSION-slim as base
1
+ ARG RUBY_VERSION=3.1.6
2
+ FROM registry.docker.com/library/ruby:$RUBY_VERSION-slim AS base
4
3
 
5
4
  # Rails app lives here
6
5
  WORKDIR /rails
7
6
 
8
7
  # Build stage
9
- FROM base as build
8
+ FROM base AS build
10
9
 
11
10
  # Install packages needed to build gems and node modules
12
11
  RUN apt-get update -qq && \
13
- apt-get install --no-install-recommends -y build-essential curl git
14
-
15
- # Install Nokigiri version that supports Ruby 2.7.8
16
- RUN gem install nokogiri -v 1.15.6
12
+ apt-get install --no-install-recommends -y build-essential curl git libyaml-dev
17
13
 
18
14
  # Install Rails
19
- ARG RAILS_VERSION=7.1.3.2
15
+ ARG RAILS_VERSION=7.2.1
20
16
  RUN gem install rails -v ${RAILS_VERSION}
21
17
 
22
18
  # create empty Rails application, we don't need ActiveRecord or JavaScript
@@ -27,9 +23,6 @@ WORKDIR mail-notify-integration
27
23
  # install the gems into the bundle
28
24
  RUN bundle install
29
25
 
30
- # remove gems that will not work in Rails 5.2.8.1
31
- RUN if [ "${RAILS_VERSION}" = "5.2.8.1" ]; then bundle remove selenium-webdriver chromedriver-helper; fi
32
-
33
26
  # Final stage for app image
34
27
  FROM base
35
28
 
@@ -45,8 +38,8 @@ COPY --from=build /rails /rails
45
38
  WORKDIR /rails/mail-notify-integration
46
39
 
47
40
  # add Mail Notify to the Gemfile
48
- ARG MAIL_NOTIFY_BRANCH=v2
49
- RUN echo "gem 'mail-notify', git: 'https://github.com/dxw/mail-notify', branch: '${MAIL_NOTIFY_BRANCH}'" >> Gemfile
41
+ COPY . ../mail-notify
42
+ RUN echo "gem 'mail-notify', path: '../mail-notify'" >> Gemfile
50
43
 
51
44
  # install the mail-notify gem, we do this here to keep the last container layer small to help caching
52
45
  RUN bundle install
data/README.md CHANGED
@@ -1,11 +1,14 @@
1
- [![Build status](https://github.com/dxw/mail-notify/actions/workflows/ci.yml/badge.svg)](https://github.com/dxw/mail-notify/actions/workflows/ci.yml)
1
+ [![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)
2
2
  [![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)
3
3
  [![Gem Version](http://img.shields.io/gem/v/mail-notify.svg?style=flat-square)](https://rubygems.org/gems/mail-notify)
4
+ [![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)
4
5
  [![License](http://img.shields.io/:license-mit-blue.svg)](https://mit-license.org/)
5
6
 
6
- # Mail::Notify
7
+ # mail-notify
7
8
 
8
- Rails / ActionMailer support for the [GOV.UK Notify API](https://www.notifications.service.gov.uk).
9
+ Rails plugin for [GOV.UK Notify](https://www.notifications.service.gov.uk).
10
+
11
+ [Great products and services like yours use mail-notify!](https://github.com/dxw/mail-notify/wiki#some-services-and-products-that-use-mail-notify)
9
12
 
10
13
  ## Installation
11
14
 
@@ -19,11 +22,10 @@ And then execute:
19
22
 
20
23
  $ bundle
21
24
 
22
- Or install it yourself as:
23
-
24
- $ gem install mail-notify
25
+ ## Configuration
25
26
 
26
- Then, add the following to your `config/environments/*.rb` (where * is `test`, `development`, `production` or whatever other environment(s) you have) file(s):
27
+ Configure in each environment `config/environments/*.rb` (where * is `test`,
28
+ `development`, `production` or whatever other environment(s) you have) file(s):
27
29
 
28
30
  ```ruby
29
31
  config.action_mailer.delivery_method = :notify
@@ -32,7 +34,13 @@ config.action_mailer.notify_settings = {
32
34
  }
33
35
  ```
34
36
 
35
- 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:
37
+ We recommend using separate Notify 'test' API keys (email will not be sent but
38
+ can be seen in Notify) in all environments except production so you can confirm
39
+ the integration and generate previews without actually sending any email.
40
+
41
+ If you're using a different Notify service to GOV.UK Notify (for example [GOV.CA
42
+ Notify](https://notification.alpha.canada.ca/)), you can also specify the Base
43
+ URL in your setup:
36
44
 
37
45
  ```ruby
38
46
  config.action_mailer.delivery_method = :notify
@@ -44,131 +52,228 @@ config.action_mailer.notify_settings = {
44
52
 
45
53
  ### Mailers
46
54
 
47
- 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:
55
+ There are two options for using mail-notify, manage the content in Notify
56
+ with [template mailers](#template-mailers) or in Rails with [view
57
+ mailers](#view-mailers) you can mix the two approaches as you need.
58
+
59
+ Whichever you choose, you'll need your mailers to inherit from `Mail::Notify::Mailer` like so:
48
60
 
49
61
  ```ruby
50
- class MyMailer < Mail::Notify::Mailer
62
+ class MyCustomMailer < Mail::Notify::Mailer
51
63
  end
52
64
  ```
53
65
 
54
- #### With a view
66
+ We recommend going 'all in' with Notify and having `ApplicationMailer` inherit
67
+ for mail-notify:
68
+
69
+ ```ruby
70
+ class ApplicationMailer < Mail::Notify::Mailer
71
+ end
72
+ ```
55
73
 
56
- 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.
74
+ then have each mailer inherit from `ApplicationMailer`:
57
75
 
58
- 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:
76
+ ```ruby
77
+ class MyCustomMailer < ApplicationMailer
78
+ end
79
+ ```
59
80
 
60
- ![Example screenshot](docs/screenshot.png)
81
+ #### Template mailers
61
82
 
62
- 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:
83
+ Template mailers only require the template ID from Notify and an to email
84
+ address, all of the content for the email is managed in Notify:
63
85
 
64
86
  ```ruby
65
- class MyMailer < Mail::Notify::Mailer
66
- def send_email
67
- view_mail('YOUR_TEMPLATE_ID_GOES_HERE',
68
- to: 'mail@somewhere.com',
69
- subject: 'Subject line goes here'
70
- )
87
+ class MyCustomMailer < ApplicationMailer
88
+ def welcome_email
89
+ to = params[:to]
90
+
91
+ template_mail("NOTIFY_TEMPLATE_ID", to: to)
71
92
  end
72
93
  end
73
- ```
74
-
75
- 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.
76
94
 
77
- #### With Notify templating
95
+ # call the template mailer
96
+ MyCustomMailer.with(to: "first.last@example.com").welcome_email.deliver_now!
97
+ ```
78
98
 
79
- 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:
99
+ You can add any number of
100
+ [personalisations](https://www.notifications.service.gov.uk/using-notify/personalisation) to template mailers:
80
101
 
81
102
  ```ruby
82
- class MyMailer < Mail::Notify::Mailer
83
- def send_email
84
- template_mail('YOUR_TEMPLATE_ID_GOES_HERE',
85
- to: 'mail@somewhere.com',
86
- personalisation: {
87
- foo: 'bar'
88
- }
103
+ class MyCustomMailer < ApplicationMailer
104
+ def appointment_email
105
+ to = params[:to]
106
+ name = params[:name]
107
+ appointment_date = params[:appointment_date]
108
+
109
+ template_mail(
110
+ "NOTIFY_TEMPLATE_ID",
111
+ to: to,
112
+ personalisation: {
113
+ name: name,
114
+ appointment_date: date.to_s
115
+ }
89
116
  )
90
117
  end
91
118
  end
119
+
120
+ # call the template mailer with personalisation options
121
+ MyCustomMailer.with(
122
+ to: "first.last@example.com",
123
+ name: "First Last",
124
+ appointment_date: Date.new(2024, 01, 01)
125
+ ).appointment_email.deliver_now!
92
126
  ```
93
127
 
94
- 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:
128
+ A note on blank personalisation; The Notify API will not allow `nil`
129
+ personalisation, if you expect `nil` values, you can wrap them in
130
+ `blank_allowed` which converts them to an empty string:
95
131
 
96
132
  ```ruby
97
- class MyMailer < Mail::Notify::Mailer
98
- def send_email
99
- template_mail('YOUR_TEMPLATE_ID_GOES_HERE',
100
- to: 'mail@somewhere.com',
101
- personalisation: {
102
- foo: foo.name, # This will trigger template validation error when blank
103
- bar: blank_allowed(bar.name) # This will inject empty string in the template when blank
104
- }
105
- )
106
- end
107
- end
133
+ MyCustomMailer.with(
134
+ to: "first.last@example.com", name: blank_allowed(user.name)).welcome_email.deliver_now!
108
135
  ```
109
136
 
137
+ Or use params as the examples above.
110
138
 
111
- #### With optional Notify arguments
139
+ #### View mailers
140
+
141
+ View mailers let you manage the content of emails with a Rails text view, with
142
+ Notify's markdown like
143
+ [formatting](https://www.notifications.service.gov.uk/using-notify/formatting)
144
+ supported.
112
145
 
113
- It's possible to pass two optional arguments to Notify:
146
+ You will still require a template in Notify, the template must be setup with
147
+ `subject` and `body` personalisations, which will be replaced with those from
148
+ your mailer and view:
114
149
 
115
- - `reply_to_id`: This is an email reply-to address specified by you to receive replies from your users
116
- - `reference`: A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications
150
+ ![Screenshot of a view mailer template in Notify](docs/assets/images/view_template_in_notify.png)
117
151
 
118
- More information can be [found in the docs](https://docs.notifications.service.gov.uk/ruby.html#send-an-email-arguments-personalisation-optional)
152
+ Your view mailer is then setup like this:
119
153
 
120
154
  ```ruby
121
- class MyMailer < Mail::Notify::Mailer
122
- def send_email
123
- view_mail('YOUR_TEMPLATE_ID_GOES_HERE',
124
- to: 'mail@somewhere.com',
125
- subject: 'Subject line goes here',
126
- reply_to_id: 'YOUR_REPLY_TO_ID_GOES_HERE',
127
- reference: 'ABC123XYZ'
128
- )
155
+ class MyCustomMailer < ApplicationMailer
156
+ def welcome_email
157
+ to = params[:to]
158
+ subject= params[:subject]
159
+
160
+ view_mail("NOTIFY_TEMPLATE_ID", to: to, subject: subject)
129
161
  end
130
- end
131
162
  ```
132
163
 
133
- #### With Devise
164
+ With a `subject` being required.
134
165
 
135
- 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.
166
+ Add the view named appropriately and in the conventional location:
136
167
 
137
- In `config/initializers/devise.rb`:
168
+ `app/views/my_custom_mailer/welcome_email.text.erb`
169
+
170
+ Add content to the view:
171
+
172
+ ```
173
+ Dear <%= @user.name %>
174
+
175
+ # Welcome to the service.
176
+
177
+ Here are some points to note:
178
+
179
+ * point one
180
+ * point two
181
+ * point three
182
+
183
+ ^ Don't forget this.
184
+
185
+ ```
186
+
187
+ Then call the mailer as usual:
138
188
 
139
189
  ```ruby
140
- config.mailer = 'DeviseMailer'
190
+ MyCustomMailer.with(
191
+ to: "first.last@example.com",
192
+ subject: "Welcome to service"
193
+ ).welcome_email.deliver_now!
194
+
141
195
  ```
142
196
 
143
- in `app/mailers/devise_mailer.rb`:
197
+ Only plain text views can be used, with the Notify markdown like formatting
198
+ options. The email is sent as both HTML and plain text by Notify.
199
+
200
+ #### With optional Notify arguments
201
+
202
+ It's possible to pass two optional arguments to Notify with either template or
203
+ view mailers.
204
+
205
+ - `reply_to_id`: This is an email reply-to address specified by you to receive
206
+ replies from your users
207
+ - `reference`: A unique identifier you can create if necessary. This reference
208
+ identifies a single unique notification or a batch of notifications
209
+ - `one_click_unsubscribe_url`: The URL email client will POST to in order to
210
+ unsubscribe from the mailing list
211
+
212
+ More information can be [found in the
213
+ Notify docs](https://docs.notifications.service.gov.uk/ruby.html#send-an-email-arguments-personalisation-optional)
144
214
 
145
215
  ```ruby
146
- class DeviseMailer < Devise::Mailer
147
- def devise_mail(record, action, opts = {}, &block)
148
- initialize_from_record(record)
149
- view_mail(ENV['NOTIFY_TEMPLATE_ID'], headers_for(action, opts))
150
- end
216
+ class MyCustomMailer < ApplicationMailer
217
+ def welcome_email
218
+ to = params[:to]
219
+ reference = params[:reference]
220
+ reply_to_id = params[:reply_to_id]
221
+
222
+ template_mail("NOTIFY_TEMPLATE_ID", to: to, reply_to_id: reply_to_id, reference: reference)
223
+ end
151
224
  end
225
+
226
+ # call the mailer
227
+ MyCustomMailer.with(
228
+ to: "first.last@example.com",
229
+ reference: "YOUR_REFERENCE",
230
+ reply_to_id: "YOUR_REPLY_TO"
231
+ ).welcome_email.deliver_now!
152
232
  ```
153
233
 
154
234
  ## Previews
155
235
 
156
- 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.
236
+ Rails [previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails)
237
+ are supported.
238
+
239
+ The Rails delivery method must be set to `:notify` and a Notify API key will be
240
+ required for previews to work as the [preview is
241
+ generated](https://docs.notifications.service.gov.uk/ruby.html#generate-a-preview-template)
242
+ by the Notify API.
243
+
244
+ ## With Devise
245
+
246
+ Mail-notify is compatible with anything that uses ActionMailer,
247
+ [Devise](https://github.com/heartcombo/devise) is a popular authentication gem
248
+ that uses ActionMailer to send emails relating to
249
+ accounts, see [instructions in the
250
+ wiki](https://github.com/dxw/mail-notify/wiki/Use-with-Devise) for more details
251
+ of using mail-notify with Devise.
157
252
 
158
253
  ## Development
159
254
 
160
- 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.
255
+ After checking out the repo, run `bin/setup` to install dependencies. Then, run
256
+ `bin/rspec` to run the tests. You can also run `bin/console` for an interactive
257
+ prompt that will allow you to experiment.
161
258
 
162
- 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).
259
+ To release a new version, update the version number in `version.rb`, and then
260
+ tag the commit on main - the release will be built and published by the
261
+ `publish.yml` GitHub action.
163
262
 
164
263
  ## Contributing
165
264
 
166
- 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.
265
+ Bug reports and pull requests are welcome on GitHub at
266
+ https://github.com/dxw/mail-notify. This project is intended to be a safe,
267
+ welcoming space for collaboration, and contributors are expected to adhere to
268
+ the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
167
269
 
168
270
  ## License
169
271
 
170
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
272
+ The gem is available as open source under the terms of the [MIT
273
+ License](https://opensource.org/licenses/MIT).
171
274
 
172
275
  ## Code of Conduct
173
276
 
174
- 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).
277
+ Everyone interacting in the Mail::Notify project’s codebases, issue trackers,
278
+ chat rooms and mailing lists is expected to follow the [code of
279
+ conduct](https://github.com/pezholio/mail-notify/blob/master/CODE_OF_CONDUCT.md).
@@ -17,7 +17,8 @@ module Mail
17
17
  email_address: message.to.first,
18
18
  personalisation: message.personalisation,
19
19
  email_reply_to_id: message.reply_to_id,
20
- reference: message.reference
20
+ reference: message.reference,
21
+ one_click_unsubscribe_url: message.one_click_unsubscribe_url
21
22
  }
22
23
 
23
24
  client.send_email(params.compact)
@@ -35,10 +35,11 @@ module Mail
35
35
  message.template_id = template_id
36
36
  message.reply_to_id = options[:reply_to_id]
37
37
  message.reference = options[:reference]
38
+ message.one_click_unsubscribe_url = options[:one_click_unsubscribe_url]
38
39
 
39
40
  message.personalisation = options[:personalisation] || {}
40
41
 
41
- headers = options.except([:personalisation, :reply_to_id, :reference])
42
+ headers = options.except(:personalisation, :reply_to_id, :reference)
42
43
 
43
44
  headers[:subject] = "Subject managed in Notify" unless options[:subject]
44
45
 
@@ -74,11 +75,14 @@ module Mail
74
75
  message.reference = options[:reference]
75
76
 
76
77
  subject = options[:subject]
77
- headers = options.except([:personalisation, :reply_to_id, :reference])
78
+ headers = options.except(:personalisation, :reply_to_id, :reference)
78
79
 
79
- # we have to render the view for the message and grab the raw source, then we set that as the
80
+ # We have to render the view for the message and grab the raw source, then we set that as the
80
81
  # body in the personalisation for sending to the Notify API.
81
- body = mail(headers).body.raw_source
82
+ #
83
+ # We do not pass the headers as the call to `mail` will keep adding headers resulting in
84
+ # duplication when we have to call it again later.
85
+ body = mail.body.raw_source
82
86
 
83
87
  # The 'view mail' works by sending a subject and body as personalisation options, these are
84
88
  # then used in the Notify template to provide content.
@@ -3,7 +3,7 @@
3
3
  module Mail
4
4
  module Notify
5
5
  module Message
6
- attr_accessor :template_id, :personalisation, :reply_to_id, :reference
6
+ attr_accessor :template_id, :personalisation, :reply_to_id, :reference, :one_click_unsubscribe_url
7
7
  end
8
8
  end
9
9
  end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Mail
4
4
  module Notify
5
- VERSION = "2.0.0"
5
+ VERSION = "2.1.0"
6
6
  end
7
7
  end
data/mail-notify.gemspec CHANGED
@@ -28,10 +28,10 @@ Gem::Specification.new do |spec|
28
28
  spec.add_development_dependency "bundler", "~> 2.0"
29
29
  spec.add_development_dependency "simplecov", "~> 0.21"
30
30
  spec.add_development_dependency "simplecov-lcov"
31
- spec.add_development_dependency "pry", "~> 0.14.1"
32
- spec.add_development_dependency "rails", "7.0.8"
31
+ spec.add_development_dependency "debug"
32
+ spec.add_development_dependency "rails", "7.2.2.1"
33
33
  spec.add_development_dependency "rake", "~> 13.2.1"
34
- spec.add_development_dependency "rspec-rails", "~> 5.1"
34
+ spec.add_development_dependency "rspec-rails", "~> 7.1"
35
35
  spec.add_development_dependency "standard", "~> 1"
36
36
  spec.add_development_dependency "sqlite3", "~> 1.7.2"
37
37
  spec.add_development_dependency "webmock", "~> 3.23.0"
metadata CHANGED
@@ -1,15 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: mail-notify
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.0
4
+ version: 2.1.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Stuart Harrison
8
8
  - Meyric Rawlings
9
- autorequire:
10
9
  bindir: exe
11
10
  cert_chain: []
12
- date: 2024-04-23 00:00:00.000000000 Z
11
+ date: 2025-03-24 00:00:00.000000000 Z
13
12
  dependencies:
14
13
  - !ruby/object:Gem::Dependency
15
14
  name: bundler
@@ -54,33 +53,33 @@ dependencies:
54
53
  - !ruby/object:Gem::Version
55
54
  version: '0'
56
55
  - !ruby/object:Gem::Dependency
57
- name: pry
56
+ name: debug
58
57
  requirement: !ruby/object:Gem::Requirement
59
58
  requirements:
60
- - - "~>"
59
+ - - ">="
61
60
  - !ruby/object:Gem::Version
62
- version: 0.14.1
61
+ version: '0'
63
62
  type: :development
64
63
  prerelease: false
65
64
  version_requirements: !ruby/object:Gem::Requirement
66
65
  requirements:
67
- - - "~>"
66
+ - - ">="
68
67
  - !ruby/object:Gem::Version
69
- version: 0.14.1
68
+ version: '0'
70
69
  - !ruby/object:Gem::Dependency
71
70
  name: rails
72
71
  requirement: !ruby/object:Gem::Requirement
73
72
  requirements:
74
73
  - - '='
75
74
  - !ruby/object:Gem::Version
76
- version: 7.0.8
75
+ version: 7.2.2.1
77
76
  type: :development
78
77
  prerelease: false
79
78
  version_requirements: !ruby/object:Gem::Requirement
80
79
  requirements:
81
80
  - - '='
82
81
  - !ruby/object:Gem::Version
83
- version: 7.0.8
82
+ version: 7.2.2.1
84
83
  - !ruby/object:Gem::Dependency
85
84
  name: rake
86
85
  requirement: !ruby/object:Gem::Requirement
@@ -101,14 +100,14 @@ dependencies:
101
100
  requirements:
102
101
  - - "~>"
103
102
  - !ruby/object:Gem::Version
104
- version: '5.1'
103
+ version: '7.1'
105
104
  type: :development
106
105
  prerelease: false
107
106
  version_requirements: !ruby/object:Gem::Requirement
108
107
  requirements:
109
108
  - - "~>"
110
109
  - !ruby/object:Gem::Version
111
- version: '5.1'
110
+ version: '7.1'
112
111
  - !ruby/object:Gem::Dependency
113
112
  name: standard
114
113
  requirement: !ruby/object:Gem::Requirement
@@ -249,21 +248,19 @@ dependencies:
249
248
  - - "~>"
250
249
  - !ruby/object:Gem::Version
251
250
  version: '6.0'
252
- description:
253
251
  email:
254
252
  - pezholio@gmail.com
255
253
  executables: []
256
254
  extensions: []
257
255
  extra_rdoc_files: []
258
256
  files:
259
- - ".github/dependabot.yml"
260
257
  - ".github/setup-rubygems.sh"
261
- - ".github/workflows/ci.yml"
258
+ - ".github/workflows/linting.yml"
262
259
  - ".github/workflows/publish.yml"
263
260
  - ".github/workflows/rails-integration-tests.yml"
261
+ - ".github/workflows/unit-tests.yml"
264
262
  - ".gitignore"
265
263
  - ".rspec"
266
- - ".rubocop.yml"
267
264
  - ".ruby-version"
268
265
  - CHANGELOG.md
269
266
  - CODE_OF_CONDUCT.md
@@ -278,7 +275,7 @@ files:
278
275
  - bin/rspec
279
276
  - bin/setup
280
277
  - bin/standardrb
281
- - docs/screenshot.png
278
+ - docs/assets/images/view_template_in_notify.png
282
279
  - lib/mail/notify.rb
283
280
  - lib/mail/notify/delivery_method.rb
284
281
  - lib/mail/notify/engine.rb
@@ -293,7 +290,6 @@ homepage: https://github.com/dxw/mail-notify
293
290
  licenses:
294
291
  - MIT
295
292
  metadata: {}
296
- post_install_message:
297
293
  rdoc_options: []
298
294
  require_paths:
299
295
  - lib
@@ -308,8 +304,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
308
304
  - !ruby/object:Gem::Version
309
305
  version: '0'
310
306
  requirements: []
311
- rubygems_version: 3.1.6
312
- signing_key:
307
+ rubygems_version: 3.6.2
313
308
  specification_version: 4
314
309
  summary: Rails plugin, send and preview email with GOV.UK Notify
315
310
  test_files: []
@@ -1,10 +0,0 @@
1
- version: 2
2
- updates:
3
- - package-ecosystem: "bundler"
4
- directory: "/"
5
- schedule:
6
- interval: "daily"
7
- - package-ecosystem: "github-actions"
8
- directory: "/"
9
- schedule:
10
- interval: "daily"
@@ -1,21 +0,0 @@
1
- name: CI
2
- on: [push, pull_request]
3
- jobs:
4
- lint-and-test:
5
- name: Linting, specs and coverage
6
- runs-on: ubuntu-latest
7
- steps:
8
- - name: Checkout code
9
- uses: actions/checkout@v4
10
- - name: Set up Ruby
11
- uses: ruby/setup-ruby@v1
12
- with:
13
- bundler-cache: true
14
- - name: Run linting
15
- run: bin/standardrb
16
- - name: Run specs
17
- run: bin/rspec
18
- - name: Run coverage report
19
- uses: coverallsapp/github-action@v2
20
- with:
21
- fail-on-error: false
data/.rubocop.yml DELETED
@@ -1,14 +0,0 @@
1
- Metrics/LineLength:
2
- Max: 91
3
- Exclude:
4
- - 'spec/dummy/**/*'
5
-
6
- Style/Documentation:
7
- Exclude:
8
- - 'spec/**/*'
9
- - 'test/**/*'
10
- - 'lib/**/*'
11
-
12
- Metrics/BlockLength:
13
- Exclude:
14
- - 'spec/**/*'
data/docs/screenshot.png DELETED
Binary file