Class: Courier::Resources::Notifications

Inherits:
Object
  • Object
show all
Defined in:
lib/courier/resources/notifications.rb,
lib/courier/resources/notifications/checks.rb,
sig/courier/resources/notifications.rbs,
sig/courier/resources/notifications/checks.rbs

Overview

Create, update, version, publish, and localize notification templates and their content.

Defined Under Namespace

Classes: Checks

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Notifications

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Notifications.

Parameters:



407
408
409
410
 
# File 'lib/courier/resources/notifications.rb', line 407

def initialize(client:)
  @client = client
  @checks = Courier::Resources::Notifications::Checks.new(client: client)
end

Instance Attribute Details

#checks ⇒ Courier::Resources::Notifications::Checks (readonly)

Create, update, version, publish, and localize notification templates and their content.

Returns:



11
12
13
 
# File 'lib/courier/resources/notifications.rb', line 11

def checks
  @checks
end

Instance Method Details

#archive(id, request_options: {}) ⇒ nil

Archives a notification template, preventing new sends from referencing it. The template stays retrievable for its version history.

Parameters:

  • id (String) —

    Template ID (nt_ prefix).

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)
  • request_options: (Courier::request_opts)

Returns:

  • (nil)

See Also:



117
118
119
120
121
122
123
124
 
# File 'lib/courier/resources/notifications.rb', line 117

def archive(id, params = {})
  @client.request(
    method: :delete,
    path: ["notifications/%1$s", id],
    model: NilClass,
    options: params[:request_options]
  )
end

#create(notification:, state: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {}) ⇒ Courier::Models::NotificationTemplateResponse

Some parameter documentations has been truncated, see Models::NotificationCreateParams for more details.

Create a notification template. Requires all fields in the notification object. Templates are created in draft state by default.

Parameters:

Returns:

See Also:



34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/courier/resources/notifications.rb', line 34

def create(params)
  parsed, options = Courier::NotificationCreateParams.dump_request(params)
  header_params =
    {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
  @client.request(
    method: :post,
    path: "notifications",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Courier::NotificationTemplateResponse,
    options: options
  )
end

#get_metrics(id, end_: nil, granularity: nil, lookback: nil, start: nil, request_options: {}) ⇒ Courier::Models::NotificationMetricsResponse

Some parameter documentations has been truncated, see Models::NotificationGetMetricsParams for more details.

Fetch the delivery funnel for one Notification Template as a time series — sent, delivered, opened, clicked, errors, and undeliverable — broken out per provider and channel inside each bucket. Sum the entries in a bucket for its totals; there is no bucket-level total.

Choose the window absolutely with start and end, or relatively with lookback (an ISO 8601 duration). start and end take precedence when both are supplied, and a request carrying neither defaults to lookback=P30D. The window is snapped outwards onto the granularity grid so every bucket it overlaps is returned whole, and the snapped boundaries come back as start and end — align a chart on those rather than on what was requested. Every boundary is UTC; there is no timezone support.

Every bucket in the window is returned, including the quiet ones, whose data array is empty, so a series is directly plottable with no gap filling client-side. An unknown template id returns 200 with an all-empty series rather than 404, and messages sent without a Notification Template never appear here.

Available in the US region only.

Parameters:

  • id (String) —

    The Notification Template to report on — its ID (nt_ prefix) or an alias. Must

  • end_ (Time) —

    The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied

  • granularity (Symbol, Courier::Models::NotificationGetMetricsParams::Granularity) —

    The size of each bucket in the series. Defaults to DAY. WEEK buckets start o

  • lookback (String) —

    The length of the window, counted back from now, as an ISO 8601 duration (P30D

  • start (Time) —

    The inclusive start of the window, as an ISO 8601 timestamp with an offset (`202

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/courier/resources/notifications.rb', line 167

def get_metrics(id, params = {})
  parsed, options = Courier::NotificationGetMetricsParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["notifications/%1$s/metrics", id],
    query: query.transform_keys(end_: "end"),
    model: Courier::NotificationMetricsResponse,
    options: options
  )
end

#list(cursor: nil, event_id: nil, notes: nil, request_options: {}) ⇒ Courier::Models::NotificationListResponse

Lists the workspace's notification templates. Each carries a name, tags, brand, routing, and its draft or published state.

Parameters:

  • cursor (String, nil) —

    Opaque pagination cursor from a previous response. Omit for the first page.

  • event_id (String) —

    Filter to templates linked to this event map ID.

  • notes (Boolean, nil) —

    Include template notes in the response. Only applies to legacy templates.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/courier/resources/notifications.rb', line 93

def list(params = {})
  parsed, options = Courier::NotificationListParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "notifications",
    query: query,
    model: Courier::Models::NotificationListResponse,
    options: options
  )
end

#list_versions(id, cursor: nil, limit: nil, request_options: {}) ⇒ Courier::Models::NotificationTemplateVersionListResponse

Returns a notification template's published versions, most recent first, for comparison or rollback. Paged.

Parameters:

  • id (String) —

    Template ID (nt_ prefix).

  • cursor (String) —

    Opaque pagination cursor from a previous response. Omit for the first page.

  • limit (Integer) —

    Maximum number of versions to return per page. Default 10, max 10.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/courier/resources/notifications.rb', line 195

def list_versions(id, params = {})
  parsed, options = Courier::NotificationListVersionsParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["notifications/%1$s/versions", id],
    query: query,
    model: Courier::NotificationTemplateVersionListResponse,
    options: options
  )
end

#publish(id, version: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::NotificationPublishParams for more details.

Publish a notification template. Publishes the current draft by default. Pass a version in the request body to publish a specific historical version.

Parameters:

  • id (String) —

    Path param: Template ID (nt_ prefix).

  • version (String) —

    Body param: Historical version to publish (e.g. "v001"). Omit to publish the cur

  • idempotency_key (String) —

    Header param: A unique key that makes this request idempotent. If Courier receiv

  • x_idempotency_expiration (String) —

    Header param: How long the idempotency key remains valid, as a Unix epoch timest

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/courier/resources/notifications.rb', line 228

def publish(id, params = {})
  parsed, options = Courier::NotificationPublishParams.dump_request(params)
  header_params =
    {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
  @client.request(
    method: :post,
    path: ["notifications/%1$s/publish", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: NilClass,
    options: options
  )
end

#put_content(id, content:, state: nil, request_options: {}) ⇒ Courier::Models::NotificationContentMutationResponse

Replaces all Elemental content in a template, overwriting every existing element. Supported for V2 templates only, not V1 blocks and channels.

Parameters:

Returns:

See Also:



258
259
260
261
262
263
264
265
266
267
 
# File 'lib/courier/resources/notifications.rb', line 258

def put_content(id, params)
  parsed, options = Courier::NotificationPutContentParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["notifications/%1$s/content", id],
    body: parsed,
    model: Courier::NotificationContentMutationResponse,
    options: options
  )
end

#put_element(element_id, id:, type:, channels: nil, data: nil, if_: nil, loop_: nil, ref: nil, state: nil, request_options: {}) ⇒ Courier::Models::NotificationContentMutationResponse

Replaces one Elemental element in a template, addressed by its element id. Supported for V2 templates only, not V1 blocks and channels.

Parameters:

  • element_id (String) —

    Path param: Element ID within the template.

  • id (String) —

    Path param: Notification template ID (nt_ prefix).

  • type (String) —

    Body param: Element type (text, meta, action, image, etc.).

  • channels (Array<String>) —

    Body param

  • data (Hash{Symbol=>Object}) —

    Body param

  • if_ (String) —

    Body param

  • loop_ (String) —

    Body param

  • ref (String) —

    Body param

  • state (Symbol, Courier::Models::NotificationTemplateState) —

    Body param: Template state. Defaults to DRAFT.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/courier/resources/notifications.rb', line 297

def put_element(element_id, params)
  parsed, options = Courier::NotificationPutElementParams.dump_request(params)
  id =
    parsed.delete(:id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :put,
    path: ["notifications/%1$s/elements/%2$s", id, element_id],
    body: parsed,
    model: Courier::NotificationContentMutationResponse,
    options: options
  )
end

#put_locale(locale_id, id:, elements:, state: nil, request_options: {}) ⇒ Courier::Models::NotificationContentMutationResponse

Sets locale-specific content overrides for a template. Each override must reference an element that already exists in the default content.

Parameters:

Returns:

See Also:



330
331
332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/courier/resources/notifications.rb', line 330

def put_locale(locale_id, params)
  parsed, options = Courier::NotificationPutLocaleParams.dump_request(params)
  id =
    parsed.delete(:id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :put,
    path: ["notifications/%1$s/locales/%2$s", id, locale_id],
    body: parsed,
    model: Courier::NotificationContentMutationResponse,
    options: options
  )
end

#replace(id, notification:, state: nil, request_options: {}) ⇒ Courier::Models::NotificationTemplateResponse

Some parameter documentations has been truncated, see Models::NotificationReplaceParams for more details.

Replaces a notification template in full, so send every field rather than only the ones you want changed. Publish separately to make it live.

Parameters:

Returns:

See Also:



364
365
366
367
368
369
370
371
372
373
 
# File 'lib/courier/resources/notifications.rb', line 364

def replace(id, params)
  parsed, options = Courier::NotificationReplaceParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["notifications/%1$s", id],
    body: parsed,
    model: Courier::NotificationTemplateResponse,
    options: options
  )
end

#retrieve(id, version: nil, request_options: {}) ⇒ Courier::Models::NotificationTemplateResponse

Some parameter documentations has been truncated, see Models::NotificationRetrieveParams for more details.

Retrieve a notification template by ID. Returns the published version by default. Pass version=draft to retrieve an unpublished template.

Parameters:

  • id (String) —

    Template ID (nt_ prefix).

  • version (String) —

    Version to retrieve. One of "draft", "published", or a version string like "v001

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/courier/resources/notifications.rb', line 65

def retrieve(id, params = {})
  parsed, options = Courier::NotificationRetrieveParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["notifications/%1$s", id],
    query: query,
    model: Courier::NotificationTemplateResponse,
    options: options
  )
end

#retrieve_content(id, version: nil, request_options: {}) ⇒ Courier::Models::NotificationContentGetResponse, Courier::Models::NotificationGetContent

Some parameter documentations has been truncated, see Models::NotificationRetrieveContentParams for more details.

Returns a template's content and checksum. V2 templates return Elemental elements, while V1 templates return blocks and channels instead.

Parameters:

  • id (String) —

    Notification template ID (nt_ prefix).

  • version (String) —

    Accepts draft, published, or a version string (e.g., v001). Defaults to `p

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



392
393
394
395
396
397
398
399
400
401
402
 
# File 'lib/courier/resources/notifications.rb', line 392

def retrieve_content(id, params = {})
  parsed, options = Courier::NotificationRetrieveContentParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["notifications/%1$s/content", id],
    query: query,
    model: Courier::Models::NotificationRetrieveContentResponse,
    options: options
  )
end