Class: Courier::Resources::Notifications

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

Overview

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

Defined Under Namespace

Classes: Checks, Previews

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:



425
426
427
428
429
 
# File 'lib/courier/resources/notifications.rb', line 425

def initialize(client:)
  @client = client
  @checks = Courier::Resources::Notifications::Checks.new(client: client)
  @previews = Courier::Resources::Notifications::Previews.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

#previews ⇒ Courier::Resources::Notifications::Previews (readonly)

Returns:



14
15
16
 
# File 'lib/courier/resources/notifications.rb', line 14

def previews
  @previews
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:



135
136
137
138
139
140
141
142
 
# File 'lib/courier/resources/notifications.rb', line 135

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.

Content must place its elements inside a channel block — { "type": "channel", "channel": "email", "elements": [...] } — or the request returns 400. The template designer renders only the channel block matching the tab it draws, so content stored without one cannot be opened. An empty elements array is accepted, and the requirement applies to creation only: PUT /notifications/{id} still accepts unwrapped content. Note this endpoint takes versioned content only — the { title, body } shorthand accepted by /send is rejected here with an invalid_request_error on notification.content.version.

Parameters:

Returns:

See Also:



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/courier/resources/notifications.rb', line 47

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:



185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/courier/resources/notifications.rb', line 185

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, tags: nil, request_options: {}) ⇒ Courier::Models::NotificationListResponse

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

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.

  • tags (String) —

    Comma-delimited list of tag names. Only templates carrying all of the listed tag

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

Returns:

See Also:



111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/courier/resources/notifications.rb', line 111

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:



213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/courier/resources/notifications.rb', line 213

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:



246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/courier/resources/notifications.rb', line 246

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:



276
277
278
279
280
281
282
283
284
285
 
# File 'lib/courier/resources/notifications.rb', line 276

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:



315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/courier/resources/notifications.rb', line 315

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:



348
349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/courier/resources/notifications.rb', line 348

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:



382
383
384
385
386
387
388
389
390
391
 
# File 'lib/courier/resources/notifications.rb', line 382

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:



78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/courier/resources/notifications.rb', line 78

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:



410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/courier/resources/notifications.rb', line 410

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