trycourier 4.21.0 → 4.23.0

data/lib/courier/resources/journeys.rb

@@ -2,26 +2,33 @@
 
 module Courier
   module Resources
+    # Build, version, publish, invoke, and cancel multi-step notification workflows,
+    # along with the templates scoped to them.
     class Journeys
+      # Build, version, publish, invoke, and cancel multi-step notification workflows,
+      # along with the templates scoped to them.
       # @return [Courier::Resources::Journeys::Templates]
       attr_reader :templates
 
-      # Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to
-      # publish on create. Send nodes are not allowed on `POST`. The standard flow is:
-      # create the journey shell here, add notification templates with
-      # `POST /journeys/{templateId}/templates`, then wire them into the journey with
-      # `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to
-      # publish a draft after the fact.
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::JourneyCreateParams} for more details.
       #
-      # @overload create(name:, nodes:, enabled: nil, state: nil, request_options: {})
+      # Creates a journey from a set of nodes, in draft state unless you pass a
+      # published state. Send nodes cannot be included until their templates exist.
       #
-      # @param name [String]
+      # @overload create(name:, nodes:, enabled: nil, state: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @param nodes [Array<Courier::Models::JourneyAPIInvokeTriggerNode, Courier::Models::JourneySegmentTriggerNode, Courier::Models::JourneySendNode, Courier::Models::JourneyDelayDurationNode, Courier::Models::JourneyDelayUntilNode, Courier::Models::JourneyFetchGetDeleteNode, Courier::Models::JourneyFetchPostPutNode, Courier::Models::JourneyAINode, Courier::Models::JourneyThrottleStaticNode, Courier::Models::JourneyThrottleDynamicNode, Courier::Models::JourneyNode::JourneyBatchNode, Courier::Models::JourneyNode::JourneyAddToDigestNode, Courier::Models::JourneyExitNode, Courier::Models::JourneyNode::JourneyBranchNode>]
+      # @param name [String] Body param
       #
-      # @param enabled [Boolean]
+      # @param nodes [Array<Courier::Models::JourneyAPIInvokeTriggerNode, Courier::Models::JourneySegmentTriggerNode, Courier::Models::JourneySendNode, Courier::Models::JourneyDelayDurationNode, Courier::Models::JourneyDelayUntilNode, Courier::Models::JourneyFetchGetDeleteNode, Courier::Models::JourneyFetchPostPutNode, Courier::Models::JourneyAINode, Courier::Models::JourneyThrottleStaticNode, Courier::Models::JourneyThrottleDynamicNode, Courier::Models::JourneyNode::JourneyBatchNode, Courier::Models::JourneyNode::JourneyAddToDigestNode, Courier::Models::JourneyExitNode, Courier::Models::JourneyNode::JourneyBranchNode>] Body param
       #
-      # @param state [Symbol, Courier::Models::JourneyState] Lifecycle state of a journey.
+      # @param enabled [Boolean] Body param
+      #
+      # @param state [Symbol, Courier::Models::JourneyState] Body param: Lifecycle state of a journey.
+      #
+      # @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]
       #
@@ -30,10 +37,13 @@ module Courier
       # @see Courier::Models::JourneyCreateParams
       def create(params)
         parsed, options = Courier::JourneyCreateParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: "journeys",
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::JourneyResponse,
           options: options
         )
@@ -68,7 +78,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::JourneyListParams} for more details.
       #
-      # Get the list of journeys.
+      # Lists the workspace's journeys, each carrying a name, state, and enabled flag.
+      # Paged by cursor.
       #
       # @overload list(cursor: nil, version: nil, request_options: {})
       #
@@ -93,8 +104,8 @@ module Courier
         )
       end
 
-      # Archive a journey. Archived journeys cannot be invoked. Existing journey runs
-      # continue to completion.
+      # Archives a journey so it can no longer be invoked. Runs already in flight
+      # continue to completion, so archiving never strands a user mid-sequence.
       #
       # @overload archive(template_id, request_options: {})
       #
@@ -117,16 +128,16 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::JourneyCancelParams} for more details.
       #
-      # Cancel journey runs. The request body must include EXACTLY ONE of
-      # `cancelation_token` (cancels every run associated with the token) or `run_id`
-      # (cancels a single tenant-scoped run). Supplying both or neither returns a `400`.
-      # A `run_id` that does not match a run for the tenant returns `404`. Cancelation
-      # is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was
-      # already `CANCELED` is left unchanged and its current status is returned.
+      # Cancels in-flight journey runs, either every run sharing a cancelation token or
+      # one run by id. Use it to stop a sequence when the event resolves.
+      #
+      # @overload cancel(cancel_journey_request:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
-      # @overload cancel(cancel_journey_request:, request_options: {})
+      # @param cancel_journey_request [Courier::Models::CancelJourneyRequest::ByCancelationToken, Courier::Models::CancelJourneyRequest::ByRunID] Body param: Request body for `POST /journeys/cancel`. Provide EXACTLY ONE of `ca
       #
-      # @param cancel_journey_request [Courier::Models::CancelJourneyRequest::ByCancelationToken, Courier::Models::CancelJourneyRequest::ByRunID] Request body for `POST /journeys/cancel`. Provide EXACTLY ONE of `cancelation_to
+      # @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]
       #
@@ -138,6 +149,10 @@ module Courier
         @client.request(
           method: :post,
           path: "journeys/cancel",
+          headers: parsed.except(:cancel_journey_request).transform_keys(
+            idempotency_key: "idempotency-key",
+            x_idempotency_expiration: "x-idempotency-expiration"
+          ),
           body: parsed[:cancel_journey_request],
           model: Courier::CancelJourneyResponse,
           options: options
@@ -147,18 +162,22 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::JourneyInvokeParams} for more details.
       #
-      # Invoke a journey by id or alias to start a new run. The response includes a
-      # `runId` identifying the run.
+      # Starts a journey run for one user and returns a runId. Runs execute
+      # asynchronously, so the response arrives before any message is sent.
+      #
+      # @overload invoke(template_id, data: nil, profile: nil, user_id: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+      #
+      # @param template_id [String] Path param: A unique identifier representing the journey to be invoked. Accepts
       #
-      # @overload invoke(template_id, data: nil, profile: nil, user_id: nil, request_options: {})
+      # @param data [Hash{Symbol=>Object}] Body param: Data payload passed to the journey. The expected shape can be predef
       #
-      # @param template_id [String] A unique identifier representing the journey to be invoked. Accepts a Journey ID
+      # @param profile [Hash{Symbol=>Object}] Body param: Profile data for the user. Can contain contact information (email, p
       #
-      # @param data [Hash{Symbol=>Object}] Data payload passed to the journey. The expected shape can be predefined using t
+      # @param user_id [String] Body param: A unique identifier for the user. If not provided, the system will a
       #
-      # @param profile [Hash{Symbol=>Object}] Profile data for the user. Can contain contact information (email, phone_number)
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
       #
-      # @param user_id [String] A unique identifier for the user. If not provided, the system will attempt to re
+      # @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]
       #
@@ -167,16 +186,20 @@ module Courier
       # @see Courier::Models::JourneyInvokeParams
       def invoke(template_id, params = {})
         parsed, options = Courier::JourneyInvokeParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: ["journeys/%1$s/invoke", template_id],
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::JourneysInvokeResponse,
           options: options
         )
       end
 
-      # List published versions of a journey, ordered most recent first.
+      # Lists a journey's published versions, most recent first, so you have a version
+      # id to roll back to. Paged by cursor.
       #
       # @overload list_versions(template_id, request_options: {})
       #
@@ -196,15 +219,21 @@ module Courier
         )
       end
 
-      # Publish the current draft as a new version. Body is optional; pass
-      # `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if
-      # the journey has no draft to publish.
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::JourneyPublishParams} for more details.
       #
-      # @overload publish(template_id, version: nil, request_options: {})
+      # Publishes a journey's current draft as a new version, making it live for new
+      # runs. Pass a version instead to roll back to an earlier one.
       #
-      # @param template_id [String] Journey id
+      # @overload publish(template_id, version: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+      #
+      # @param template_id [String] Path param: Journey id
+      #
+      # @param version [String] Body param
       #
-      # @param version [String]
+      # @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]
       #
@@ -213,20 +242,20 @@ module Courier
       # @see Courier::Models::JourneyPublishParams
       def publish(template_id, params = {})
         parsed, options = Courier::JourneyPublishParams.dump_request(params)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
         @client.request(
           method: :post,
           path: ["journeys/%1$s/publish", template_id],
-          body: parsed,
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
           model: Courier::JourneyResponse,
           options: options
         )
       end
 
-      # Replace the journey draft. Updates the working draft only; call
-      # `POST /journeys/{templateId}/publish` to make it live, or pass
-      # `state: "PUBLISHED"` in this request to publish immediately. Send-node
-      # `template` ids must already exist and be scoped to this journey, and node ids
-      # must not be claimed by another journey.
+      # Replaces a journey's working draft, leaving the published version live until you
+      # publish. Reach for this when editing a journey already running.
       #
       # @overload replace(template_id, name:, nodes:, enabled: nil, state: nil, request_options: {})
       #

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

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Lists
+      # Manage static groups of users that you subscribe explicitly, and send to them by
+      # list id or list pattern.
       class Subscriptions
-        # Get the list's subscriptions.
+        # Returns the users subscribed to a list with paging, each with the preferences
+        # recorded for that subscription.
         #
         # @overload list(list_id, cursor: nil, request_options: {})
         #
@@ -29,14 +32,21 @@ module Courier
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Courier::Models::Lists::SubscriptionAddParams} for more details.
+        #
         # Subscribes additional users to the list, without modifying existing
         # subscriptions. If the list does not exist, it will be automatically created.
         #
-        # @overload add(list_id, recipients:, request_options: {})
+        # @overload add(list_id, recipients:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
         #
-        # @param list_id [String] A unique identifier representing the list you wish to retrieve.
+        # @param list_id [String] Path param: A unique identifier representing the list you wish to retrieve.
         #
-        # @param recipients [Array<Courier::Models::PutSubscriptionsRecipient>]
+        # @param recipients [Array<Courier::Models::PutSubscriptionsRecipient>] 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]
         #
@@ -45,10 +55,13 @@ module Courier
         # @see Courier::Models::Lists::SubscriptionAddParams
         def add(list_id, params)
           parsed, options = Courier::Lists::SubscriptionAddParams.dump_request(params)
+          header_params =
+            {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
           @client.request(
             method: :post,
             path: ["lists/%1$s/subscriptions", list_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: NilClass,
             options: options
           )
@@ -82,8 +95,8 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Lists::SubscriptionSubscribeUserParams} for more details.
         #
-        # Subscribe a user to an existing list (note: if the List does not exist, it will
-        # be automatically created).
+        # Subscribes one user to a list, creating the list if it does not yet exist.
+        # Optional preferences apply to this subscription only.
         #
         # @overload subscribe_user(user_id, list_id:, preferences: nil, request_options: {})
         #
@@ -113,7 +126,8 @@ module Courier
           )
         end
 
-        # Delete a subscription to a list by list ID and user ID.
+        # Removes one user's subscription to a list, addressed by list id and user id. The
+        # user's profile and other subscriptions are separate resources.
         #
         # @overload unsubscribe_user(user_id, list_id:, request_options: {})
         #

data/lib/courier/resources/lists.rb

@@ -2,11 +2,16 @@
 
 module Courier
   module Resources
+    # Manage static groups of users that you subscribe explicitly, and send to them by
+    # list id or list pattern.
     class Lists
+      # Manage static groups of users that you subscribe explicitly, and send to them by
+      # list id or list pattern.
       # @return [Courier::Resources::Lists::Subscriptions]
       attr_reader :subscriptions
 
-      # Returns a list based on the list ID provided.
+      # Returns one list by id with its name and created and updated timestamps. Fetch
+      # its subscribers separately with the subscriptions endpoint.
       #
       # @overload retrieve(list_id, request_options: {})
       #
@@ -26,7 +31,8 @@ module Courier
         )
       end
 
-      # Create or replace an existing list with the supplied values.
+      # Creates or replaces a list from a name and preferences. Subscribers are managed
+      # through the separate subscriptions endpoints.
       #
       # @overload update(list_id, name:, preferences: nil, request_options: {})
       #
@@ -55,7 +61,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::ListListParams} for more details.
       #
-      # Returns all of the lists, with the ability to filter based on a pattern.
+      # Returns the workspace's lists, filterable by a pattern to fetch a subset such as
+      # every regional list. Paged by cursor.
       #
       # @overload list(cursor: nil, pattern: nil, request_options: {})
       #
@@ -80,7 +87,8 @@ module Courier
         )
       end
 
-      # Delete a list by list ID.
+      # Deletes a list, halting sends that target it. A previously deleted list can be
+      # brought back with the companion restore endpoint.
       #
       # @overload delete(list_id, request_options: {})
       #
@@ -100,7 +108,8 @@ module Courier
         )
       end
 
-      # Restore a previously deleted list.
+      # Restores a previously deleted list along with its subscribers, so a list removed
+      # by mistake can be brought back rather than rebuilt.
       #
       # @overload restore(list_id, request_options: {})
       #

data/lib/courier/resources/messages.rb

@@ -2,11 +2,14 @@
 
 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 Messages
       # Some parameter documentations has been truncated, see
       # {Courier::Models::MessageRetrieveParams} for more details.
       #
-      # Fetch the status of a message you've previously sent.
+      # Returns a sent message's status, recipient, event, and per-provider delivery
+      # detail, with timestamps for enqueued, sent, delivered, opened, and clicked.
       #
       # @overload retrieve(message_id, request_options: {})
       #
@@ -29,7 +32,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::MessageListParams} for more details.
       #
-      # Fetch the statuses of messages you've previously sent.
+      # Returns previously sent messages, most recent first, each carrying its status,
+      # recipient, channel, and provider. Paged by cursor.
       #
       # @overload list(archived: nil, cursor: nil, enqueued_after: nil, event: nil, list: nil, message_id: nil, notification: nil, provider: nil, recipient: nil, status: nil, tag: nil, tags: nil, tenant_id: nil, trace_id: nil, request_options: {})
       #
@@ -78,11 +82,8 @@ module Courier
         )
       end
 
-      # Cancel a message that is currently in the process of being delivered. A
-      # well-formatted API call to the cancel message API will return either `200`
-      # status code for a successful cancellation or `409` status code for an
-      # unsuccessful cancellation. Both cases will include the actual message record in
-      # the response body (see details below).
+      # Cancels a message that is still in the delivery pipeline and returns the message
+      # record with its resulting canceled or failed status.
       #
       # @overload cancel(message_id, request_options: {})
       #
@@ -105,7 +106,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::MessageContentParams} for more details.
       #
-      # Get message content
+      # Returns the rendered content Courier delivered for a message, broken out per
+      # channel, to confirm what the recipient received.
       #
       # @overload content(message_id, request_options: {})
       #
@@ -125,7 +127,8 @@ module Courier
         )
       end
 
-      # Fetch the array of events of a message you've previously sent.
+      # Returns the ordered event history for a sent message, one entry per status
+      # transition with its timestamp.
       #
       # @overload history(message_id, type: nil, request_options: {})
       #
@@ -153,11 +156,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::MessageResendParams} for more details.
       #
-      # Resend a previously sent message. The original send request is loaded from
-      # storage and a brand-new send is enqueued for the same recipient and content,
-      # producing a **new** `messageId` — the original message is not modified.
-      # Throttled by a per-message rate limit; a repeat inside the limit window returns
-      # `429 Too Many Requests`.
+      # Resends a previously sent message to the same recipient and content, returning a
+      # new messageId. The original send request is not modified.
       #
       # @overload resend(message_id, request_options: {})
       #

data/lib/courier/resources/notifications/checks.rb

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Notifications
+      # Create, update, version, publish, and localize notification templates and their
+      # content.
       class Checks
-        # Replace the submission checks for a notification template.
+        # Replaces the approval checks on a template submission with the complete set
+        # supplied in the request body.
         #
         # @overload update(submission_id, id:, checks:, request_options: {})
         #
@@ -34,7 +37,8 @@ module Courier
           )
         end
 
-        # Retrieve the submission checks for a notification template.
+        # Returns the approval checks recorded for a template submission, each with its
+        # pass or fail result.
         #
         # @overload list(submission_id, id:, request_options: {})
         #
@@ -61,7 +65,8 @@ module Courier
           )
         end
 
-        # Cancel a submission for a notification template.
+        # Cancels a pending template submission, withdrawing it from the approval
+        # workflow. The template stays in draft and can be resubmitted later.
         #
         # @overload delete(submission_id, id:, request_options: {})
         #

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: {})
       #