README.md in notifications-ruby-client-2.1.0 vs README.md in notifications-ruby-client-2.2.0
- old
+ new
@@ -26,11 +26,10 @@
### Send a message
Text message:
```ruby
-require 'notifications/client/response_notification'
sms = client.send_sms(
phone_number: number,
template_id: template_id,
personalisation: {
name: "name",
@@ -50,18 +49,16 @@
```ruby
sms => Notifications::Client::ResponseNotification
sms.id # => uuid for the notification
sms.reference # => Reference string you supplied in the request
-sms.type # => sms
-sms.status # => status of the message "created|pending|sent|delivered|permanent-failure|temporary-failure"
-content # => Hash containing body => the message sent to the recipient, with placeholders replaced.
+sms.content # => Hash containing body => the message sent to the recipient, with placeholders replaced.
# from_number => the sms sender number of your service found **Settings** page
-template # => Hash containing id => id of the template
+sms.template # => Hash containing id => id of the template
# version => version of the template
- # uri => url of the template
-uri # => URL of the notification
+ # uri => url of the template
+sms.uri # => URL of the notification
```
Otherwise the client will raise a `Notifications::Client::RequestError`:
<table>
<thead>
@@ -69,10 +66,23 @@
<th>error.code</th>
<th>error.message</th>
</tr>
</thead>
<tbody>
+ <tr>
+ <td>
+ <pre>429</pre>
+ </td>
+ <td>
+ <pre>
+ [{
+ "error": "RateLimitError",
+ "message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
+ }]
+ </pre>
+ </td>
+ </tr>
<tr>
<td>
<pre>429</pre>
</td>
<td>
@@ -117,11 +127,10 @@
Email:
```ruby
-require 'notifications/client/response_notification'
email = client.send_email(
email_address: email_address,
template_id: template_id,
personalisation: {
name: "name",
@@ -141,18 +150,16 @@
```ruby
email => Notifications::Client::ResponseNotification
email.id # => uuid for the notification
email.reference # => Reference string you supplied in the request
-email.type # => email
-email.status # => status of the message "created|pending|sent|delivered|permanent-failure|temporary-failure"
email.content # => Hash containing body => the message sent to the recipient, with placeholders replaced.
# subject => subject of the message sent to the recipient, with placeholders replaced.
# from_email => the from email of your service found **Settings** page
email.template # => Hash containing id => id of the template
# version => version of the template
- # uri => url of the template
+ # uri => url of the template
email.uri # => URL of the notification
```
Otherwise the client will raise a `Notifications::Client::RequestError`:
<table>
@@ -161,10 +168,23 @@
<th>error.code</th>
<th>error.message</th>
</tr>
</thead>
<tbody>
+ <tr>
+ <td>
+ <pre>429</pre>
+ </td>
+ <td>
+ <pre>
+ [{
+ "error": "RateLimitError",
+ "message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
+ }]
+ </pre>
+ </td>
+ </tr>
<tr>
<td>
<pre>429</pre>
</td>
<td>
@@ -205,10 +225,126 @@
</tr>
</tbody>
</table>
</details>
+Letter:
+
+```ruby
+letter = client.send_letter(
+ template_id: template_id,
+ personalisation: {
+ address_line_1: 'Her Majesty The Queen', # required
+ address_line_2: 'Buckingham Palace', # required
+ address_line_3: 'London',
+ postcode: 'SW1 1AA', # required
+
+ ... # any other personalisation found in your template
+ },
+ reference: "your_reference_string"
+) # => Notifications::Client::ResponseNotification
+```
+
+<details>
+<summary>
+Response
+</summary>
+
+If the request is successful, a `Notifications::Client:ResponseNotification` is returned
+
+```ruby
+letter => Notifications::Client::ResponseNotification
+
+letter.id # => uuid for the notification
+letter.reference # => Reference string you supplied in the request
+letter.content # => Hash containing body => the body of the letter sent to the recipient, with placeholders replaced
+ # subject => the main heading of the letter
+letter.template # => Hash containing id => id of the template
+ # version => version of the template
+ # uri => url of the template
+letter.uri # => URL of the notification
+```
+
+Otherwise the client will raise a `Notifications::Client::RequestError`:
+<table>
+<thead>
+<tr>
+<th>error.code</th>
+<th>error.message</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<pre>429</pre>
+</td>
+<td>
+<pre>
+[{
+ "error": "RateLimitError",
+ "message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
+}]
+</pre>
+</td>
+</tr>
+<tr>
+<td>
+<pre>429</pre>
+</td>
+<td>
+<pre>
+[{
+ "error": "TooManyRequestsError",
+ "message": "Exceeded send limits (50) for today"
+}]
+</pre>
+</td>
+</tr>
+<tr>
+<td>
+<pre>400</pre>
+</td>
+<td>
+<pre>
+[{
+ "error": "BadRequestError",
+ "message": "Can"t send to this recipient using a team-only API key"
+]}
+</pre>
+</td>
+</tr>
+<tr>
+<td>
+<pre>400</pre>
+</td>
+<td>
+<pre>
+[{
+ "error": "BadRequestError",
+ "message": "Can"t send to this recipient when service is in trial mode
+ - see https://www.notifications.service.gov.uk/trial-mode"
+}]
+</pre>
+</td>
+</tr>
+<tr>
+<td>
+<pre>400</pre>
+</td>
+<td>
+<pre>
+[{
+ "error": "ValidationError",
+ "message": "personalisation address_line_1 is a required property"
+}]
+</pre>
+</td>
+</tr>
+</tbody>
+</table>
+</details>
+
### Arguments
#### `phone_number`
The phone number of the recipient, only required when using `client.send_sms`.
#### `email_address`
@@ -230,12 +366,29 @@
'first_name' => 'Amala',
'reference_number' => '300241',
}
```
-You can omit this argument if the template does not contain placeholders.
+You can omit this argument if the template does not contain placeholders and is for email or sms.
+#### `personalisation` (for letters)
+
+If you are sending a letter, you will need to provide the letter fields in the format `"address_line_#"`, for example:
+
+```ruby
+personalisation: {
+ 'address_line_1' => 'The Occupier',
+ 'address_line_2' => '123 High Street',
+ 'address_line_3' => 'London',
+ 'postcode' => 'SW14 6BH',
+ 'first_name' => 'Amala',
+ 'reference_number' => '300241',
+}
+```
+
+The fields `address_line_1`, `address_line_2` and `postcode` are required.
+
### Get the status of one message
```ruby
notification = client.get_notification(id) # => Notifications::Client::Notification
```
@@ -304,9 +457,10 @@
</tbody>
</table>
</details>
</details>
+
### Get the status of all messages
```ruby
# See section below for a description of the arguments.
args = {