notifications-ruby-client 5.3.0 → 6.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.dockerignore +1 -0
- data/CHANGELOG.md +11 -0
- data/CONTRIBUTING.md +26 -21
- data/DOCUMENTATION.md +398 -297
- data/Dockerfile +3 -0
- data/Makefile +11 -44
- data/README.md +2 -2
- data/lib/notifications/client/helper_methods.rb +8 -2
- data/lib/notifications/client/version.rb +1 -1
- data/notifications-ruby-client.gemspec +1 -1
- data/scripts/run_with_docker.sh +22 -0
- metadata +11 -4
- data/bin/generate_docker_env.sh +0 -29
data/DOCUMENTATION.md
CHANGED
@@ -2,9 +2,9 @@
|
|
2
2
|
|
3
3
|
This documentation is for developers interested in using the GOV.UK Notify Ruby client to send emails, text messages or letters.
|
4
4
|
|
5
|
-
|
5
|
+
## Set up the client
|
6
6
|
|
7
|
-
|
7
|
+
### Install the client
|
8
8
|
|
9
9
|
Run the following in the command line:
|
10
10
|
|
@@ -12,9 +12,9 @@ Run the following in the command line:
|
|
12
12
|
gem install 'notifications-ruby-client'
|
13
13
|
```
|
14
14
|
|
15
|
-
Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/
|
15
|
+
Refer to the [client changelog](https://github.com/alphagov/notifications-ruby-client/blob/main/CHANGELOG.md) for the version number and the latest updates.
|
16
16
|
|
17
|
-
|
17
|
+
### Create a new instance of the client
|
18
18
|
|
19
19
|
Add this code to your application:
|
20
20
|
|
@@ -25,13 +25,13 @@ client = Notifications::Client.new(api_key)
|
|
25
25
|
|
26
26
|
To get an API key, [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __API integration__ page. You can find more information in the [API keys](#api-keys) section of this documentation.
|
27
27
|
|
28
|
-
|
28
|
+
## Send a message
|
29
29
|
|
30
30
|
You can use GOV.UK Notify to send text messages, emails or letters.
|
31
31
|
|
32
|
-
|
32
|
+
### Send a text message
|
33
33
|
|
34
|
-
|
34
|
+
#### Method
|
35
35
|
|
36
36
|
```ruby
|
37
37
|
smsresponse = client.send_sms(
|
@@ -40,9 +40,9 @@ smsresponse = client.send_sms(
|
|
40
40
|
)
|
41
41
|
```
|
42
42
|
|
43
|
-
|
43
|
+
#### Arguments
|
44
44
|
|
45
|
-
|
45
|
+
##### phone_number (required)
|
46
46
|
|
47
47
|
The phone number of the text message recipient. This can be a UK or international number. For example:
|
48
48
|
|
@@ -50,7 +50,7 @@ The phone number of the text message recipient. This can be a UK or internationa
|
|
50
50
|
phone_number:"+447900900123"
|
51
51
|
```
|
52
52
|
|
53
|
-
|
53
|
+
##### template_id (required)
|
54
54
|
|
55
55
|
To find the template ID:
|
56
56
|
|
@@ -64,7 +64,7 @@ For example:
|
|
64
64
|
template_id:"f33517ff-2a88-4f6e-b855-c550268ce08a"
|
65
65
|
```
|
66
66
|
|
67
|
-
|
67
|
+
##### personalisation (optional)
|
68
68
|
|
69
69
|
If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a hash. For example:
|
70
70
|
|
@@ -77,7 +77,7 @@ personalisation: {
|
|
77
77
|
|
78
78
|
You can leave out this argument if a template does not have any placeholder fields for personalised information.
|
79
79
|
|
80
|
-
|
80
|
+
##### reference (optional)
|
81
81
|
|
82
82
|
A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:
|
83
83
|
|
@@ -87,7 +87,7 @@ reference: "your_reference_string"
|
|
87
87
|
|
88
88
|
You can leave out this argument if you do not have a reference.
|
89
89
|
|
90
|
-
|
90
|
+
##### sms_sender_id (optional)
|
91
91
|
|
92
92
|
A unique identifier of the sender of the text message notification.
|
93
93
|
|
@@ -111,7 +111,7 @@ sms_sender_id: "8e222534-7f05-4972-86e3-17c5d9f894e2"
|
|
111
111
|
|
112
112
|
You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.
|
113
113
|
|
114
|
-
|
114
|
+
#### Response
|
115
115
|
|
116
116
|
If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](#method), the object is named `smsresponse`.
|
117
117
|
|
@@ -119,17 +119,17 @@ You can then call different methods on this object:
|
|
119
119
|
|
120
120
|
|Method|Information|Type|
|
121
121
|
|:---|:---|:---|
|
122
|
-
|
123
|
-
|
124
|
-
|
125
|
-
|
126
|
-
|
122
|
+
|#`smsresponse.id`|Notification UUID|String|
|
123
|
+
|#`smsresponse.reference`|`reference` argument|String|
|
124
|
+
|#`smsresponse.content`|- `body`: Message body sent to the recipient<br>- `from_number`: SMS sender number of your service|Hash|
|
125
|
+
|#`smsresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
|
126
|
+
|#`smsresponse.uri`|Notification URL|String|
|
127
127
|
|
128
128
|
If you are using the [test API key](#test), all your messages come back with a `delivered` status.
|
129
129
|
|
130
130
|
All messages sent using the [team and guest list](#team-and-guest-list) or [live](#live) keys appear on your GOV.UK Notify dashboard.
|
131
131
|
|
132
|
-
|
132
|
+
#### Error codes
|
133
133
|
|
134
134
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
135
135
|
|
@@ -143,9 +143,9 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
143
143
|
|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`ClientError`|Refer to [service limits](#daily-limits) for the limit number|
|
144
144
|
|`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
|
145
145
|
|
146
|
-
|
146
|
+
### Send an email
|
147
147
|
|
148
|
-
|
148
|
+
#### Method
|
149
149
|
|
150
150
|
```ruby
|
151
151
|
emailresponse = client.send_email(
|
@@ -154,9 +154,9 @@ emailresponse = client.send_email(
|
|
154
154
|
)
|
155
155
|
```
|
156
156
|
|
157
|
-
|
157
|
+
#### Arguments
|
158
158
|
|
159
|
-
|
159
|
+
##### email_address (required)
|
160
160
|
|
161
161
|
The email address of the recipient. For example:
|
162
162
|
|
@@ -164,7 +164,7 @@ The email address of the recipient. For example:
|
|
164
164
|
email_address: "sender@something.com"
|
165
165
|
```
|
166
166
|
|
167
|
-
|
167
|
+
##### template_id (required)
|
168
168
|
|
169
169
|
To find the template ID:
|
170
170
|
|
@@ -178,20 +178,22 @@ For example:
|
|
178
178
|
template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a"
|
179
179
|
```
|
180
180
|
|
181
|
-
|
181
|
+
##### personalisation (optional)
|
182
182
|
|
183
183
|
If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a hash. For example:
|
184
184
|
|
185
185
|
```ruby
|
186
186
|
personalisation: {
|
187
187
|
name: "John Smith",
|
188
|
-
year: "2016"
|
188
|
+
year: "2016",
|
189
|
+
# pass in an array and it will appear as bullet points in the message:
|
190
|
+
required_documents: ["passport", "utility bill", "other id"],
|
189
191
|
}
|
190
192
|
```
|
191
193
|
|
192
194
|
You can leave out this argument if a template does not have any placeholder fields for personalised information.
|
193
195
|
|
194
|
-
|
196
|
+
##### reference (optional)
|
195
197
|
|
196
198
|
A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:
|
197
199
|
|
@@ -201,7 +203,7 @@ reference: "your_reference_string"
|
|
201
203
|
|
202
204
|
You can leave out this argument if you do not have a reference.
|
203
205
|
|
204
|
-
|
206
|
+
##### email_reply_to_id (optional)
|
205
207
|
|
206
208
|
This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.
|
207
209
|
|
@@ -221,31 +223,38 @@ email_reply_to_id: '8e222534-7f05-4972-86e3-17c5d9f894e2'
|
|
221
223
|
|
222
224
|
You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.
|
223
225
|
|
224
|
-
|
226
|
+
### Send a file by email
|
225
227
|
|
226
228
|
To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.
|
227
229
|
|
228
230
|
The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.
|
229
231
|
|
230
|
-
|
232
|
+
Your file will be available to download for a default period of 26 weeks (6 months).
|
233
|
+
|
234
|
+
To help protect your files you can also:
|
235
|
+
|
236
|
+
* ask recipients to confirm their email address before downloading
|
237
|
+
* choose the length of time that a file is available to download
|
238
|
+
|
239
|
+
#### Add contact details to the file download page
|
231
240
|
|
232
241
|
1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in).
|
233
242
|
1. Go to the __Settings__ page.
|
234
243
|
1. In the __Email__ section, select __Manage__ on the __Send files by email__ row.
|
235
244
|
1. Enter the contact details you want to use, and select __Save__.
|
236
245
|
|
237
|
-
|
246
|
+
#### Add a placeholder to the template
|
238
247
|
|
239
248
|
1. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in).
|
240
249
|
1. Go to the __Templates__ page and select the relevant email template.
|
241
250
|
1. Select __Edit__.
|
242
|
-
1. Add a placeholder to the email template using double brackets. For example:
|
251
|
+
1. Add a placeholder to the email template using double brackets. For example: "Download your file at: ((link_to_file))"
|
243
252
|
|
244
|
-
|
253
|
+
Your email should also tell recipients how long the file will be available to download.
|
245
254
|
|
246
|
-
|
255
|
+
#### Upload your file
|
247
256
|
|
248
|
-
You can upload PDF, CSV, .odt, .txt and MS Word Document files. Your file must be smaller than 2MB. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) if you need to send other file types.
|
257
|
+
You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. [Contact the GOV.UK Notify team](https://www.notifications.service.gov.uk/support/ask-question-give-feedback) if you need to send other file types.
|
249
258
|
|
250
259
|
1. Pass the file object as an argument to the `Notifications.prepare_upload` helper method.
|
251
260
|
1. Pass the result into the personalisation argument.
|
@@ -263,9 +272,22 @@ File.open("file.pdf", "rb") do |f|
|
|
263
272
|
end
|
264
273
|
```
|
265
274
|
|
266
|
-
####
|
275
|
+
#### Set the filename
|
276
|
+
|
277
|
+
To do this you will need version 6.0.0 of the Ruby client library, or a more recent version.
|
278
|
+
|
279
|
+
You should provide a filename when you upload your file.
|
280
|
+
|
281
|
+
The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.
|
267
282
|
|
268
|
-
|
283
|
+
The filename must end with a file extension. For example, `.csv` for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.
|
284
|
+
|
285
|
+
If you do not provide a filename for your file, Notify will:
|
286
|
+
|
287
|
+
* generate a random filename
|
288
|
+
* try to add the correct file extension
|
289
|
+
|
290
|
+
If Notify cannot add the correct file extension, recipients may not be able to open your file.
|
269
291
|
|
270
292
|
```ruby
|
271
293
|
File.open("file.csv", "rb") do |f|
|
@@ -273,12 +295,71 @@ File.open("file.csv", "rb") do |f|
|
|
273
295
|
personalisation: {
|
274
296
|
first_name: "Amala",
|
275
297
|
application_date: "2018-01-01",
|
276
|
-
link_to_file: Notifications.prepare_upload(f,
|
298
|
+
link_to_file: Notifications.prepare_upload(f, filename="2023-12-25-daily-report.csv"),
|
299
|
+
}
|
300
|
+
end
|
301
|
+
```
|
302
|
+
|
303
|
+
#### Ask recipients to confirm their email address before they can download the file
|
304
|
+
|
305
|
+
When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.
|
306
|
+
|
307
|
+
This security feature is turned on by default.
|
308
|
+
|
309
|
+
##### Turn off email address check (not recommended)
|
310
|
+
|
311
|
+
If you do not want to use this feature, you can turn it off on a file-by-file basis.
|
312
|
+
|
313
|
+
To do this you will need version 5.4.0 of the Ruby client library, or a more recent version.
|
314
|
+
|
315
|
+
You should not turn this feature off if you send files that contain:
|
316
|
+
|
317
|
+
* personally identifiable information
|
318
|
+
* commercially sensitive information
|
319
|
+
* information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the [Government Security Classifications](https://www.gov.uk/government/publications/government-security-classifications) policy
|
320
|
+
|
321
|
+
To let the recipient download the file without confirming their email address, set the `confirm_email_before_download` flag to `false`.
|
322
|
+
|
323
|
+
|
324
|
+
|
325
|
+
```ruby
|
326
|
+
File.open("file.pdf", "rb") do |f|
|
327
|
+
...
|
328
|
+
personalisation: {
|
329
|
+
first_name: "Amala",
|
330
|
+
application_date: "2018-01-01",
|
331
|
+
link_to_file: Notifications.prepare_upload(f, confirm_email_before_download: false),
|
332
|
+
}
|
333
|
+
end
|
334
|
+
```
|
335
|
+
|
336
|
+
#### Choose the length of time that a file is available to download
|
337
|
+
|
338
|
+
Set the number of weeks you want the file to be available using the `retention_period` key.
|
339
|
+
|
340
|
+
To use this feature will need version 5.4.0 of the Ruby client library, or a more recent version.
|
341
|
+
|
342
|
+
You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:
|
343
|
+
|
344
|
+
* the need to protect the recipient’s personal information
|
345
|
+
* whether the recipient will need to download the file again later
|
346
|
+
|
347
|
+
If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).
|
348
|
+
|
349
|
+
Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).
|
350
|
+
|
351
|
+
```ruby
|
352
|
+
File.open("file.pdf", "rb") do |f|
|
353
|
+
...
|
354
|
+
personalisation: {
|
355
|
+
first_name: "Amala",
|
356
|
+
application_date: "2018-01-01",
|
357
|
+
link_to_file: Notifications.prepare_upload(f, retention_period: '52 weeks'),
|
277
358
|
}
|
278
359
|
end
|
279
360
|
```
|
280
361
|
|
281
|
-
|
362
|
+
#### Response
|
282
363
|
|
283
364
|
If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](#send-an-email-method), the object is named `emailresponse`.
|
284
365
|
|
@@ -286,13 +367,13 @@ You can then call different methods on this object to return the requested infor
|
|
286
367
|
|
287
368
|
|Method|Information|Type|
|
288
369
|
|:---|:---|:---|
|
289
|
-
|
290
|
-
|
291
|
-
|
292
|
-
|
293
|
-
|
370
|
+
|#`emailresponse.id`|Notification UUID|String|
|
371
|
+
|#`emailresponse.reference`|`reference` argument|String|
|
372
|
+
|#`emailresponse.content`|- `body`: Message body<br>- `subject`: Message subject<br>- `from_email`: From email address of your service found on the **Settings** page|Hash|
|
373
|
+
|#`emailresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
|
374
|
+
|#`emailresponse.uri`|Notification URL|String|
|
294
375
|
|
295
|
-
|
376
|
+
#### Error codes
|
296
377
|
|
297
378
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
298
379
|
|
@@ -300,9 +381,12 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
300
381
|
|:--- |:---|:---|:---|
|
301
382
|
|`400`|`BadRequestError: Can't send to this recipient using a team-only API key`|`BadRequestError`|Use the correct type of [API key](#api-keys)|
|
302
383
|
|`400`|`BadRequestError: Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode`|`BadRequestError`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)|
|
303
|
-
|`400`|`BadRequestError: Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)'`|`BadRequestError`|Wrong file type. You can only upload .pdf, .csv, .txt, .doc, .docx or .odt files|
|
384
|
+
|`400`|`BadRequestError: Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)'`|`BadRequestError`|Wrong file type. You can only upload .pdf, .csv, .txt, .doc, .docx, .xlsx, .rtf or .odt files|
|
385
|
+
|`400`|`BadRequestError: Unsupported value for retention_period '(PERIOD)'. Supported periods are from 1 to 78 weeks.`|`BadRequestError`|Choose a period between 1 and 78 weeks|
|
386
|
+
|`400`|`BadRequestError: Unsupported value for confirm_email_before_download: '(VALUE)'. Use a boolean true or false value.`|`BadRequestError`|Use either true or false|
|
304
387
|
|`400`|`BadRequestError: File did not pass the virus scan`|`BadRequestError`|The file contains a virus|
|
305
388
|
|`400`|`BadRequestError: Send files by email has not been set up - add contact details for your service at https://www.notifications.service.gov.uk/services/(SERVICE ID)/service-settings/send-files-by-email`|`BadRequestError`|See how to [add contact details to the file download page](#add-contact-details-to-the-file-download-page)|
|
389
|
+
|`400`|`BadRequestError: Can only send a file by email` | `BadRequestError`|Make sure you are using an email template|
|
306
390
|
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
307
391
|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
308
392
|
|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](#rate-limits) for more information|
|
@@ -310,7 +394,7 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
310
394
|
|`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification|
|
311
395
|
|-|`ArgumentError: File is larger than 2MB")`|-|The file is too big. Files must be smaller than 2MB|
|
312
396
|
|
313
|
-
|
397
|
+
### Send a letter
|
314
398
|
|
315
399
|
When you add a new service it will start in [trial mode](https://www.notifications.service.gov.uk/features/trial-mode). You can only send letters when your service is live.
|
316
400
|
|
@@ -320,7 +404,7 @@ To send Notify a request to go live:
|
|
320
404
|
1. Go to the __Settings__ page.
|
321
405
|
1. In the __Your service is in trial mode__ section, select __request to go live__.
|
322
406
|
|
323
|
-
|
407
|
+
#### Method
|
324
408
|
|
325
409
|
```ruby
|
326
410
|
letterresponse = client.send_letter(
|
@@ -328,14 +412,14 @@ letterresponse = client.send_letter(
|
|
328
412
|
personalisation: {
|
329
413
|
address_line_1: 'The Occupier',
|
330
414
|
address_line_2: '123 High Street',
|
331
|
-
|
415
|
+
address_line_3: 'SW14 6BH',
|
332
416
|
},
|
333
417
|
)
|
334
418
|
```
|
335
419
|
|
336
|
-
|
420
|
+
#### Arguments
|
337
421
|
|
338
|
-
|
422
|
+
##### template_id (required)
|
339
423
|
|
340
424
|
To find the template ID:
|
341
425
|
|
@@ -349,13 +433,25 @@ For example:
|
|
349
433
|
template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a"
|
350
434
|
```
|
351
435
|
|
352
|
-
|
436
|
+
##### personalisation (required)
|
353
437
|
|
354
438
|
The personalisation argument always contains the following parameters for the letter recipient’s address:
|
355
439
|
|
356
440
|
- `address_line_1`
|
357
441
|
- `address_line_2`
|
358
|
-
- `
|
442
|
+
- `address_line_3`
|
443
|
+
- `address_line_4`
|
444
|
+
- `address_line_5`
|
445
|
+
- `address_line_6`
|
446
|
+
- `address_line_7`
|
447
|
+
|
448
|
+
The address must have at least 3 lines.
|
449
|
+
|
450
|
+
The last line needs to be a real UK postcode or the name of a country outside the UK.
|
451
|
+
|
452
|
+
Notify checks for international addresses and will automatically charge you the correct postage.
|
453
|
+
|
454
|
+
The `postcode` personalisation argument has been replaced. If your template still uses `postcode`, Notify will treat it as the last line of the address.
|
359
455
|
|
360
456
|
Any other placeholder fields included in the letter template also count as required parameters. You must provide their values in a hash. For example:
|
361
457
|
|
@@ -364,26 +460,15 @@ Any other placeholder fields included in the letter template also count as requi
|
|
364
460
|
personalisation: {
|
365
461
|
address_line_1: 'The Occupier', # mandatory address field
|
366
462
|
address_line_2: '123 High Street', # mandatory address field
|
367
|
-
|
463
|
+
address_line_3: 'SW14 6BH', # mandatory address field
|
368
464
|
name: 'John Smith', # field from template
|
369
|
-
application_date: '2018-01-01' # field from template
|
370
|
-
|
371
|
-
|
372
|
-
|
373
|
-
#### personalisation (optional)
|
374
|
-
|
375
|
-
The following parameters in the letter recipient’s address are optional:
|
376
|
-
|
377
|
-
```ruby
|
378
|
-
personalisation: {
|
379
|
-
address_line_3: 'Richmond', # optional address field
|
380
|
-
address_line_4: 'London', # optional address field
|
381
|
-
address_line_5: 'Middlesex', # optional address field
|
382
|
-
address_line_6: 'UK', # optional address field
|
465
|
+
application_date: '2018-01-01' # field from template,
|
466
|
+
# pass in an array and it will appear as bullet points in the letter:
|
467
|
+
required_documents: ["passport", "utility bill", "other id"],
|
383
468
|
},
|
384
469
|
```
|
385
470
|
|
386
|
-
|
471
|
+
##### reference (optional)
|
387
472
|
|
388
473
|
A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:
|
389
474
|
|
@@ -391,7 +476,7 @@ A unique identifier you can create if necessary. This reference identifies a sin
|
|
391
476
|
reference: 'your_reference_string'
|
392
477
|
```
|
393
478
|
|
394
|
-
|
479
|
+
#### Response
|
395
480
|
|
396
481
|
If the request to the client is successful, the client returns a `Notifications::Client:ResponseNotification` object. In the example shown in the [Method section](#send-a-letter-method), the object is named `letterresponse`.
|
397
482
|
|
@@ -399,44 +484,45 @@ You can then call different methods on this object to return the requested infor
|
|
399
484
|
|
400
485
|
|Method|Information|Type|
|
401
486
|
|:---|:---|:---|
|
402
|
-
|
403
|
-
|
404
|
-
|
405
|
-
|
406
|
-
|
487
|
+
|#`letterresponse.id`|Notification UUID|String|
|
488
|
+
|#`letterresponse.reference`|`reference` argument|String|
|
489
|
+
|#`letterresponse.content`|- `body`: Letter body<br>- `subject`: Letter subject or main heading|Hash|
|
490
|
+
|#`letterresponse.template`|Contains the `id`, `version` and `uri` of the template|Hash|
|
491
|
+
|#`letterresponse.uri`|Notification URL|String|
|
407
492
|
|
408
493
|
|
409
|
-
|
494
|
+
#### Error codes
|
410
495
|
|
411
496
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
412
497
|
|
413
498
|
|error.code|error.message|class|How to fix|
|
414
499
|
|:--- |:---|:---|:---|
|
415
|
-
|`400`|`BadRequestError: Cannot send letters with a team api key`|`BadRequestError`|Use the correct type of [API key](#api-keys)
|
416
|
-
|`400`|`BadRequestError: Cannot send letters when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode`|`BadRequestError`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode)
|
417
|
-
|`400`|`ValidationError: personalisation address_line_1 is a required property`|`BadRequestError`|Ensure that your template has a field for the first line of the address, refer to [personalisation](#personalisation-required) for more information
|
418
|
-
|`400`|`ValidationError: Must be a real UK postcode
|
419
|
-
|`
|
420
|
-
|`403`|`AuthError:
|
421
|
-
|`
|
422
|
-
|`429`|`
|
423
|
-
|`
|
424
|
-
|
425
|
-
|
426
|
-
|
427
|
-
|
500
|
+
|`400`|`BadRequestError: Cannot send letters with a team api key`|`BadRequestError`|Use the correct type of [API key](#api-keys).|
|
501
|
+
|`400`|`BadRequestError: Cannot send letters when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode`|`BadRequestError`|Your service cannot send this notification in [trial mode](https://www.notifications.service.gov.uk/features/using-notify#trial-mode).|
|
502
|
+
|`400`|`ValidationError: personalisation address_line_1 is a required property`|`BadRequestError`|Ensure that your template has a field for the first line of the address, refer to [personalisation](#personalisation-required) for more information.|
|
503
|
+
|`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "Must be a real UK postcode"`<br>`}]`|Ensure that the value for the last line of the address is a real UK postcode.|
|
504
|
+
|`400`|`[{`<br>`"error": "ValidationError",`<br>`"message": "Last line of address must be a real UK postcode or another country"`<br>`}]`|Ensure that the value for the last line of the address is a real UK postcode or the name of a country outside the UK.|
|
505
|
+
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock.|
|
506
|
+
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information.|
|
507
|
+
|`429`|`RateLimitError: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds`|`RateLimitError`|Refer to [API rate limits](#rate-limits) for more information.|
|
508
|
+
|`429`|`TooManyRequestsError: Exceeded send limits (LIMIT NUMBER) for today`|`RateLimitError`|Refer to [service limits](#daily-limits) for the limit number.|
|
509
|
+
|`500`|`Exception: Internal server error`|`ServerError`|Notify was unable to process the request, resend your notification.|
|
510
|
+
|
511
|
+
### Send a precompiled letter
|
512
|
+
|
513
|
+
#### Method
|
428
514
|
```ruby
|
429
515
|
precompiled_letter = client.send_precompiled_letter(reference, pdf_file)
|
430
516
|
```
|
431
517
|
|
432
|
-
|
518
|
+
#### Arguments
|
433
519
|
|
434
|
-
|
520
|
+
##### reference (required)
|
435
521
|
A unique identifier you create. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address.
|
436
522
|
|
437
|
-
|
523
|
+
##### pdf_file (required)
|
438
524
|
|
439
|
-
The precompiled letter must be a PDF file which meets [the GOV.UK Notify
|
525
|
+
The precompiled letter must be a PDF file which meets [the GOV.UK Notify letter specification](https://www.notifications.service.gov.uk/using-notify/guidance/letter-specification).
|
440
526
|
|
441
527
|
```ruby
|
442
528
|
File.open("path/to/pdf_file", "rb") do |pdf_file|
|
@@ -444,25 +530,25 @@ File.open("path/to/pdf_file", "rb") do |pdf_file|
|
|
444
530
|
end
|
445
531
|
```
|
446
532
|
|
447
|
-
|
533
|
+
##### postage (optional)
|
448
534
|
|
449
535
|
You can choose first or second class postage for your precompiled letter. Set the value to `first` for first class, or `second` for second class. If you do not pass in this argument, the postage will default to second class.
|
450
536
|
|
451
537
|
|
452
|
-
|
538
|
+
#### Response
|
453
539
|
|
454
|
-
If the request to the client is successful, the client returns a `Notifications::Client:ResponsePrecompiledLetter` object. In the example shown in the [Method section](#send-a-
|
540
|
+
If the request to the client is successful, the client returns a `Notifications::Client:ResponsePrecompiledLetter` object. In the example shown in the [Method section](#send-a-precompiled-letter-method), the object is named `precompiled_letter`.
|
455
541
|
|
456
542
|
You can then call different methods on this object to return the requested information.
|
457
543
|
|
458
544
|
|Method|Information|Type|
|
459
545
|
|:---|:---|:---|
|
460
|
-
|
461
|
-
|
462
|
-
|
546
|
+
|#`precompiled_letter.id`|Notification UUID|String|
|
547
|
+
|#`precompiled_letter.reference`|`reference` argument|String|
|
548
|
+
|#`precompiled_letter.postage`|`postage` argument|String|
|
463
549
|
|
464
550
|
|
465
|
-
|
551
|
+
#### Error codes
|
466
552
|
|
467
553
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
468
554
|
|
@@ -476,67 +562,30 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
476
562
|
|`429`|`RateLimitError: Exceeded rate limit for key type live of 10 requests per 20 seconds`|`RateLimitError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
477
563
|
|`429`|`TooManyRequestsError: Exceeded send limits (50) for today`|`RateLimitError`|Refer to [service limits](#daily-limits) for the limit number|
|
478
564
|
|
479
|
-
|
480
|
-
|
481
|
-
Message status depends on the type of message you have sent.
|
482
|
-
|
483
|
-
You can only get the status of messages that are 7 days old or newer.
|
484
|
-
|
485
|
-
## Status - email
|
486
|
-
|
487
|
-
|Status|Information|
|
488
|
-
|:---|:---|
|
489
|
-
|Created|GOV.UK Notify has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds.|
|
490
|
-
|Sending|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. GOV.UK Notify is waiting for delivery information.|
|
491
|
-
|Delivered|The message was successfully delivered.|
|
492
|
-
|Failed|This covers all failure statuses:<br>- `permanent-failure` - "The provider could not deliver the message because the email address was wrong. You should remove these email addresses from your database."<br>- `temporary-failure` - "The provider could not deliver the message. This can happen when the recipient’s inbox is full. You can try to send the message again."<br>- `technical-failure` - "Your message was not sent because there was a problem between Notify and the provider.<br>You’ll have to try sending your messages again."|
|
493
|
-
|
494
|
-
## Status - text message
|
495
|
-
|
496
|
-
|Status|Information|
|
497
|
-
|:---|:---|
|
498
|
-
|Created|GOV.UK Notify has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds.|
|
499
|
-
|Sending|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. GOV.UK Notify is waiting for delivery information.|
|
500
|
-
|Pending|GOV.UK Notify is waiting for more delivery information.<br>GOV.UK Notify received a callback from the provider but the recipient’s device has not yet responded. Another callback from the provider determines the final status of the notification.|
|
501
|
-
|Sent / Sent internationally|The message was sent to an international number. The mobile networks in some countries do not provide any more delivery information. The GOV.UK Notify client API returns this status as `sent`. The GOV.UK Notify client app returns this status as `Sent internationally`.|
|
502
|
-
|Delivered|The message was successfully delivered.|
|
503
|
-
|Failed|This covers all failure statuses:<br>- `permanent-failure` - "The provider could not deliver the message. This can happen if the phone number was wrong or if the network operator rejects the message. If you’re sure that these phone numbers are correct, you should [contact GOV.UK Notify support](https://www.notifications.service.gov.uk/support). If not, you should remove them from your database. You’ll still be charged for text messages that cannot be delivered."<br>- `temporary-failure` - "The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages."<br>- `technical-failure` - "Your message was not sent because there was a problem between Notify and the provider.<br>You’ll have to try sending your messages again. You will not be charged for text messages that are affected by a technical failure."|
|
504
|
-
|
505
|
-
## Status - letter
|
506
|
-
|
507
|
-
|Status|information|
|
508
|
-
|:---|:---|
|
509
|
-
|Failed|The only failure status that applies to letters is `technical-failure`. GOV.UK Notify had an unexpected error while sending to our printing provider.|
|
510
|
-
|Accepted|GOV.UK Notify has sent the letter to the provider to be printed.|
|
511
|
-
|Received|The provider has printed and dispatched the letter.|
|
565
|
+
## Get message status
|
512
566
|
|
513
|
-
## Status - precompiled letter
|
514
567
|
|
515
|
-
|Status|information|
|
516
|
-
|:---|:---|
|
517
|
-
|Pending virus check|GOV.UK Notify has not completed a virus scan of the precompiled letter file.|
|
518
|
-
|Virus scan failed|GOV.UK Notify found a potential virus in the precompiled letter file.|
|
519
|
-
|Validation failed|Content in the precompiled letter file is outside the printable area. See the [GOV.UK Notify PDF letter specification](https://docs.notifications.service.gov.uk/documentation/images/notify-pdf-letter-spec-v2.3.pdf) for more information.|
|
520
568
|
|
521
|
-
|
569
|
+
### Get the status of one message
|
522
570
|
|
523
|
-
You can only get the status of messages
|
571
|
+
You can only get the status of messages sent within the retention period. The default retention period is 7 days.
|
524
572
|
|
525
|
-
|
573
|
+
#### Method
|
526
574
|
|
527
575
|
```ruby
|
528
576
|
response = client.get_notification(id)
|
529
577
|
```
|
530
578
|
|
531
|
-
|
579
|
+
#### Arguments
|
532
580
|
|
533
|
-
|
581
|
+
##### id (required)
|
534
582
|
|
535
|
-
The ID of the notification.
|
583
|
+
The ID of the notification. To find the notification ID, you can either:
|
536
584
|
|
537
|
-
|
585
|
+
* check the response to the [original notification method call](#response)
|
586
|
+
* [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __API integration__ page
|
538
587
|
|
539
|
-
|
588
|
+
#### Response
|
540
589
|
|
541
590
|
If the request to the client is successful, the client returns a `Notifications::Client::Notification` object. In the example shown in the [Method section](#get-the-status-of-one-message-method), the object is named `response`.
|
542
591
|
|
@@ -544,29 +593,29 @@ You can then call different methods on this object to return the requested infor
|
|
544
593
|
|
545
594
|
|Method|Information|Type|
|
546
595
|
|:---|:---|:---|
|
547
|
-
|
548
|
-
|
549
|
-
|
550
|
-
|
551
|
-
|
552
|
-
|
553
|
-
|
554
|
-
|
555
|
-
|
556
|
-
|
557
|
-
|
558
|
-
|
559
|
-
|
560
|
-
|
561
|
-
|
562
|
-
|
563
|
-
|
564
|
-
|
565
|
-
|
566
|
-
|
567
|
-
|
568
|
-
|
569
|
-
|
596
|
+
|#`response.id`|Notification UUID|String|
|
597
|
+
|#`response.reference`| String supplied in `reference` argument|String|
|
598
|
+
|#`response.email_address`|Recipient email address (email only)|String|
|
599
|
+
|#`response.phone_number`|Recipient phone number (SMS only)|String|
|
600
|
+
|#`response.line_1`|Recipient address line 1 of the address (letter only)|String|
|
601
|
+
|#`response.line_2`|Recipient address line 2 of the address (letter only)|String|
|
602
|
+
|#`response.line_3`|Recipient address line 3 of the address (letter only)|String|
|
603
|
+
|#`response.line_4`|Recipient address line 4 of the address (letter only)|String|
|
604
|
+
|#`response.line_5`|Recipient address line 5 of the address (letter only)|String|
|
605
|
+
|#`response.line_6`|Recipient address line 6 of the address (letter only)|String|
|
606
|
+
|#`response.line_7`|Recipient address line 7 of the address (letter only)|String|
|
607
|
+
|#`response.postage`|Postage class of the notification sent (letter only)|String|
|
608
|
+
|#`response.type`|Type of notification sent (sms, email or letter)|String|
|
609
|
+
|#`response.status`|Notification status (sending / delivered / permanent-failure / temporary-failure / technical-failure)|String|
|
610
|
+
|#`response.template`|Template UUID|String|
|
611
|
+
|#`response.body`|Notification body|String|
|
612
|
+
|#`response.subject`|Notification subject (email and letter)|String|
|
613
|
+
|#`response.sent_at`|Date and time notification sent to provider|String|
|
614
|
+
|#`response.created_at`|Date and time notification created|String|
|
615
|
+
|#`response.completed_at`|Date and time notification delivered or failed|String|
|
616
|
+
|#`response.created_by_name`|Name of sender if notification sent manually|String|
|
617
|
+
|
618
|
+
#### Error codes
|
570
619
|
|
571
620
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
572
621
|
|
@@ -577,13 +626,13 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
577
626
|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
578
627
|
|`404`|`NoResultFound: No result found`|`NotFoundError`|Check the notification ID. This error occurs if the notification is more than 7 days old.|
|
579
628
|
|
580
|
-
|
629
|
+
### Get the status of multiple messages
|
581
630
|
|
582
631
|
This API call returns one page of up to 250 messages and statuses. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the `older_than` argument.
|
583
632
|
|
584
633
|
You can only get messages that are 7 days old or newer.
|
585
634
|
|
586
|
-
|
635
|
+
#### Method
|
587
636
|
|
588
637
|
```ruby
|
589
638
|
args = {
|
@@ -599,22 +648,22 @@ You can leave out the `older_than` argument to get the 250 most recent messages.
|
|
599
648
|
|
600
649
|
To get older messages, pass the ID of an older notification into the `older_than` argument. This returns the next 250 oldest messages from the specified notification ID.
|
601
650
|
|
602
|
-
|
651
|
+
#### Arguments
|
603
652
|
|
604
653
|
You can leave out these arguments to ignore these filters.
|
605
654
|
|
606
|
-
|
655
|
+
##### status (optional)
|
607
656
|
|
608
657
|
You can filter by each:
|
609
658
|
|
610
|
-
* [email status](#status-
|
611
|
-
* [text message status](#
|
612
|
-
* [letter status](#status-
|
613
|
-
* [precompiled letter status](#
|
659
|
+
* [email status](#email-status-descriptions)
|
660
|
+
* [text message status](#text-message-status-descriptions)
|
661
|
+
* [letter status](#letter-status-descriptions)
|
662
|
+
* [precompiled letter status](#precompiled-letter-status-descriptions)
|
614
663
|
|
615
664
|
You can leave out this argument to ignore this filter.
|
616
665
|
|
617
|
-
|
666
|
+
##### templateType (optional)
|
618
667
|
|
619
668
|
You can filter by:
|
620
669
|
|
@@ -622,7 +671,7 @@ You can filter by:
|
|
622
671
|
* `sms`
|
623
672
|
* `letter`
|
624
673
|
|
625
|
-
|
674
|
+
##### reference (optional)
|
626
675
|
|
627
676
|
A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:
|
628
677
|
|
@@ -630,7 +679,7 @@ A unique identifier you can create if necessary. This reference identifies a sin
|
|
630
679
|
reference: 'your_reference_string'
|
631
680
|
```
|
632
681
|
|
633
|
-
|
682
|
+
##### older_than (optional)
|
634
683
|
|
635
684
|
Input the ID of a notification into this argument. If you use this argument, the client returns the next 250 received notifications older than the given ID. For example:
|
636
685
|
|
@@ -642,7 +691,7 @@ If you leave out this argument, the client returns the most recent 250 notificat
|
|
642
691
|
|
643
692
|
The client only returns notifications that are 7 days old or newer. If the notification specified in this argument is older than 7 days, the client returns an empty response.
|
644
693
|
|
645
|
-
|
694
|
+
#### Response
|
646
695
|
|
647
696
|
If the request to the client is successful, the client returns a `Notifications::Client::NotificationsCollection` object. In the example shown in the [Method section](#get-the-status-of-multiple-messages-method), the object is named `response`.
|
648
697
|
|
@@ -650,37 +699,37 @@ You must then call either the `.links` method or the `.collection` method on thi
|
|
650
699
|
|
651
700
|
|Method|Information|
|
652
701
|
|:---|:---|
|
653
|
-
|
654
|
-
|
702
|
+
|#`response.links`|Returns a hash linking to the requested notifications (limited to 250)|
|
703
|
+
|#`response.collection`|Returns an array of the required notifications|
|
655
704
|
|
656
705
|
If you call the `collection` method on this object to return a notification array, you must then call the following methods on the notifications in this array to return information on those notifications:
|
657
706
|
|
658
707
|
|Method|Information|Type|
|
659
708
|
|:---|:---|:---|
|
660
|
-
|
661
|
-
|
662
|
-
|
663
|
-
|
664
|
-
|
665
|
-
|
666
|
-
|
667
|
-
|
668
|
-
|
669
|
-
|
670
|
-
|
671
|
-
|
672
|
-
|
673
|
-
|
674
|
-
|
675
|
-
|
676
|
-
|
677
|
-
|
678
|
-
|
679
|
-
|
709
|
+
|#`response.id`|Notification UUID|String|
|
710
|
+
|#`response.reference`| String supplied in `reference` argument|String|
|
711
|
+
|#`response.email_address`|Recipient email address (email only)|String|
|
712
|
+
|#`response.phone_number`|Recipient phone number (SMS only)|String|
|
713
|
+
|#`response.line_1`|Recipient address line 1 of the address (letter only)|String|
|
714
|
+
|#`response.line_2`|Recipient address line 2 of the address (letter only)|String|
|
715
|
+
|#`response.line_3`|Recipient address line 3 of the address (letter only)|String|
|
716
|
+
|#`response.line_4`|Recipient address line 4 of the address (letter only)|String|
|
717
|
+
|#`response.line_5`|Recipient address line 5 of the address (letter only)|String|
|
718
|
+
|#`response.line_6`|Recipient address line 6 of the address (letter only)|String|
|
719
|
+
|#`response.postcode`|Recipient postcode (letter only)|String|
|
720
|
+
|#`response.type`|Type of notification sent (sms, email or letter)|String|
|
721
|
+
|#`response.status`|Notification status (sending / delivered / permanent-failure / temporary-failure / technical-failure)|String|
|
722
|
+
|#`response.template`|Template UUID|String|
|
723
|
+
|#`response.body`|Notification body|String|
|
724
|
+
|#`response.subject`|Notification subject (email and letter)|String|
|
725
|
+
|#`response.sent_at`|Date and time notification sent to provider|String|
|
726
|
+
|#`response.created_at`|Date and time notification created|String|
|
727
|
+
|#`response.completed_at`|Date and time notification delivered or failed|String|
|
728
|
+
|#`response.created_by_name`|Name of sender if notification sent manually|String|
|
680
729
|
|
681
730
|
If the notification specified in the `older_than` argument is older than 7 days, the client returns an empty `collection` response.
|
682
731
|
|
683
|
-
|
732
|
+
#### Error codes
|
684
733
|
|
685
734
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
686
735
|
|
@@ -691,9 +740,57 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
691
740
|
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
692
741
|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
693
742
|
|
694
|
-
|
743
|
+
### Email status descriptions
|
695
744
|
|
696
|
-
|
745
|
+
|Status|Description|
|
746
|
+
|:---|:---|
|
747
|
+
|#`created`|GOV.UK Notify has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds.|
|
748
|
+
|#`sending`|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. GOV.UK Notify is waiting for delivery information.|
|
749
|
+
|#`delivered`|The message was successfully delivered.|
|
750
|
+
|#`permanent-failure`|The provider could not deliver the message because the email address was wrong. You should remove these email addresses from your database.|
|
751
|
+
|#`temporary-failure`|The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. [Check your content does not look like spam](https://www.gov.uk/service-manual/design/sending-emails-and-text-messages#protect-your-users-from-spam-and-phishing) before you try to send the message again.|
|
752
|
+
|#`technical-failure`|Your message was not sent because there was a problem between Notify and the provider.<br>You’ll have to try sending your messages again.|
|
753
|
+
|
754
|
+
### Text message status descriptions
|
755
|
+
|
756
|
+
|Status|Description|
|
757
|
+
|:---|:---|
|
758
|
+
|#`created`|GOV.UK Notify has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds.|
|
759
|
+
|#`sending`|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. GOV.UK Notify is waiting for delivery information.|
|
760
|
+
|#`pending`|GOV.UK Notify is waiting for more delivery information.<br>GOV.UK Notify received a callback from the provider but the recipient’s device has not yet responded. Another callback from the provider determines the final status of the text message.|
|
761
|
+
|#`sent`|The message was sent to an international number. The mobile networks in some countries do not provide any more delivery information. The GOV.UK Notify website displays this status as 'Sent to an international number'.|
|
762
|
+
|#`delivered`|The message was successfully delivered. If a recipient blocks your sender name or mobile number, your message will still show as delivered.|
|
763
|
+
|#`permanent-failure`|The provider could not deliver the message. This can happen if the phone number was wrong or if the network operator rejects the message. If you’re sure that these phone numbers are correct, you should [contact GOV.UK Notify support](https://www.notifications.service.gov.uk/support). If not, you should remove them from your database. You’ll still be charged for text messages that cannot be delivered.
|
764
|
+
|#`temporary-failure`|The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.|
|
765
|
+
|#`technical-failure`|Your message was not sent because there was a problem between Notify and the provider.<br>You’ll have to try sending your messages again. You will not be charged for text messages that are affected by a technical failure.|
|
766
|
+
|
767
|
+
### Letter status descriptions
|
768
|
+
|
769
|
+
|Status|Description|
|
770
|
+
|:---|:---|
|
771
|
+
|#`accepted`|GOV.UK Notify has sent the letter to the provider to be printed.|
|
772
|
+
|#`received`|The provider has printed and dispatched the letter.|
|
773
|
+
|#`cancelled`|Sending cancelled. The letter will not be printed or dispatched.|
|
774
|
+
|#`technical-failure`|GOV.UK Notify had an unexpected error while sending the letter to our printing provider.|
|
775
|
+
|#`permanent-failure`|The provider cannot print the letter. Your letter will not be dispatched.|
|
776
|
+
|
777
|
+
### Precompiled letter status descriptions
|
778
|
+
|
779
|
+
|Status|Description|
|
780
|
+
|:---|:---|
|
781
|
+
|#`accepted`|GOV.UK Notify has sent the letter to the provider to be printed.|
|
782
|
+
|#`received`|The provider has printed and dispatched the letter.|
|
783
|
+
|#`cancelled`|Sending cancelled. The letter will not be printed or dispatched.|
|
784
|
+
|#`pending-virus-check`|GOV.UK Notify has not completed a virus scan of the precompiled letter file.|
|
785
|
+
|#`virus-scan-failed`|GOV.UK Notify found a potential virus in the precompiled letter file.|
|
786
|
+
|#`validation-failed`|Content in the precompiled letter file is outside the printable area. See the [GOV.UK Notify letter specification](https://www.notifications.service.gov.uk/using-notify/guidance/letter-specification) for more information.|
|
787
|
+
|#`technical-failure`|GOV.UK Notify had an unexpected error while sending the letter to our printing provider.|
|
788
|
+
|#`permanent-failure`|The provider cannot print the letter. Your letter will not be dispatched.|
|
789
|
+
|
790
|
+
|
791
|
+
### Get a PDF for a letter notification
|
792
|
+
|
793
|
+
#### Method
|
697
794
|
|
698
795
|
This returns the pdf contents of a letter notification.
|
699
796
|
|
@@ -703,19 +800,20 @@ pdf_file = client.get_pdf_for_letter(
|
|
703
800
|
)
|
704
801
|
```
|
705
802
|
|
706
|
-
|
803
|
+
#### Arguments
|
707
804
|
|
708
|
-
|
805
|
+
##### id (required)
|
709
806
|
|
710
|
-
The ID of the notification.
|
807
|
+
The ID of the notification. To find the notification ID, you can either:
|
711
808
|
|
712
|
-
|
809
|
+
* check the response to the [original notification method call](#get-the-status-of-one-message-response)
|
810
|
+
* [sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __API integration__ page
|
713
811
|
|
714
|
-
|
812
|
+
#### Response
|
715
813
|
|
716
814
|
If the request to the client is successful, the client will return a `string` containing the raw PDF data.
|
717
815
|
|
718
|
-
|
816
|
+
#### Error codes
|
719
817
|
|
720
818
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
721
819
|
|
@@ -731,11 +829,11 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
731
829
|
|`404`|`NoResultFound: No result found`|`BadRequestError`|Check the notification ID|
|
732
830
|
|
733
831
|
|
734
|
-
|
832
|
+
## Get a template
|
735
833
|
|
736
|
-
|
834
|
+
### Get a template by ID
|
737
835
|
|
738
|
-
|
836
|
+
#### Method
|
739
837
|
|
740
838
|
This returns the latest version of the template.
|
741
839
|
|
@@ -743,9 +841,9 @@ This returns the latest version of the template.
|
|
743
841
|
response = client.get_template_by_id(id)
|
744
842
|
```
|
745
843
|
|
746
|
-
|
844
|
+
#### Arguments
|
747
845
|
|
748
|
-
|
846
|
+
##### id (required)
|
749
847
|
|
750
848
|
The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __Templates__ page to find it. For example:
|
751
849
|
|
@@ -753,7 +851,7 @@ The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.ser
|
|
753
851
|
'f33517ff-2a88-4f6e-b855-c550268ce08a'
|
754
852
|
```
|
755
853
|
|
756
|
-
|
854
|
+
#### Response
|
757
855
|
|
758
856
|
If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](#get-a-template-by-id-method), the object is named `response`.
|
759
857
|
|
@@ -761,18 +859,18 @@ You can then call different methods on this object to return the requested infor
|
|
761
859
|
|
762
860
|
|Method|Information|Type|
|
763
861
|
|:---|:---|:---|
|
764
|
-
|
765
|
-
|
766
|
-
|
767
|
-
|
768
|
-
|
769
|
-
|
770
|
-
|
771
|
-
|
772
|
-
|
773
|
-
|
774
|
-
|
775
|
-
|
862
|
+
|#`response.id`|Template UUID|String|
|
863
|
+
|#`response.name`|Template name|String|
|
864
|
+
|#`response.type`|Template type (email/sms/letter)|String|
|
865
|
+
|#`response.created_at`|Date and time template created|String|
|
866
|
+
|#`response.updated_at`|Date and time template last updated (may be nil if version 1)|String|
|
867
|
+
|#`response.created_by`|Email address of person that created the template|String|
|
868
|
+
|#`response.version`|Template version|String|
|
869
|
+
|#`response.body`|Template content|String|
|
870
|
+
|#`response.subject`|Template subject (email and letter)|String|
|
871
|
+
|#`response.letter_contact_block`|Template letter contact block (letter)|String|
|
872
|
+
|
873
|
+
#### Error codes
|
776
874
|
|
777
875
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
778
876
|
|
@@ -783,17 +881,17 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
783
881
|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
784
882
|
|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](#get-a-template-by-id-arguments-id-required)|
|
785
883
|
|
786
|
-
|
884
|
+
### Get a template by ID and version
|
787
885
|
|
788
|
-
|
886
|
+
#### Method
|
789
887
|
|
790
888
|
```ruby
|
791
889
|
response = client.get_template_version(id, version)
|
792
890
|
```
|
793
891
|
|
794
|
-
|
892
|
+
#### Arguments
|
795
893
|
|
796
|
-
|
894
|
+
##### id (required)
|
797
895
|
|
798
896
|
The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __Templates__ page to find it. For example:
|
799
897
|
|
@@ -801,11 +899,11 @@ The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.ser
|
|
801
899
|
'f33517ff-2a88-4f6e-b855-c550268ce08a'
|
802
900
|
```
|
803
901
|
|
804
|
-
|
902
|
+
##### version (required)
|
805
903
|
|
806
904
|
The version number of the template.
|
807
905
|
|
808
|
-
|
906
|
+
#### Response
|
809
907
|
|
810
908
|
If the request to the client is successful, the client returns a `Notifications::Client::Template` object. In the example shown in the [Method section](#get-a-template-by-id-and-version-method), the object is named `response`.
|
811
909
|
|
@@ -813,18 +911,18 @@ You can then call different methods on this object to return the requested infor
|
|
813
911
|
|
814
912
|
|Method|Information|Type|
|
815
913
|
|:---|:---|:---|
|
816
|
-
|
817
|
-
|
818
|
-
|
819
|
-
|
820
|
-
|
821
|
-
|
822
|
-
|
823
|
-
|
824
|
-
|
825
|
-
|
826
|
-
|
827
|
-
|
914
|
+
|#`response.id`|Template UUID|String|
|
915
|
+
|#`response.name`|Template name|String|
|
916
|
+
|#`response.type`|Template type (email/sms/letter)|String|
|
917
|
+
|#`response.created_at`|Date and time template created|String|
|
918
|
+
|#`response.updated_at`|Date and time template last updated (may be nil if it is the first version)|String|
|
919
|
+
|#`response.created_by`|Email address of person that created the template|String|
|
920
|
+
|#`response.version`|Template version|String|
|
921
|
+
|#`response.body`|Template content|String|
|
922
|
+
|#`response.subject`|Template subject (email and letter)|String|
|
923
|
+
|#`response.letter_contact_block`|Template letter contact block (letter)|String|
|
924
|
+
|
925
|
+
#### Error codes
|
828
926
|
|
829
927
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
830
928
|
|
@@ -835,9 +933,9 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
835
933
|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
836
934
|
|`404`|`NoResultFound: No Result Found`|`NotFoundError`|Check your [template ID](#get-a-template-by-id-and-version-arguments-id-required) and [version](#version-required)|
|
837
935
|
|
838
|
-
|
936
|
+
### Get all templates
|
839
937
|
|
840
|
-
|
938
|
+
#### Method
|
841
939
|
|
842
940
|
This returns the latest version of all templates inside a collection object.
|
843
941
|
|
@@ -848,9 +946,9 @@ args = {
|
|
848
946
|
response = client.get_all_templates(args)
|
849
947
|
```
|
850
948
|
|
851
|
-
|
949
|
+
#### Arguments
|
852
950
|
|
853
|
-
|
951
|
+
##### type (optional)
|
854
952
|
|
855
953
|
If you do not use `type`, the client returns all templates. Otherwise you can filter by:
|
856
954
|
|
@@ -858,7 +956,7 @@ If you do not use `type`, the client returns all templates. Otherwise you can fi
|
|
858
956
|
- `sms`
|
859
957
|
- `letter`
|
860
958
|
|
861
|
-
|
959
|
+
#### Response
|
862
960
|
|
863
961
|
If the request to the client is successful, the client returns a `Notifications::Client::TemplateCollection` object. In the example shown in the [Method section](#get-all-templates-method), the object is named `response`.
|
864
962
|
|
@@ -868,20 +966,20 @@ Once the client has returned a template array, you must then call the following
|
|
868
966
|
|
869
967
|
|Method|Information|Type|
|
870
968
|
|:---|:---|:---|
|
871
|
-
|
872
|
-
|
873
|
-
|
874
|
-
|
875
|
-
|
876
|
-
|
877
|
-
|
878
|
-
|
879
|
-
|
880
|
-
|
969
|
+
|#`response.id`|Template UUID|String|
|
970
|
+
|#`response.name`|Template name|String|
|
971
|
+
|#`response.type`|Template type (email/sms/letter)|String|
|
972
|
+
|#`response.created_at`|Date and time template created|String|
|
973
|
+
|#`response.updated_at`|Date and time template last updated (may be nil if it is the first version)|String|
|
974
|
+
|#`response.created_by`|Email address of person that created the template|String|
|
975
|
+
|#`response.version`|Template version|String|
|
976
|
+
|#`response.body`|Template content|String|
|
977
|
+
|#`response.subject`|Template subject (email and letter)|String|
|
978
|
+
|#`response.letter_contact_block`|Template letter contact block (letter)|String|
|
881
979
|
|
882
980
|
If no templates exist for a template type or there no templates for a service, the templates array will be empty.
|
883
981
|
|
884
|
-
|
982
|
+
#### Error codes
|
885
983
|
|
886
984
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
887
985
|
|
@@ -889,9 +987,9 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
889
987
|
|:---|:---|:---|:---|
|
890
988
|
|`400`|`ValidationError: Template type is not one of [sms, email, letter]`|`BadRequestError`|Contact the Notify team|
|
891
989
|
|
892
|
-
|
990
|
+
### Generate a preview template
|
893
991
|
|
894
|
-
|
992
|
+
#### Method
|
895
993
|
|
896
994
|
This generates a preview version of a template.
|
897
995
|
|
@@ -901,9 +999,9 @@ response = client.generate_template_preview(id)
|
|
901
999
|
|
902
1000
|
The parameters in the personalisation argument must match the placeholder fields in the actual template. The API notification client ignores any extra fields in the method.
|
903
1001
|
|
904
|
-
|
1002
|
+
#### Arguments
|
905
1003
|
|
906
|
-
|
1004
|
+
##### id (required)
|
907
1005
|
|
908
1006
|
The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.service.gov.uk/sign-in) and go to the __Templates__ page to find it. For example:
|
909
1007
|
|
@@ -911,7 +1009,7 @@ The ID of the template. [Sign in to GOV.UK Notify](https://www.notifications.ser
|
|
911
1009
|
'f33517ff-2a88-4f6e-b855-c550268ce08a'
|
912
1010
|
```
|
913
1011
|
|
914
|
-
|
1012
|
+
##### personalisation (optional)
|
915
1013
|
|
916
1014
|
If a template has placeholder fields for personalised information such as name or application date, you must provide their values in a hash. For example:
|
917
1015
|
|
@@ -924,7 +1022,7 @@ personalisation: {
|
|
924
1022
|
|
925
1023
|
You can leave out this argument if a template does not have any placeholder fields for personalised information.
|
926
1024
|
|
927
|
-
|
1025
|
+
#### Response
|
928
1026
|
|
929
1027
|
If the request to the client is successful, the client returns a `Notifications::Client::TemplatePreview` object. In the example shown in the [Method section](#generate-a-preview-template-method), the object is named `response`.
|
930
1028
|
|
@@ -932,14 +1030,14 @@ You can then call different methods on this object to return the requested infor
|
|
932
1030
|
|
933
1031
|
|Method|Information|Type|
|
934
1032
|
|:---|:---|:---|
|
935
|
-
|
936
|
-
|
937
|
-
|
938
|
-
|
939
|
-
|
940
|
-
|
1033
|
+
|#`response.id`|Template UUID|String|
|
1034
|
+
|#`response.version`|Template version|String|
|
1035
|
+
|#`response.body`|Template content|String|
|
1036
|
+
|#`response.subject`|Template subject (email and letter)|String|
|
1037
|
+
|#`response.type`|Template type (sms/email/letter)|String|
|
1038
|
+
|#`response.html`|Body as rendered HTML (email only)|String|
|
941
1039
|
|
942
|
-
|
1040
|
+
#### Error codes
|
943
1041
|
|
944
1042
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
945
1043
|
|
@@ -950,7 +1048,7 @@ If the request is not successful, the client raises a `Notifications::Client::Re
|
|
950
1048
|
|`403`|`AuthError: Error: Your system clock must be accurate to within 30 seconds`|`AuthError`|Check your system clock|
|
951
1049
|
|`403`|`AuthError: Invalid token: API key not found`|`AuthError`|Use the correct API key. Refer to [API keys](#api-keys) for more information|
|
952
1050
|
|
953
|
-
|
1051
|
+
## Get received text messages
|
954
1052
|
|
955
1053
|
This API call returns one page of up to 250 received text messages. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the `older_than` argument.
|
956
1054
|
|
@@ -958,13 +1056,16 @@ You can only get the status of messages that are 7 days old or newer.
|
|
958
1056
|
|
959
1057
|
You can also set up [callbacks](#callbacks) for received text messages.
|
960
1058
|
|
961
|
-
|
1059
|
+
### Enable received text messages
|
1060
|
+
|
1061
|
+
To receive text messages:
|
962
1062
|
|
963
|
-
|
1063
|
+
1. Go to the **Text message settings** section of the **Settings** page.
|
1064
|
+
1. Select **Change** on the **Receive text messages** row.
|
964
1065
|
|
965
|
-
|
1066
|
+
### Get a page of received text messages
|
966
1067
|
|
967
|
-
|
1068
|
+
#### Method
|
968
1069
|
|
969
1070
|
```ruby
|
970
1071
|
args = {
|
@@ -977,9 +1078,9 @@ To get older messages, pass the ID of an older notification into the `older_than
|
|
977
1078
|
|
978
1079
|
If you leave out the `older_than` argument, the client returns the most recent 250 notifications.
|
979
1080
|
|
980
|
-
|
1081
|
+
#### Arguments
|
981
1082
|
|
982
|
-
|
1083
|
+
##### older_than (optional)
|
983
1084
|
|
984
1085
|
Input the ID of a received text message into this argument. If you use this argument, the client returns the next 250 received text messages older than the given ID. For example:
|
985
1086
|
|
@@ -991,31 +1092,31 @@ If you leave out the `older_than` argument, the client returns the most recent 2
|
|
991
1092
|
|
992
1093
|
The client only returns notifications that are 7 days old or newer. If the notification specified in this argument is older than 7 days, the client returns an empty `collection` response.
|
993
1094
|
|
994
|
-
|
1095
|
+
#### Response
|
995
1096
|
|
996
|
-
If the request to the client is successful, the client returns a `Notifications::Client::ReceivedTextCollection` object. In the example shown in the [Method section](#get-received-text-messages-method), the object is named `response`.
|
1097
|
+
If the request to the client is successful, the client returns a `Notifications::Client::ReceivedTextCollection` object. In the example shown in the [Method section](#get-a-page-of-received-text-messages-method), the object is named `response`.
|
997
1098
|
|
998
1099
|
You must then call either the `.links` method or the `.collection` method on this object.
|
999
1100
|
|
1000
1101
|
|Method|Information|
|
1001
1102
|
|:---|:---|
|
1002
|
-
|
1003
|
-
|
1103
|
+
|#`response.links`|Returns a hash linking to the requested texts (limited to 250)|
|
1104
|
+
|#`response.collection`|Returns an array of the required texts|
|
1004
1105
|
|
1005
1106
|
If you call the `collection` method on this object to return an array, you must then call the following methods on the received texts in this array to return information on those texts:
|
1006
1107
|
|
1007
1108
|
|Method|Information|Type|
|
1008
1109
|
|:---|:---|:---|
|
1009
|
-
|
1010
|
-
|
1011
|
-
|
1012
|
-
|
1013
|
-
|
1014
|
-
|
1110
|
+
|#`response.id`|Received text UUID|String|
|
1111
|
+
|#`response.created_at`|Date and time of received text|String|
|
1112
|
+
|#`response.content`|Received text content|String|
|
1113
|
+
|#`response.notify_number`|Number that received text was sent to|String|
|
1114
|
+
|#`response.service_id`|Received text service ID|String|
|
1115
|
+
|#`response.user_number`|Number that received text was sent from|String|
|
1015
1116
|
|
1016
1117
|
If the notification specified in the `older_than` argument is older than 7 days, the client returns an empty `collection` response.
|
1017
1118
|
|
1018
|
-
|
1119
|
+
#### Error codes
|
1019
1120
|
|
1020
1121
|
If the request is not successful, the client raises a `Notifications::Client::RequestError` exception (or a subclass), which contains a code:
|
1021
1122
|
|