trycourier 6.1.0 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62f640ccc5d992cd807b750192ee8ca02b3ffe5fa09537eeadf67ba086c518b3
-  data.tar.gz: bd638a13b9a78b54e849e76a30614bed55afbcb6e7fb7a1a2edf60a74cb1531b
+  metadata.gz: 0f0b22ca9267f965731c89199aa8d49077c5ac53f12c307946893c67a9ee7896
+  data.tar.gz: abeea8195ccb031cebe6a83096665851ee7d6bae0e2743e2d7a3504af35b8f47
 SHA512:
-  metadata.gz: ed8c416e8431f1a50aa7fff01b939ba42b03acabe3a42a5a9f14da078f9dcf11bfd8cfe6cb88f642d48444aa0131c3eb9a9164fdbd6fec8a6d80d07c2f360403
-  data.tar.gz: 971c6a9a71bfdbc8faec0796d2b591d3635e55aece1ab1c208c6f68f3943a5fb39214c8a5944815b1f70f6e9912b8c77d8db2971d836116c543660a0951ef4a2
+  metadata.gz: 6c81dbe75df19bf95658f341e62e7475db0007be7ead3a8f822e3e8ce9a8c7424dcaefe76ee629c47bc798211e49e574a81d55b62426fd46a0d022ec61122fa3
+  data.tar.gz: 14dfa346c595b581a2ebbe8467e5452af68d04a64638b7347139287f79e05417394ae5ae5508634e209d2618bd821b00b688ecdc1320c6146e6e5587599a4e28

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [6.2.0](https://github.com/trycourier/courier-ruby/compare/v6.1.0...v6.2.0) (2026-08-26)
+
+
+### Features
+
+* **api:** document the template send metrics endpoint ([#134](https://github.com/trycourier/courier-ruby/issues/134)) ([cd882b5](https://github.com/trycourier/courier-ruby/commit/cd882b5a4e1b1dee40c24fd2bec65f07ed10db8a))
+
 ## [6.1.0](https://github.com/trycourier/courier-ruby/compare/v6.0.0...v6.1.0) (2026-08-19)
 
 

data/README.md

@@ -9,7 +9,7 @@ Add the gem to your `Gemfile`:
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "trycourier", "~> 6.1.0"
+gem "trycourier", "~> 6.2.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/courier/models/notification_get_metrics_params.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Notifications#get_metrics
+    class NotificationGetMetricsParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute end_
+      #   The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+      #   together with `start`. An `end` in the future is accepted and not clamped — the
+      #   trailing buckets come back empty.
+      #
+      #   @return [Time, nil]
+      optional :end_, Time
+
+      # @!attribute granularity
+      #   The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+      #   on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+      #   7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+      #   coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+      #   1000-bucket limit on a single response.
+      #
+      #   @return [Symbol, Courier::Models::NotificationGetMetricsParams::Granularity, nil]
+      optional :granularity, enum: -> { Courier::NotificationGetMetricsParams::Granularity }
+
+      # @!attribute lookback
+      #   The length of the window, counted back from now, as an ISO 8601 duration
+      #   (`P30D`, `P12W`, `PT12H`). Defaults to `P30D`, and is ignored when `start` and
+      #   `end` are supplied. A malformed or non-positive duration returns `400`.
+      #
+      #   @return [String, nil]
+      optional :lookback, String
+
+      # @!attribute start
+      #   The inclusive start of the window, as an ISO 8601 timestamp with an offset
+      #   (`2026-04-01T00:00:00Z`). Must be supplied together with `end` and be earlier
+      #   than it; either one alone returns `400`.
+      #
+      #   @return [Time, nil]
+      optional :start, Time
+
+      # @!method initialize(id:, end_: nil, granularity: nil, lookback: nil, start: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Courier::Models::NotificationGetMetricsParams} for more details.
+      #
+      #   @param id [String]
+      #
+      #   @param end_ [Time] The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+      #
+      #   @param granularity [Symbol, Courier::Models::NotificationGetMetricsParams::Granularity] The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start o
+      #
+      #   @param lookback [String] The length of the window, counted back from now, as an ISO 8601 duration (`P30D`
+      #
+      #   @param start [Time] The inclusive start of the window, as an ISO 8601 timestamp with an offset (`202
+      #
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+
+      # The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+      # on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+      # 7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+      # coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+      # 1000-bucket limit on a single response.
+      module Granularity
+        extend Courier::Internal::Type::Enum
+
+        HOUR = :HOUR
+        DAY = :DAY
+        WEEK = :WEEK
+        MONTH = :MONTH
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/courier/models/notification_metrics_response.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Notifications#get_metrics
+    class NotificationMetricsResponse < Courier::Internal::Type::BaseModel
+      # @!attribute end_
+      #   End of the window actually queried, ceiled onto the granularity grid.
+      #   Second-precision UTC.
+      #
+      #   @return [Time]
+      required :end_, Time, api_name: :end
+
+      # @!attribute granularity
+      #   Bucket size the series was built at.
+      #
+      #   @return [Symbol, Courier::Models::NotificationMetricsResponse::Granularity]
+      required :granularity, enum: -> { Courier::NotificationMetricsResponse::Granularity }
+
+      # @!attribute notification_id
+      #   The template the series describes, echoed from the request.
+      #
+      #   @return [String]
+      required :notification_id, String, api_name: :notificationId
+
+      # @!attribute series
+      #   One entry per bucket between `start` and `end`, oldest first, including buckets
+      #   with no activity.
+      #
+      #   @return [Array<Courier::Models::NotificationMetricsResponse::Series>]
+      required :series, -> { Courier::Internal::Type::ArrayOf[Courier::NotificationMetricsResponse::Series] }
+
+      # @!attribute start
+      #   Inclusive start of the window actually queried, floored onto the granularity
+      #   grid. Second-precision UTC.
+      #
+      #   @return [Time]
+      required :start, Time
+
+      # @!method initialize(end_:, granularity:, notification_id:, series:, start:)
+      #   Some parameter documentations has been truncated, see
+      #   {Courier::Models::NotificationMetricsResponse} for more details.
+      #
+      #   @param end_ [Time] End of the window actually queried, ceiled onto the granularity grid. Second-pre
+      #
+      #   @param granularity [Symbol, Courier::Models::NotificationMetricsResponse::Granularity] Bucket size the series was built at.
+      #
+      #   @param notification_id [String] The template the series describes, echoed from the request.
+      #
+      #   @param series [Array<Courier::Models::NotificationMetricsResponse::Series>] One entry per bucket between `start` and `end`, oldest first, including buckets
+      #
+      #   @param start [Time] Inclusive start of the window actually queried, floored onto the granularity gri
+
+      # Bucket size the series was built at.
+      #
+      # @see Courier::Models::NotificationMetricsResponse#granularity
+      module Granularity
+        extend Courier::Internal::Type::Enum
+
+        HOUR = :HOUR
+        DAY = :DAY
+        WEEK = :WEEK
+        MONTH = :MONTH
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      class Series < Courier::Internal::Type::BaseModel
+        # @!attribute data
+        #   One entry per provider and channel that handled a message in this bucket. Empty
+        #   when nothing was sent.
+        #
+        #   @return [Array<Courier::Models::NotificationMetricsResponse::Series::Data>]
+        required :data,
+                 -> { Courier::Internal::Type::ArrayOf[Courier::NotificationMetricsResponse::Series::Data] }
+
+        # @!attribute period
+        #   Start of the bucket, second-precision UTC.
+        #
+        #   @return [Time]
+        required :period, Time
+
+        # @!method initialize(data:, period:)
+        #   Some parameter documentations has been truncated, see
+        #   {Courier::Models::NotificationMetricsResponse::Series} for more details.
+        #
+        #   @param data [Array<Courier::Models::NotificationMetricsResponse::Series::Data>] One entry per provider and channel that handled a message in this bucket. Empty
+        #
+        #   @param period [Time] Start of the bucket, second-precision UTC.
+
+        class Data < Courier::Internal::Type::BaseModel
+          # @!attribute channel
+          #   Channel the provider delivered on, e.g. `email`.
+          #
+          #   @return [String]
+          required :channel, String
+
+          # @!attribute clicked
+          #   Messages with at least one tracked link click.
+          #
+          #   @return [Integer]
+          required :clicked, Integer
+
+          # @!attribute delivered
+          #   Messages the provider confirmed as delivered.
+          #
+          #   @return [Integer]
+          required :delivered, Integer
+
+          # @!attribute errors
+          #   Messages the provider rejected or failed on, including ones a later provider
+          #   then delivered.
+          #
+          #   @return [Integer]
+          required :errors, Integer
+
+          # @!attribute opened
+          #   Messages opened at least once. Always `0` on channels with no open tracking.
+          #
+          #   @return [Integer]
+          required :opened, Integer
+
+          # @!attribute provider
+          #   Provider that handled the messages, e.g. `sendgrid`.
+          #
+          #   @return [String]
+          required :provider, String
+
+          # @!attribute sent
+          #   Messages handed to the provider.
+          #
+          #   @return [Integer]
+          required :sent, Integer
+
+          # @!attribute undeliverable
+          #   Messages Courier could not deliver on any provider for the channel.
+          #
+          #   @return [Integer]
+          required :undeliverable, Integer
+
+          # @!method initialize(channel:, clicked:, delivered:, errors:, opened:, provider:, sent:, undeliverable:)
+          #   Some parameter documentations has been truncated, see
+          #   {Courier::Models::NotificationMetricsResponse::Series::Data} for more details.
+          #
+          #   @param channel [String] Channel the provider delivered on, e.g. `email`.
+          #
+          #   @param clicked [Integer] Messages with at least one tracked link click.
+          #
+          #   @param delivered [Integer] Messages the provider confirmed as delivered.
+          #
+          #   @param errors [Integer] Messages the provider rejected or failed on, including ones a later provider the
+          #
+          #   @param opened [Integer] Messages opened at least once. Always `0` on channels with no open tracking.
+          #
+          #   @param provider [String] Provider that handled the messages, e.g. `sendgrid`.
+          #
+          #   @param sent [Integer] Messages handed to the provider.
+          #
+          #   @param undeliverable [Integer] Messages Courier could not deliver on any provider for the channel.
+        end
+      end
+    end
+  end
+end

data/lib/courier/models.rb

@@ -422,12 +422,16 @@ module Courier
 
   NotificationGetContent = Courier::Models::NotificationGetContent
 
+  NotificationGetMetricsParams = Courier::Models::NotificationGetMetricsParams
+
   NotificationListParams = Courier::Models::NotificationListParams
 
   NotificationListVersionsParams = Courier::Models::NotificationListVersionsParams
 
   NotificationLocalePutRequest = Courier::Models::NotificationLocalePutRequest
 
+  NotificationMetricsResponse = Courier::Models::NotificationMetricsResponse
+
   NotificationPreferenceDetails = Courier::Models::NotificationPreferenceDetails
 
   NotificationPublishParams = Courier::Models::NotificationPublishParams

data/lib/courier/resources/notifications.rb

@@ -123,6 +123,59 @@ module Courier
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Courier::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.
+      #
+      # @overload get_metrics(id, end_: nil, granularity: nil, lookback: nil, start: nil, request_options: {})
+      #
+      # @param id [String] The Notification Template to report on — its ID (`nt_` prefix) or an alias. Must
+      #
+      # @param end_ [Time] The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+      #
+      # @param granularity [Symbol, Courier::Models::NotificationGetMetricsParams::Granularity] The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start o
+      #
+      # @param lookback [String] The length of the window, counted back from now, as an ISO 8601 duration (`P30D`
+      #
+      # @param start [Time] The inclusive start of the window, as an ISO 8601 timestamp with an offset (`202
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::NotificationMetricsResponse]
+      #
+      # @see Courier::Models::NotificationGetMetricsParams
+      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
+
       # Returns a notification template's published versions, most recent first, for
       # comparison or rollback. Paged.
       #

data/lib/courier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Courier
-  VERSION = "6.1.0"
+  VERSION = "6.2.0"
 end

data/lib/courier.rb

@@ -298,9 +298,11 @@ require_relative "courier/models/notification_content_get_response"
 require_relative "courier/models/notification_content_mutation_response"
 require_relative "courier/models/notification_create_params"
 require_relative "courier/models/notification_get_content"
+require_relative "courier/models/notification_get_metrics_params"
 require_relative "courier/models/notification_list_params"
 require_relative "courier/models/notification_list_response"
 require_relative "courier/models/notification_list_versions_params"
+require_relative "courier/models/notification_metrics_response"
 require_relative "courier/models/notification_preference_details"
 require_relative "courier/models/notification_publish_params"
 require_relative "courier/models/notification_put_content_params"

data/rbi/courier/models/notification_get_metrics_params.rbi

@@ -0,0 +1,167 @@
+# typed: strong
+
+module Courier
+  module Models
+    class NotificationGetMetricsParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Courier::NotificationGetMetricsParams,
+            Courier::Internal::AnyHash
+          )
+        end
+
+      sig { returns(String) }
+      attr_accessor :id
+
+      # The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+      # together with `start`. An `end` in the future is accepted and not clamped — the
+      # trailing buckets come back empty.
+      sig { returns(T.nilable(Time)) }
+      attr_reader :end_
+
+      sig { params(end_: Time).void }
+      attr_writer :end_
+
+      # The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+      # on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+      # 7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+      # coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+      # 1000-bucket limit on a single response.
+      sig do
+        returns(
+          T.nilable(
+            Courier::NotificationGetMetricsParams::Granularity::OrSymbol
+          )
+        )
+      end
+      attr_reader :granularity
+
+      sig do
+        params(
+          granularity:
+            Courier::NotificationGetMetricsParams::Granularity::OrSymbol
+        ).void
+      end
+      attr_writer :granularity
+
+      # The length of the window, counted back from now, as an ISO 8601 duration
+      # (`P30D`, `P12W`, `PT12H`). Defaults to `P30D`, and is ignored when `start` and
+      # `end` are supplied. A malformed or non-positive duration returns `400`.
+      sig { returns(T.nilable(String)) }
+      attr_reader :lookback
+
+      sig { params(lookback: String).void }
+      attr_writer :lookback
+
+      # The inclusive start of the window, as an ISO 8601 timestamp with an offset
+      # (`2026-04-01T00:00:00Z`). Must be supplied together with `end` and be earlier
+      # than it; either one alone returns `400`.
+      sig { returns(T.nilable(Time)) }
+      attr_reader :start
+
+      sig { params(start: Time).void }
+      attr_writer :start
+
+      sig do
+        params(
+          id: String,
+          end_: Time,
+          granularity:
+            Courier::NotificationGetMetricsParams::Granularity::OrSymbol,
+          lookback: String,
+          start: Time,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        id:,
+        # The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+        # together with `start`. An `end` in the future is accepted and not clamped — the
+        # trailing buckets come back empty.
+        end_: nil,
+        # The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+        # on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+        # 7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+        # coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+        # 1000-bucket limit on a single response.
+        granularity: nil,
+        # The length of the window, counted back from now, as an ISO 8601 duration
+        # (`P30D`, `P12W`, `PT12H`). Defaults to `P30D`, and is ignored when `start` and
+        # `end` are supplied. A malformed or non-positive duration returns `400`.
+        lookback: nil,
+        # The inclusive start of the window, as an ISO 8601 timestamp with an offset
+        # (`2026-04-01T00:00:00Z`). Must be supplied together with `end` and be earlier
+        # than it; either one alone returns `400`.
+        start: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: String,
+            end_: Time,
+            granularity:
+              Courier::NotificationGetMetricsParams::Granularity::OrSymbol,
+            lookback: String,
+            start: Time,
+            request_options: Courier::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+      # on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+      # 7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+      # coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+      # 1000-bucket limit on a single response.
+      module Granularity
+        extend Courier::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, Courier::NotificationGetMetricsParams::Granularity)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        HOUR =
+          T.let(
+            :HOUR,
+            Courier::NotificationGetMetricsParams::Granularity::TaggedSymbol
+          )
+        DAY =
+          T.let(
+            :DAY,
+            Courier::NotificationGetMetricsParams::Granularity::TaggedSymbol
+          )
+        WEEK =
+          T.let(
+            :WEEK,
+            Courier::NotificationGetMetricsParams::Granularity::TaggedSymbol
+          )
+        MONTH =
+          T.let(
+            :MONTH,
+            Courier::NotificationGetMetricsParams::Granularity::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Courier::NotificationGetMetricsParams::Granularity::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/notification_metrics_response.rbi

@@ -0,0 +1,269 @@
+# typed: strong
+
+module Courier
+  module Models
+    class NotificationMetricsResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Courier::NotificationMetricsResponse,
+            Courier::Internal::AnyHash
+          )
+        end
+
+      # End of the window actually queried, ceiled onto the granularity grid.
+      # Second-precision UTC.
+      sig { returns(Time) }
+      attr_accessor :end_
+
+      # Bucket size the series was built at.
+      sig do
+        returns(Courier::NotificationMetricsResponse::Granularity::TaggedSymbol)
+      end
+      attr_accessor :granularity
+
+      # The template the series describes, echoed from the request.
+      sig { returns(String) }
+      attr_accessor :notification_id
+
+      # One entry per bucket between `start` and `end`, oldest first, including buckets
+      # with no activity.
+      sig { returns(T::Array[Courier::NotificationMetricsResponse::Series]) }
+      attr_accessor :series
+
+      # Inclusive start of the window actually queried, floored onto the granularity
+      # grid. Second-precision UTC.
+      sig { returns(Time) }
+      attr_accessor :start
+
+      sig do
+        params(
+          end_: Time,
+          granularity:
+            Courier::NotificationMetricsResponse::Granularity::OrSymbol,
+          notification_id: String,
+          series:
+            T::Array[Courier::NotificationMetricsResponse::Series::OrHash],
+          start: Time
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # End of the window actually queried, ceiled onto the granularity grid.
+        # Second-precision UTC.
+        end_:,
+        # Bucket size the series was built at.
+        granularity:,
+        # The template the series describes, echoed from the request.
+        notification_id:,
+        # One entry per bucket between `start` and `end`, oldest first, including buckets
+        # with no activity.
+        series:,
+        # Inclusive start of the window actually queried, floored onto the granularity
+        # grid. Second-precision UTC.
+        start:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            end_: Time,
+            granularity:
+              Courier::NotificationMetricsResponse::Granularity::TaggedSymbol,
+            notification_id: String,
+            series: T::Array[Courier::NotificationMetricsResponse::Series],
+            start: Time
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Bucket size the series was built at.
+      module Granularity
+        extend Courier::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, Courier::NotificationMetricsResponse::Granularity)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        HOUR =
+          T.let(
+            :HOUR,
+            Courier::NotificationMetricsResponse::Granularity::TaggedSymbol
+          )
+        DAY =
+          T.let(
+            :DAY,
+            Courier::NotificationMetricsResponse::Granularity::TaggedSymbol
+          )
+        WEEK =
+          T.let(
+            :WEEK,
+            Courier::NotificationMetricsResponse::Granularity::TaggedSymbol
+          )
+        MONTH =
+          T.let(
+            :MONTH,
+            Courier::NotificationMetricsResponse::Granularity::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Courier::NotificationMetricsResponse::Granularity::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+
+      class Series < Courier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::NotificationMetricsResponse::Series,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        # One entry per provider and channel that handled a message in this bucket. Empty
+        # when nothing was sent.
+        sig do
+          returns(T::Array[Courier::NotificationMetricsResponse::Series::Data])
+        end
+        attr_accessor :data
+
+        # Start of the bucket, second-precision UTC.
+        sig { returns(Time) }
+        attr_accessor :period
+
+        sig do
+          params(
+            data:
+              T::Array[
+                Courier::NotificationMetricsResponse::Series::Data::OrHash
+              ],
+            period: Time
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # One entry per provider and channel that handled a message in this bucket. Empty
+          # when nothing was sent.
+          data:,
+          # Start of the bucket, second-precision UTC.
+          period:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              data:
+                T::Array[Courier::NotificationMetricsResponse::Series::Data],
+              period: Time
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Data < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::NotificationMetricsResponse::Series::Data,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          # Channel the provider delivered on, e.g. `email`.
+          sig { returns(String) }
+          attr_accessor :channel
+
+          # Messages with at least one tracked link click.
+          sig { returns(Integer) }
+          attr_accessor :clicked
+
+          # Messages the provider confirmed as delivered.
+          sig { returns(Integer) }
+          attr_accessor :delivered
+
+          # Messages the provider rejected or failed on, including ones a later provider
+          # then delivered.
+          sig { returns(Integer) }
+          attr_accessor :errors
+
+          # Messages opened at least once. Always `0` on channels with no open tracking.
+          sig { returns(Integer) }
+          attr_accessor :opened
+
+          # Provider that handled the messages, e.g. `sendgrid`.
+          sig { returns(String) }
+          attr_accessor :provider
+
+          # Messages handed to the provider.
+          sig { returns(Integer) }
+          attr_accessor :sent
+
+          # Messages Courier could not deliver on any provider for the channel.
+          sig { returns(Integer) }
+          attr_accessor :undeliverable
+
+          sig do
+            params(
+              channel: String,
+              clicked: Integer,
+              delivered: Integer,
+              errors: Integer,
+              opened: Integer,
+              provider: String,
+              sent: Integer,
+              undeliverable: Integer
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Channel the provider delivered on, e.g. `email`.
+            channel:,
+            # Messages with at least one tracked link click.
+            clicked:,
+            # Messages the provider confirmed as delivered.
+            delivered:,
+            # Messages the provider rejected or failed on, including ones a later provider
+            # then delivered.
+            errors:,
+            # Messages opened at least once. Always `0` on channels with no open tracking.
+            opened:,
+            # Provider that handled the messages, e.g. `sendgrid`.
+            provider:,
+            # Messages handed to the provider.
+            sent:,
+            # Messages Courier could not deliver on any provider for the channel.
+            undeliverable:
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                channel: String,
+                clicked: Integer,
+                delivered: Integer,
+                errors: Integer,
+                opened: Integer,
+                provider: String,
+                sent: Integer,
+                undeliverable: Integer
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models.rbi

@@ -392,6 +392,8 @@ module Courier
 
   NotificationGetContent = Courier::Models::NotificationGetContent
 
+  NotificationGetMetricsParams = Courier::Models::NotificationGetMetricsParams
+
   NotificationListParams = Courier::Models::NotificationListParams
 
   NotificationListVersionsParams =
@@ -399,6 +401,8 @@ module Courier
 
   NotificationLocalePutRequest = Courier::Models::NotificationLocalePutRequest
 
+  NotificationMetricsResponse = Courier::Models::NotificationMetricsResponse
+
   NotificationPreferenceDetails = Courier::Models::NotificationPreferenceDetails
 
   NotificationPublishParams = Courier::Models::NotificationPublishParams

data/rbi/courier/resources/notifications.rbi

@@ -99,6 +99,63 @@ module Courier
       )
       end
 
+      # 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.
+      sig do
+        params(
+          id: String,
+          end_: Time,
+          granularity:
+            Courier::NotificationGetMetricsParams::Granularity::OrSymbol,
+          lookback: String,
+          start: Time,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::NotificationMetricsResponse)
+      end
+      def get_metrics(
+        # The Notification Template to report on — its ID (`nt_` prefix) or an alias. Must
+        # not contain commas or whitespace.
+        id,
+        # The end of the window, as an ISO 8601 timestamp with an offset. Must be supplied
+        # together with `start`. An `end` in the future is accepted and not clamped — the
+        # trailing buckets come back empty.
+        end_: nil,
+        # The size of each bucket in the series. Defaults to `DAY`. `WEEK` buckets start
+        # on Sunday. A fine granularity caps the window it can cover: `HOUR` spans at most
+        # 7 days and `DAY` at most 90 days, and a wider window returns `400` — request a
+        # coarser granularity instead. `WEEK` and `MONTH` are uncapped, subject to the
+        # 1000-bucket limit on a single response.
+        granularity: nil,
+        # The length of the window, counted back from now, as an ISO 8601 duration
+        # (`P30D`, `P12W`, `PT12H`). Defaults to `P30D`, and is ignored when `start` and
+        # `end` are supplied. A malformed or non-positive duration returns `400`.
+        lookback: nil,
+        # The inclusive start of the window, as an ISO 8601 timestamp with an offset
+        # (`2026-04-01T00:00:00Z`). Must be supplied together with `end` and be earlier
+        # than it; either one alone returns `400`.
+        start: nil,
+        request_options: {}
+      )
+      end
+
       # Returns a notification template's published versions, most recent first, for
       # comparison or rollback. Paged.
       sig do

data/sig/courier/models/notification_get_metrics_params.rbs

@@ -0,0 +1,69 @@
+module Courier
+  module Models
+    type notification_get_metrics_params =
+      {
+        id: String,
+        end_: Time,
+        granularity: Courier::Models::NotificationGetMetricsParams::granularity,
+        lookback: String,
+        start: Time
+      }
+      & Courier::Internal::Type::request_parameters
+
+    class NotificationGetMetricsParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      attr_accessor id: String
+
+      attr_reader end_: Time?
+
+      def end_=: (Time) -> Time
+
+      attr_reader granularity: Courier::Models::NotificationGetMetricsParams::granularity?
+
+      def granularity=: (
+        Courier::Models::NotificationGetMetricsParams::granularity
+      ) -> Courier::Models::NotificationGetMetricsParams::granularity
+
+      attr_reader lookback: String?
+
+      def lookback=: (String) -> String
+
+      attr_reader start: Time?
+
+      def start=: (Time) -> Time
+
+      def initialize: (
+        id: String,
+        ?end_: Time,
+        ?granularity: Courier::Models::NotificationGetMetricsParams::granularity,
+        ?lookback: String,
+        ?start: Time,
+        ?request_options: Courier::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        id: String,
+        end_: Time,
+        granularity: Courier::Models::NotificationGetMetricsParams::granularity,
+        lookback: String,
+        start: Time,
+        request_options: Courier::RequestOptions
+      }
+
+      type granularity = :HOUR | :DAY | :WEEK | :MONTH
+
+      module Granularity
+        extend Courier::Internal::Type::Enum
+
+        HOUR: :HOUR
+        DAY: :DAY
+        WEEK: :WEEK
+        MONTH: :MONTH
+
+        def self?.values: -> ::Array[Courier::Models::NotificationGetMetricsParams::granularity]
+      end
+    end
+  end
+end

data/sig/courier/models/notification_metrics_response.rbs

@@ -0,0 +1,127 @@
+module Courier
+  module Models
+    type notification_metrics_response =
+      {
+        end_: Time,
+        granularity: Courier::Models::NotificationMetricsResponse::granularity,
+        notification_id: String,
+        series: ::Array[Courier::NotificationMetricsResponse::Series],
+        start: Time
+      }
+
+    class NotificationMetricsResponse < Courier::Internal::Type::BaseModel
+      attr_accessor end_: Time
+
+      attr_accessor granularity: Courier::Models::NotificationMetricsResponse::granularity
+
+      attr_accessor notification_id: String
+
+      attr_accessor series: ::Array[Courier::NotificationMetricsResponse::Series]
+
+      attr_accessor start: Time
+
+      def initialize: (
+        end_: Time,
+        granularity: Courier::Models::NotificationMetricsResponse::granularity,
+        notification_id: String,
+        series: ::Array[Courier::NotificationMetricsResponse::Series],
+        start: Time
+      ) -> void
+
+      def to_hash: -> {
+        end_: Time,
+        granularity: Courier::Models::NotificationMetricsResponse::granularity,
+        notification_id: String,
+        series: ::Array[Courier::NotificationMetricsResponse::Series],
+        start: Time
+      }
+
+      type granularity = :HOUR | :DAY | :WEEK | :MONTH
+
+      module Granularity
+        extend Courier::Internal::Type::Enum
+
+        HOUR: :HOUR
+        DAY: :DAY
+        WEEK: :WEEK
+        MONTH: :MONTH
+
+        def self?.values: -> ::Array[Courier::Models::NotificationMetricsResponse::granularity]
+      end
+
+      type series =
+        {
+          data: ::Array[Courier::NotificationMetricsResponse::Series::Data],
+          period: Time
+        }
+
+      class Series < Courier::Internal::Type::BaseModel
+        attr_accessor data: ::Array[Courier::NotificationMetricsResponse::Series::Data]
+
+        attr_accessor period: Time
+
+        def initialize: (
+          data: ::Array[Courier::NotificationMetricsResponse::Series::Data],
+          period: Time
+        ) -> void
+
+        def to_hash: -> {
+          data: ::Array[Courier::NotificationMetricsResponse::Series::Data],
+          period: Time
+        }
+
+        type data =
+          {
+            channel: String,
+            clicked: Integer,
+            delivered: Integer,
+            errors: Integer,
+            opened: Integer,
+            provider: String,
+            sent: Integer,
+            undeliverable: Integer
+          }
+
+        class Data < Courier::Internal::Type::BaseModel
+          attr_accessor channel: String
+
+          attr_accessor clicked: Integer
+
+          attr_accessor delivered: Integer
+
+          attr_accessor errors: Integer
+
+          attr_accessor opened: Integer
+
+          attr_accessor provider: String
+
+          attr_accessor sent: Integer
+
+          attr_accessor undeliverable: Integer
+
+          def initialize: (
+            channel: String,
+            clicked: Integer,
+            delivered: Integer,
+            errors: Integer,
+            opened: Integer,
+            provider: String,
+            sent: Integer,
+            undeliverable: Integer
+          ) -> void
+
+          def to_hash: -> {
+            channel: String,
+            clicked: Integer,
+            delivered: Integer,
+            errors: Integer,
+            opened: Integer,
+            provider: String,
+            sent: Integer,
+            undeliverable: Integer
+          }
+        end
+      end
+    end
+  end
+end

data/sig/courier/models.rbs

@@ -379,12 +379,16 @@ module Courier
 
   class NotificationGetContent = Courier::Models::NotificationGetContent
 
+  class NotificationGetMetricsParams = Courier::Models::NotificationGetMetricsParams
+
   class NotificationListParams = Courier::Models::NotificationListParams
 
   class NotificationListVersionsParams = Courier::Models::NotificationListVersionsParams
 
   class NotificationLocalePutRequest = Courier::Models::NotificationLocalePutRequest
 
+  class NotificationMetricsResponse = Courier::Models::NotificationMetricsResponse
+
   class NotificationPreferenceDetails = Courier::Models::NotificationPreferenceDetails
 
   class NotificationPublishParams = Courier::Models::NotificationPublishParams

data/sig/courier/resources/notifications.rbs

@@ -26,6 +26,15 @@ module Courier
 
       def archive: (String id, ?request_options: Courier::request_opts) -> nil
 
+      def get_metrics: (
+        String id,
+        ?end_: Time,
+        ?granularity: Courier::Models::NotificationGetMetricsParams::granularity,
+        ?lookback: String,
+        ?start: Time,
+        ?request_options: Courier::request_opts
+      ) -> Courier::NotificationMetricsResponse
+
       def list_versions: (
         String id,
         ?cursor: String,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trycourier
 version: !ruby/object:Gem::Version
-  version: 6.1.0
+  version: 6.2.0
 platform: ruby
 authors:
 - Courier
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -296,10 +296,12 @@ files:
 - lib/courier/models/notification_create_params.rb
 - lib/courier/models/notification_element_put_request.rb
 - lib/courier/models/notification_get_content.rb
+- lib/courier/models/notification_get_metrics_params.rb
 - lib/courier/models/notification_list_params.rb
 - lib/courier/models/notification_list_response.rb
 - lib/courier/models/notification_list_versions_params.rb
 - lib/courier/models/notification_locale_put_request.rb
+- lib/courier/models/notification_metrics_response.rb
 - lib/courier/models/notification_preference_details.rb
 - lib/courier/models/notification_publish_params.rb
 - lib/courier/models/notification_put_content_params.rb
@@ -767,10 +769,12 @@ files:
 - rbi/courier/models/notification_create_params.rbi
 - rbi/courier/models/notification_element_put_request.rbi
 - rbi/courier/models/notification_get_content.rbi
+- rbi/courier/models/notification_get_metrics_params.rbi
 - rbi/courier/models/notification_list_params.rbi
 - rbi/courier/models/notification_list_response.rbi
 - rbi/courier/models/notification_list_versions_params.rbi
 - rbi/courier/models/notification_locale_put_request.rbi
+- rbi/courier/models/notification_metrics_response.rbi
 - rbi/courier/models/notification_preference_details.rbi
 - rbi/courier/models/notification_publish_params.rbi
 - rbi/courier/models/notification_put_content_params.rbi
@@ -1237,10 +1241,12 @@ files:
 - sig/courier/models/notification_create_params.rbs
 - sig/courier/models/notification_element_put_request.rbs
 - sig/courier/models/notification_get_content.rbs
+- sig/courier/models/notification_get_metrics_params.rbs
 - sig/courier/models/notification_list_params.rbs
 - sig/courier/models/notification_list_response.rbs
 - sig/courier/models/notification_list_versions_params.rbs
 - sig/courier/models/notification_locale_put_request.rbs
+- sig/courier/models/notification_metrics_response.rbs
 - sig/courier/models/notification_preference_details.rbs
 - sig/courier/models/notification_publish_params.rbs
 - sig/courier/models/notification_put_content_params.rbs