Class: GdsApi::EmailAlertApi

Inherits:
Base
  • Object
show all
Defined in:
lib/gds_api/email_alert_api.rb

Overview

Adapter for the Email Alert API

See Also:

Instance Attribute Summary

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

#client, #create_client, #get_list, #initialize, #url_for_slug

Constructor Details

This class inherits a constructor from GdsApi::Base

Instance Method Details

#authenticate_subscriber_by_govuk_account(govuk_account_session:) ⇒ Hash

Verify a GOV.UK Account-holder has a corresponding subscriber

Parameters:

  • govuk_account_session (string) —

    The request’s session identifier

Returns:

  • (Hash) —

    subscriber



186
187
188
189
190
191
 
# File 'lib/gds_api/email_alert_api.rb', line 186

def (govuk_account_session:)
  post_json(
    "#{endpoint}/subscribers/govuk-account",
    govuk_account_session: ,
  )
end

#bulk_unsubscribe(slug:, govuk_request_id: nil, body: nil, sender_message_id: nil) ⇒ Object

Unsubscribe all users for a subscription list optionally send a notification email explaining the reason

Parameters:

  • slug (string) —

    Identifier for the subscription list

  • (optional) (string) —

    govuk_request_id An ID allowing us to trace requests across our infra. Required if you want to send an email by running out-of-band processes via asynchronous workers.

  • (optional) (string) —

    body Optional email body to send to alert users they are being unsubscribed. Required if you want to send an email

  • (optional) (string) —

    sender_message_id A UUID to prevent multiple emails for the same event. Required if you want to send an email.



258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/gds_api/email_alert_api.rb', line 258

def bulk_unsubscribe(slug:, govuk_request_id: nil, body: nil, sender_message_id: nil)
  post_json(
    "#{endpoint}/subscriber-lists/#{slug}/bulk-unsubscribe",
    {
      body: body,
      sender_message_id: sender_message_id,
    }.compact,
    {
      "Govuk-Request-Id" => govuk_request_id,
    }.compact,
  )
end

#change_subscriber(id:, new_address:, on_conflict: nil) ⇒ Hash

Patch a Subscriber

Parameters:

  • Subscriber (integer) —

    id

  • Subscriber (string) —

    new_address

Returns:

  • (Hash) —

    subscriber



161
162
163
164
165
166
 
# File 'lib/gds_api/email_alert_api.rb', line 161

def change_subscriber(id:, new_address:, on_conflict: nil)
  patch_json(
    "#{endpoint}/subscribers/#{uri_encode(id)}",
    { new_address: new_address, on_conflict: on_conflict }.compact,
  )
end

#change_subscription(id:, frequency:) ⇒ Hash

Patch a Subscription

Parameters:

  • Subscription (string) —

    id

  • Subscription (string) —

    frequency

Returns:

  • (Hash) —

    subscription



174
175
176
177
178
179
 
# File 'lib/gds_api/email_alert_api.rb', line 174

def change_subscription(id:, frequency:)
  patch_json(
    "#{endpoint}/subscriptions/#{uri_encode(id)}",
    frequency: frequency,
  )
end

#create_content_change(content_change, headers = {}) ⇒ Object

Post a content change

Parameters:

  • content_change (Hash) —

    Valid content change attributes



33
34
35
 
# File 'lib/gds_api/email_alert_api.rb', line 33

def create_content_change(content_change, headers = {})
  post_json("#{endpoint}/content-changes", content_change, headers)
end

#create_message(message, headers = {}) ⇒ Object

Post a message

Parameters:

  • message (Hash) —

    Valid message attributes



40
41
42
43
 
# File 'lib/gds_api/email_alert_api.rb', line 40

def create_message(message, headers = {})
  warn "#create_message is deprecated and will be removed in a future version."
  post_json("#{endpoint}/messages", message, headers)
end

#find_or_create_subscriber_list(attributes) ⇒ Object

Get or Post subscriber list

Parameters:

  • attributes (Hash) —

    document_type, links, tags used to search existing subscriber lists



12
13
14
15
16
17
18
19
20
 
# File 'lib/gds_api/email_alert_api.rb', line 12

def find_or_create_subscriber_list(attributes)
  present_fields = [attributes["content_id"], attributes["links"], attributes["tags"]].compact.count
  if present_fields > 1
    message = "please provide content_id, tags, or links (or none), but not more than one of them"
    raise ArgumentError, message
  end

  post_json("#{endpoint}/subscriber-lists", attributes)
end

#find_subscriber_by_govuk_account(govuk_account_id:) ⇒ Hash

Find a subscriber which has been “linked” to a GOV.UK Account.

Parameters:

  • govuk_account_id (String) —

    An ID for the account.

Returns:

  • (Hash) —

    subscriber



213
214
215
216
217
 
# File 'lib/gds_api/email_alert_api.rb', line 213

def (govuk_account_id:)
  get_json(
    "#{endpoint}/subscribers/govuk-account/#{}",
  )
end

#find_subscriber_list(attributes) ⇒ Object

Get a subscriber list

Parameters:

  • attributes (Hash) —

    document_type, links, tags used to search existing subscriber lists



25
26
27
28
 
# File 'lib/gds_api/email_alert_api.rb', line 25

def find_subscriber_list(attributes)
  query_string = nested_query_string(attributes)
  get_json("#{endpoint}/subscriber-lists?" + query_string)
end

#get_latest_matching_subscription(id) ⇒ Hash

Get the latest Subscription that has the same subscriber_list and email as the Subscription associated with the ‘id` passed. This may or may not be the same Subscription.

}

Returns:

  • (Hash) —

    subscription: { id subscriber_list subscriber created_at updated_at ended_at ended_reason frequency source



137
138
139
 
# File 'lib/gds_api/email_alert_api.rb', line 137

def get_latest_matching_subscription(id)
  get_json("#{endpoint}/subscriptions/#{uri_encode(id)}/latest")
end

#get_subscriber_list(slug:) ⇒ Hash

Get a Subscriber List

}

Returns:

  • (Hash) —

    subscriber_list: { id title created_at updated_at document_type tags links email_document_supertype government_document_supertype subscriber_count



101
102
103
 
# File 'lib/gds_api/email_alert_api.rb', line 101

def get_subscriber_list(slug:)
  get_json("#{endpoint}/subscriber-lists/#{uri_encode(slug)}")
end

#get_subscription(id) ⇒ Hash

Get a Subscription

}

Returns:

  • (Hash) —

    subscription: { id subscriber_list subscriber created_at updated_at ended_at ended_reason frequency source



118
119
120
 
# File 'lib/gds_api/email_alert_api.rb', line 118

def get_subscription(id)
  get_json("#{endpoint}/subscriptions/#{uri_encode(id)}")
end

#get_subscriptions(id:, order: nil) ⇒ Hash

Get Subscriptions for a Subscriber

Parameters:

  • Subscriber (integer) —

    id

  • Subscription (string) —

    order - title, created_at

Returns:

  • (Hash) —

    subscriber, subscriptions



147
148
149
150
151
152
153
 
# File 'lib/gds_api/email_alert_api.rb', line 147

def get_subscriptions(id:, order: nil)
  if order
    get_json("#{endpoint}/subscribers/#{uri_encode(id)}/subscriptions?order=#{uri_encode(order)}")
  else
    get_json("#{endpoint}/subscribers/#{uri_encode(id)}/subscriptions")
  end
end

#link_subscriber_to_govuk_account(govuk_account_session:) ⇒ Hash

Mark a subscriber as “linked” to its corresponding GOV.UK Account. In practice “linking” will mean that email-alert-frontend and account-api will treat the subscriber specially (eg, only allowing address changes via the account).

Parameters:

  • govuk_account_session (string) —

    The request’s session identifier

Returns:

  • (Hash) —

    subscriber



201
202
203
204
205
206
 
# File 'lib/gds_api/email_alert_api.rb', line 201

def (govuk_account_session:)
  post_json(
    "#{endpoint}/subscribers/govuk-account/link",
    govuk_account_session: ,
  )
end

#send_subscriber_verification_email(address:, destination:) ⇒ Hash

Verify a subscriber has control of a provided email

Parameters:

  • address (string) —

    Address to send verification email to

  • destination (string) —

    Path on GOV.UK that subscriber will be emailed

Returns:

  • (Hash) —

    subscriber



226
227
228
229
230
231
232
 
# File 'lib/gds_api/email_alert_api.rb', line 226

def send_subscriber_verification_email(address:, destination:)
  post_json(
    "#{endpoint}/subscribers/auth-token",
    address: address,
    destination: destination,
  )
end

#send_subscription_verification_email(address:, frequency:, topic_id:) ⇒ Object

Verify a subscriber intends to be added to a subscription

return [Hash] subscription

Parameters:

  • address (string) —

    Address to send verification email to

  • frequency (string) —

    How often the subscriber wishes to be notified of new items

  • topic_id (string) —

    The slugs/ID for the topic being subscribed to



242
243
244
245
246
247
248
249
 
# File 'lib/gds_api/email_alert_api.rb', line 242

def send_subscription_verification_email(address:, frequency:, topic_id:)
  post_json(
    "#{endpoint}/subscriptions/auth-token",
    address: address,
    frequency: frequency,
    topic_id: topic_id,
  )
end

#subscribe(subscriber_list_id:, address:, frequency: "immediately", skip_confirmation_email: false) ⇒ Hash

Subscribe

Returns:

  • (Hash) —

    subscription_id



77
78
79
80
81
82
83
84
85
 
# File 'lib/gds_api/email_alert_api.rb', line 77

def subscribe(subscriber_list_id:, address:, frequency: "immediately", skip_confirmation_email: false)
  post_json(
    "#{endpoint}/subscriptions",
    subscriber_list_id: subscriber_list_id,
    address: address,
    frequency: frequency,
    skip_confirmation_email: skip_confirmation_email,
  )
end

#topic_matches(attributes) ⇒ Hash

Get topic matches

email_document_supertype, government_document_supertype

Parameters:

  • attributes (Hash) —

    tags, links, document_type,

Returns:

  • (Hash) —

    topics, enabled, disabled



51
52
53
54
 
# File 'lib/gds_api/email_alert_api.rb', line 51

def topic_matches(attributes)
  query_string = nested_query_string(attributes)
  get_json("#{endpoint}/topic-matches.json?#{query_string}")
end

#unsubscribe(uuid) ⇒ nil

Unsubscribe subscriber from subscription

Parameters:

  • Subscription (string) —

    uuid

Returns:

  • (nil) 


61
62
63
 
# File 'lib/gds_api/email_alert_api.rb', line 61

def unsubscribe(uuid)
  post_json("#{endpoint}/unsubscribe/#{uri_encode(uuid)}")
end

#unsubscribe_subscriber(id) ⇒ nil

Unsubscribe subscriber from everything

Parameters:

  • Subscriber (integer) —

    id

Returns:

  • (nil) 


70
71
72
 
# File 'lib/gds_api/email_alert_api.rb', line 70

def unsubscribe_subscriber(id)
  delete_json("#{endpoint}/subscribers/#{uri_encode(id)}")
end

#update_subscriber_list_details(slug:, params: {}) ⇒ Object

Update subscriber list details, such as title

Parameters:



275
276
277
278
279
280
 
# File 'lib/gds_api/email_alert_api.rb', line 275

def update_subscriber_list_details(slug:, params: {})
  patch_json(
    "#{endpoint}/subscriber-lists/#{slug}",
    params,
  )
end