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



191
192
193
194
195
196
 
# File 'lib/gds_api/email_alert_api.rb', line 191

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

#bulk_migrate(from_slug:, to_slug:) ⇒ Object

Migrate all users from one existing subscriber list to another existing subscriber list

Parameters:

  • to_slug (string) —

    Identifier for the successor subscription list

  • from_slug (string) —

    Identifier for the source subscription list



281
282
283
284
285
286
287
 
# File 'lib/gds_api/email_alert_api.rb', line 281

def bulk_migrate(from_slug:, to_slug:)
  post_json(
    "#{endpoint}/subscriber-lists/bulk-migrate",
    from_slug:,
    to_slug:,
  )
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.



263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/gds_api/email_alert_api.rb', line 263

def bulk_unsubscribe(slug:, govuk_request_id: nil, body: nil, sender_message_id: nil)
  post_json(
    "#{endpoint}/subscriber-lists/#{slug}/bulk-unsubscribe",
    {
      body:,
      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



166
167
168
169
170
171
 
# File 'lib/gds_api/email_alert_api.rb', line 166

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

#change_subscription(id:, frequency:) ⇒ Hash

Patch a Subscription

Parameters:

  • Subscription (string) —

    id

  • Subscription (string) —

    frequency

Returns:

  • (Hash) —

    subscription



179
180
181
182
183
184
 
# File 'lib/gds_api/email_alert_api.rb', line 179

def change_subscription(id:, frequency:)
  patch_json(
    "#{endpoint}/subscriptions/#{uri_encode(id)}",
    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

#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) && (attributes["tags"])
    message = "Invalid attributes provided. Valid attributes are content_id only, tags only, links only, content_id AND links, or none."
    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



218
219
220
221
222
 
# File 'lib/gds_api/email_alert_api.rb', line 218

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



142
143
144
 
# File 'lib/gds_api/email_alert_api.rb', line 142

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



93
94
95
 
# File 'lib/gds_api/email_alert_api.rb', line 93

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

#get_subscriber_list_metrics(path:) ⇒ Hash

Get a Subscriber List

}

Parameters:

  • path (path) —

    of page for subscriber list

Returns:

  • (Hash) —

    { subscriber_list_count all_notify_count



106
107
108
 
# File 'lib/gds_api/email_alert_api.rb', line 106

def get_subscriber_list_metrics(path:)
  get_json("#{endpoint}/subscriber-lists/metrics#{path}")
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



123
124
125
 
# File 'lib/gds_api/email_alert_api.rb', line 123

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



152
153
154
155
156
157
158
 
# File 'lib/gds_api/email_alert_api.rb', line 152

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



206
207
208
209
210
211
 
# File 'lib/gds_api/email_alert_api.rb', line 206

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



231
232
233
234
235
236
237
 
# File 'lib/gds_api/email_alert_api.rb', line 231

def send_subscriber_verification_email(address:, destination:)
  post_json(
    "#{endpoint}/subscribers/auth-token",
    address:,
    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



247
248
249
250
251
252
253
254
 
# File 'lib/gds_api/email_alert_api.rb', line 247

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

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

Subscribe

Returns:

  • (Hash) —

    subscription_id



69
70
71
72
73
74
75
76
77
 
# File 'lib/gds_api/email_alert_api.rb', line 69

def subscribe(subscriber_list_id:, address:, frequency: "immediately", skip_confirmation_email: false)
  post_json(
    "#{endpoint}/subscriptions",
    subscriber_list_id:,
    address:,
    frequency:,
    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



43
44
45
46
 
# File 'lib/gds_api/email_alert_api.rb', line 43

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) 


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

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) 


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

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:



293
294
295
296
297
298
 
# File 'lib/gds_api/email_alert_api.rb', line 293

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