trycourier 4.20.0 → 4.22.0

data/lib/courier/resources/notifications.rb

@@ -2,7 +2,11 @@
 
 module Courier
   module Resources
+    # Create, update, version, publish, and localize notification templates and their
+    # content.
     class Notifications
+      # Create, update, version, publish, and localize notification templates and their
+      # content.
       # @return [Courier::Resources::Notifications::Checks]
       attr_reader :checks
 
@@ -12,11 +16,15 @@ module Courier
       # Create a notification template. Requires all fields in the notification object.
       # Templates are created in draft state by default.
       #
-      # @overload create(notification:, state: nil, request_options: {})
+      # @overload create(notification:, state: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param notification [Courier::Models::NotificationTemplatePayload] Core template fields used in POST and PUT request bodies (nested under a `notifi
+      # @param notification [Courier::Models::NotificationTemplatePayload] Body param: Core template fields used in POST and PUT request bodies (nested und
+      #
+      # @param state [Symbol, Courier::Models::NotificationTemplateCreateRequest::State] Body param: Template state after creation. Case-insensitive input, normalized to
+      #
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
       #
-      # @param state [Symbol, Courier::Models::NotificationTemplateCreateRequest::State] Template state after creation. Case-insensitive input, normalized to uppercase i
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -25,10 +33,13 @@ module Courier
       # @see Courier::Models::NotificationCreateParams
       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",
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::NotificationTemplateResponse,
           options: options
         )
@@ -63,7 +74,8 @@ module Courier
         )
       end
 
-      # List notification templates in your workspace.
+      # Lists the workspace's notification templates. Each carries a name, tags, brand,
+      # routing, and its draft or published state.
       #
       # @overload list(cursor: nil, event_id: nil, notes: nil, request_options: {})
       #
@@ -90,7 +102,8 @@ module Courier
         )
       end
 
-      # Archive a notification template.
+      # Archives a notification template, preventing new sends from referencing it. The
+      # template stays retrievable for its version history.
       #
       # @overload archive(id, request_options: {})
       #
@@ -110,12 +123,9 @@ module Courier
         )
       end
 
-      # Duplicate a notification template. Creates a standalone copy within the same
-      # workspace and environment, with " COPY" appended to the title. The copy clones
-      # the source draft's tags, brand, subscription topic, routing strategy, channels,
-      # and content, and is always created as a standalone template (it is not linked to
-      # any journey or broadcast, even if the source was). Templates that are scoped to
-      # a journey or a broadcast cannot be duplicated through this endpoint.
+      # Copies a notification template within the same workspace and environment,
+      # appending " COPY" to the title. The copy is standalone and independently
+      # editable.
       #
       # @overload duplicate(id, request_options: {})
       #
@@ -135,7 +145,8 @@ module Courier
         )
       end
 
-      # List versions of a notification template.
+      # Returns a notification template's published versions, most recent first, for
+      # comparison or rollback. Paged.
       #
       # @overload list_versions(id, cursor: nil, limit: nil, request_options: {})
       #
@@ -162,14 +173,21 @@ module Courier
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Courier::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.
       #
-      # @overload publish(id, version: nil, request_options: {})
+      # @overload publish(id, version: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param id [String] Template ID (nt\_ prefix).
+      # @param id [String] Path param: Template ID (nt\_ prefix).
+      #
+      # @param version [String] Body param: Historical version to publish (e.g. "v001"). Omit to publish the cur
       #
-      # @param version [String] Historical version to publish (e.g. "v001"). Omit to publish the current draft.
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+      #
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -178,18 +196,20 @@ module Courier
       # @see Courier::Models::NotificationPublishParams
       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],
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: NilClass,
           options: options
         )
       end
 
-      # Replace the elemental content of a notification template. Overwrites all
-      # elements in the template with the provided content. Only supported for V2
-      # (elemental) templates.
+      # Replaces all Elemental content in a template, overwriting every existing
+      # element. Supported for V2 templates only, not V1 blocks and channels.
       #
       # @overload put_content(id, content:, state: nil, request_options: {})
       #
@@ -215,8 +235,8 @@ module Courier
         )
       end
 
-      # Update a single element within a notification template. Only supported for V2
-      # (elemental) templates.
+      # Replaces one Elemental element in a template, addressed by its element id.
+      # Supported for V2 templates only, not V1 blocks and channels.
       #
       # @overload put_element(element_id, id:, type:, channels: nil, data: nil, if_: nil, loop_: nil, ref: nil, state: nil, request_options: {})
       #
@@ -258,9 +278,8 @@ module Courier
         )
       end
 
-      # Set locale-specific content overrides for a notification template. Each element
-      # override must reference an existing element by ID. Only supported for V2
-      # (elemental) templates.
+      # Sets locale-specific content overrides for a template. Each override must
+      # reference an element that already exists in the default content.
       #
       # @overload put_locale(locale_id, id:, elements:, state: nil, request_options: {})
       #
@@ -295,7 +314,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::NotificationReplaceParams} for more details.
       #
-      # Replace a notification template. All fields are required.
+      # Replaces a notification template in full, so send every field rather than only
+      # the ones you want changed. Publish separately to make it live.
       #
       # @overload replace(id, notification:, state: nil, request_options: {})
       #
@@ -324,10 +344,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::NotificationRetrieveContentParams} for more details.
       #
-      # Retrieve the content of a notification template. The response shape depends on
-      # whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use
-      # the `version` query parameter to select draft, published, or a specific
-      # historical version.
+      # Returns a template's content and checksum. V2 templates return Elemental
+      # elements, while V1 templates return blocks and channels instead.
       #
       # @overload retrieve_content(id, version: nil, request_options: {})
       #

data/lib/courier/resources/profiles/lists.rb

@@ -3,11 +3,14 @@
 module Courier
   module Resources
     class Profiles
+      # Store the contact information Courier delivers to for each user — email, phone
+      # number, push tokens, and any custom data you send to.
       class Lists
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Profiles::ListRetrieveParams} for more details.
         #
-        # Returns the subscribed lists for a specified user.
+        # Returns the lists a user is subscribed to, with paging. Use it to check what a
+        # recipient will receive before sending to a list.
         #
         # @overload retrieve(user_id, cursor: nil, request_options: {})
         #
@@ -35,7 +38,8 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Profiles::ListDeleteParams} for more details.
         #
-        # Removes all list subscriptions for given user.
+        # Removes every list subscription for a user at once. Their profile and
+        # preferences are untouched, so this only affects list-targeted sends.
         #
         # @overload delete(user_id, request_options: {})
         #
@@ -58,14 +62,18 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Profiles::ListSubscribeParams} for more details.
         #
-        # Subscribes the given user to one or more lists. If the list does not exist, it
-        # will be created.
+        # Subscribes a user to one or more lists, creating any list that does not yet
+        # exist. Optional preferences apply to each subscription.
         #
-        # @overload subscribe(user_id, lists:, request_options: {})
+        # @overload subscribe(user_id, lists:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
         #
-        # @param user_id [String] A unique identifier representing the user associated with the requested user pro
+        # @param user_id [String] Path param: A unique identifier representing the user associated with the reques
+        #
+        # @param lists [Array<Courier::Models::SubscribeToListsRequestItem>] Body param
+        #
+        # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
         #
-        # @param lists [Array<Courier::Models::SubscribeToListsRequestItem>]
+        # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
         #
         # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -74,10 +82,13 @@ module Courier
         # @see Courier::Models::Profiles::ListSubscribeParams
         def subscribe(user_id, params)
           parsed, options = Courier::Profiles::ListSubscribeParams.dump_request(params)
+          header_params =
+            {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
           @client.request(
             method: :post,
             path: ["profiles/%1$s/lists", user_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Courier::Models::Profiles::ListSubscribeResponse,
             options: options
           )

data/lib/courier/resources/profiles.rb

@@ -2,21 +2,29 @@
 
 module Courier
   module Resources
+    # Store the contact information Courier delivers to for each user — email, phone
+    # number, push tokens, and any custom data you send to.
     class Profiles
+      # Store the contact information Courier delivers to for each user — email, phone
+      # number, push tokens, and any custom data you send to.
       # @return [Courier::Resources::Profiles::Lists]
       attr_reader :lists
 
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProfileCreateParams} for more details.
       #
-      # Merge the supplied values with an existing profile or create a new profile if
-      # one doesn't already exist.
+      # Merges the supplied values into a user's profile, creating it if absent and
+      # leaving any key you omit untouched. Prefer this for everyday writes.
       #
-      # @overload create(user_id, profile:, request_options: {})
+      # @overload create(user_id, profile:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param user_id [String] A unique identifier representing the user associated with the requested profile.
+      # @param user_id [String] Path param: A unique identifier representing the user associated with the reques
       #
-      # @param profile [Hash{Symbol=>Object}]
+      # @param profile [Hash{Symbol=>Object}] Body param
+      #
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+      #
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -25,10 +33,13 @@ module Courier
       # @see Courier::Models::ProfileCreateParams
       def create(user_id, params)
         parsed, options = Courier::ProfileCreateParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: ["profiles/%1$s", user_id],
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::Models::ProfileCreateResponse,
           options: options
         )
@@ -37,7 +48,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProfileRetrieveParams} for more details.
       #
-      # Returns the specified user profile.
+      # Returns a user's stored profile and preferences, including the email address,
+      # phone number, and push tokens Courier can reach them on.
       #
       # @overload retrieve(user_id, request_options: {})
       #
@@ -60,7 +72,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProfileUpdateParams} for more details.
       #
-      # Update a profile
+      # Applies a JSON Patch to a user profile, adding, removing, or replacing
+      # individual fields without sending the whole object.
       #
       # @overload update(user_id, patch:, request_options: {})
       #
@@ -87,7 +100,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProfileDeleteParams} for more details.
       #
-      # Deletes the specified user profile.
+      # Deletes a user's profile and stored contact details. List subscriptions and
+      # preferences are separate resources, so remove those too if required.
       #
       # @overload delete(user_id, request_options: {})
       #
@@ -110,11 +124,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProfileReplaceParams} for more details.
       #
-      # When using `PUT`, be sure to include all the key-value pairs required by the
-      # recipient's profile. Any key-value pairs that exist in the profile but fail to
-      # be included in the `PUT` request will be removed from the profile. Remember, a
-      # `PUT` update is a full replacement of the data. For partial updates, use the
-      # [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.
+      # Overwrites a user profile in full, removing any key absent from the request
+      # body. Use the patch endpoint when changing a single field.
       #
       # @overload replace(user_id, profile:, request_options: {})
       #

data/lib/courier/resources/providers/catalog.rb

@@ -3,14 +3,14 @@
 module Courier
   module Resources
     class Providers
+      # Configure the channel providers Courier delivers through, and browse the
+      # provider types it supports.
       class Catalog
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Providers::CatalogListParams} for more details.
         #
-        # Returns the catalog of available provider types with their display names,
-        # descriptions, and configuration schema fields (snake_case, with `type` and
-        # `required`). Providers with no configurable schema return only `provider`,
-        # `name`, and `description`.
+        # Returns the provider types Courier supports, each with a display name,
+        # description, and the configuration fields it requires.
         #
         # @overload list(channel: nil, keys: nil, name: nil, request_options: {})
         #

data/lib/courier/resources/providers.rb

@@ -2,25 +2,33 @@
 
 module Courier
   module Resources
+    # Configure the channel providers Courier delivers through, and browse the
+    # provider types it supports.
     class Providers
+      # Configure the channel providers Courier delivers through, and browse the
+      # provider types it supports.
       # @return [Courier::Resources::Providers::Catalog]
       attr_reader :catalog
 
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProviderCreateParams} for more details.
       #
-      # Create a new provider configuration. The `provider` field must be a known
-      # Courier provider key (see catalog).
+      # Configures a provider integration from a Courier provider key and its settings.
+      # Check the catalog endpoint for the schema each provider expects.
       #
-      # @overload create(provider:, alias_: nil, settings: nil, title: nil, request_options: {})
+      # @overload create(provider:, alias_: nil, settings: nil, title: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param provider [String] The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a kno
+      # @param provider [String] Body param: The provider key identifying the type (e.g. "sendgrid", "twilio"). M
       #
-      # @param alias_ [String] Optional alias for this configuration.
+      # @param alias_ [String] Body param: Optional alias for this configuration.
       #
-      # @param settings [Hash{Symbol=>Object}] Provider-specific settings (snake_case keys). Defaults to an empty object when o
+      # @param settings [Hash{Symbol=>Object}] Body param: Provider-specific settings (snake_case keys). Defaults to an empty o
       #
-      # @param title [String] Optional display title. Omit to use "Default Configuration".
+      # @param title [String] Body param: Optional display title. Omit to use "Default Configuration".
+      #
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+      #
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -29,16 +37,20 @@ module Courier
       # @see Courier::Models::ProviderCreateParams
       def create(params)
         parsed, options = Courier::ProviderCreateParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: "providers",
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::Provider,
           options: options
         )
       end
 
-      # Fetch a single provider configuration by ID.
+      # Returns one configured provider by id, including its channel, provider key,
+      # alias, title, and current settings.
       #
       # @overload retrieve(id, request_options: {})
       #
@@ -61,11 +73,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ProviderUpdateParams} for more details.
       #
-      # Replace an existing provider configuration. The `provider` key is required and
-      # determines which provider-specific settings schema is applied. All other fields
-      # are optional — omitted fields are cleared from the stored configuration (this is
-      # a full replacement, not a partial merge). Changing the provider type for an
-      # existing configuration is not supported.
+      # Replaces a provider's configuration in full, clearing any field you omit rather
+      # than merging it. Send the complete settings object.
       #
       # @overload update(id, provider:, alias_: nil, settings: nil, title: nil, request_options: {})
       #
@@ -95,8 +104,8 @@ module Courier
         )
       end
 
-      # List configured provider integrations for the current workspace. Supports
-      # cursor-based pagination.
+      # Lists the provider integrations configured in the workspace, one entry per
+      # channel and provider key with its alias and settings.
       #
       # @overload list(cursor: nil, request_options: {})
       #
@@ -119,8 +128,8 @@ module Courier
         )
       end
 
-      # Delete a provider configuration. Returns 409 if the provider is still referenced
-      # by routing or notifications.
+      # Deletes a provider configuration, which fails while routing strategies or
+      # templates still reference it. Update those references first.
       #
       # @overload delete(id, request_options: {})
       #

data/lib/courier/resources/requests.rb

@@ -2,8 +2,11 @@
 
 module Courier
   module Resources
+    # Look up the messages Courier has accepted, inspect their delivery history and
+    # rendered output, and cancel, resend, or archive them.
     class Requests
-      # Archive message
+      # Archives a send request by its request id. Use it to remove test sends or
+      # superseded requests from the message list without deleting them.
       #
       # @overload archive(request_id, request_options: {})
       #

data/lib/courier/resources/routing_strategies.rb

@@ -2,23 +2,32 @@
 
 module Courier
   module Resources
+    # Define reusable channel routing and failover strategies, and see which templates
+    # use them.
     class RoutingStrategies
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::RoutingStrategyCreateParams} for more details.
+      #
       # Create a routing strategy. Requires a name and routing configuration at minimum.
       # Channels and providers default to empty if omitted.
       #
-      # @overload create(name:, routing:, channels: nil, description: nil, providers: nil, tags: nil, request_options: {})
+      # @overload create(name:, routing:, channels: nil, description: nil, providers: nil, tags: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param name [String] Human-readable name for the routing strategy.
+      # @param name [String] Body param: Human-readable name for the routing strategy.
       #
-      # @param routing [Courier::Models::MessageRouting] Routing tree defining channel selection method and order.
+      # @param routing [Courier::Models::MessageRouting] Body param: Routing tree defining channel selection method and order.
       #
-      # @param channels [Hash{Symbol=>Courier::Models::Channel}, nil] Per-channel delivery configuration. Defaults to empty if omitted.
+      # @param channels [Hash{Symbol=>Courier::Models::Channel}, nil] Body param: Per-channel delivery configuration. Defaults to empty if omitted.
       #
-      # @param description [String, nil] Optional description of the routing strategy.
+      # @param description [String, nil] Body param: Optional description of the routing strategy.
       #
-      # @param providers [Hash{Symbol=>Courier::Models::MessageProvidersType}, nil] Per-provider delivery configuration. Defaults to empty if omitted.
+      # @param providers [Hash{Symbol=>Courier::Models::MessageProvidersType}, nil] Body param: Per-provider delivery configuration. Defaults to empty if omitted.
       #
-      # @param tags [Array<String>, nil] Optional tags for categorization.
+      # @param tags [Array<String>, nil] Body param: Optional tags for categorization.
+      #
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+      #
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -27,17 +36,20 @@ module Courier
       # @see Courier::Models::RoutingStrategyCreateParams
       def create(params)
         parsed, options = Courier::RoutingStrategyCreateParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: "routing-strategies",
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::RoutingStrategyGetResponse,
           options: options
         )
       end
 
-      # Retrieve a routing strategy by ID. Returns the full entity including routing
-      # content and metadata.
+      # Returns one routing strategy by id with its name, tags, channels, and the
+      # routing rules that decide provider order and fallback.
       #
       # @overload retrieve(id, request_options: {})
       #
@@ -105,8 +117,8 @@ module Courier
         )
       end
 
-      # List notification templates associated with a routing strategy. Includes
-      # template metadata only, not full content.
+      # Returns the notification templates using a routing strategy, with paging. Check
+      # this before changing a strategy that templates depend on.
       #
       # @overload list_notifications(id, cursor: nil, limit: nil, request_options: {})
       #

data/lib/courier/resources/send.rb

@@ -2,15 +2,22 @@
 
 module Courier
   module Resources
+    # Send a message to one or more recipients — users, lists, audiences, or tenants —
+    # across every channel you have configured.
     class Send
       # Some parameter documentations has been truncated, see
       # {Courier::Models::SendMessageParams} for more details.
       #
-      # Send a message to one or more recipients.
+      # Sends a message to one or more recipients and returns a requestId. Courier
+      # routes it to email, SMS, push, chat, or in-app based on your rules.
       #
-      # @overload message(message:, request_options: {})
+      # @overload message(message:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param message [Courier::Models::SendMessageParams::Message] The message property has the following primary top-level properties. They define
+      # @param message [Courier::Models::SendMessageParams::Message] Body param: The message property has the following primary top-level properties.
+      #
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+      #
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -19,10 +26,13 @@ module Courier
       # @see Courier::Models::SendMessageParams
       def message(params)
         parsed, options = Courier::SendMessageParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: "send",
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::Models::SendMessageResponse,
           options: options
         )

data/lib/courier/resources/tenants/preferences/items.rb

@@ -4,11 +4,14 @@ module Courier
   module Resources
     class Tenants
       class Preferences
+        # Manage tenants — the organizations, teams, or accounts your users belong to —
+        # along with their users and default preferences.
         class Items
           # Some parameter documentations has been truncated, see
           # {Courier::Models::Tenants::Preferences::ItemUpdateParams} for more details.
           #
-          # Create or Replace Default Preferences For Topic
+          # Sets a tenant's default opt-in status for one subscription topic, which applies
+          # to every member unless a user sets their own override.
           #
           # @overload update(topic_id, tenant_id:, status:, custom_routing: nil, has_custom_routing: nil, request_options: {})
           #
@@ -42,7 +45,8 @@ module Courier
             )
           end
 
-          # Remove Default Preferences For Topic
+          # Removes a tenant's default preference for one subscription topic, addressed by
+          # tenant id and topic id.
           #
           # @overload delete(topic_id, tenant_id:, request_options: {})
           #

data/lib/courier/resources/tenants/preferences.rb

@@ -4,6 +4,8 @@ module Courier
   module Resources
     class Tenants
       class Preferences
+        # Manage tenants — the organizations, teams, or accounts your users belong to —
+        # along with their users and default preferences.
         # @return [Courier::Resources::Tenants::Preferences::Items]
         attr_reader :items
 

data/lib/courier/resources/tenants/templates/versions.rb

@@ -4,17 +4,14 @@ module Courier
   module Resources
     class Tenants
       class Templates
+        # Manage the templates and template versions scoped to a single tenant, including
+        # the ones authored in the embedded designer.
         class Versions
           # Some parameter documentations has been truncated, see
           # {Courier::Models::Tenants::Templates::VersionRetrieveParams} for more details.
           #
-          # Fetches a specific version of a tenant template.
-          #
-          # Supports the following version formats:
-          #
-          # - `latest` - The most recent version of the template
-          # - `published` - The currently published version
-          # - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0")
+          # Returns one version of a tenant template, addressed by version number or by
+          # latest, with its content and publish timestamp.
           #
           # @overload retrieve(version, tenant_id:, template_id:, request_options: {})
           #