Class: GdsApi::EmailAlertApi

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

Overview

Adapter for the Email Alert API

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.

  • (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

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