trycourier 4.21.0 → 4.23.0

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

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

@@ -3,11 +3,16 @@
 module Courier
   module Resources
     class Tenants
+      # Manage the templates and template versions scoped to a single tenant, including
+      # the ones authored in the embedded designer.
       class Templates
+        # Manage the templates and template versions scoped to a single tenant, including
+        # the ones authored in the embedded designer.
         # @return [Courier::Resources::Tenants::Templates::Versions]
         attr_reader :versions
 
-        # Get a Template in Tenant
+        # Returns a tenant's notification template with its content, version, and created,
+        # updated, and published timestamps.
         #
         # @overload retrieve(template_id, tenant_id:, request_options: {})
         #
@@ -34,7 +39,8 @@ module Courier
           )
         end
 
-        # List Templates in Tenant
+        # Lists a tenant's notification templates, each carrying its version and published
+        # timestamp. Paged.
         #
         # @overload list(tenant_id, cursor: nil, limit: nil, request_options: {})
         #
@@ -61,12 +67,8 @@ module Courier
           )
         end
 
-        # Deletes the tenant's notification template with the given `template_id`.
-        #
-        # Returns **204 No Content** with an empty body on success.
-        #
-        # Returns **404** if there is no template with this ID for the tenant, including a
-        # second `DELETE` after a successful removal.
+        # Deletes a tenant's notification template by id. Sends for that tenant then use
+        # the workspace template registered under the same id.
         #
         # @overload delete(template_id, tenant_id:, request_options: {})
         #
@@ -96,10 +98,8 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Tenants::TemplatePublishParams} for more details.
         #
-        # Publishes a specific version of a notification template for a tenant.
-        #
-        # The template must already exist in the tenant's notification map. If no version
-        # is specified, defaults to publishing the "latest" version.
+        # Publishes a version of a tenant's notification template, making it the content
+        # that tenant's sends render from until you publish another.
         #
         # @overload publish(template_id, tenant_id:, version: nil, request_options: {})
         #
@@ -132,13 +132,8 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Tenants::TemplateReplaceParams} for more details.
         #
-        # Creates or updates a notification template for a tenant.
-        #
-        # If the template already exists for the tenant, it will be updated (200).
-        # Otherwise, a new template is created (201).
-        #
-        # Optionally publishes the template immediately if the `published` flag is set to
-        # true.
+        # Creates or updates a notification template scoped to one tenant, letting a
+        # tenant override the content the workspace template would send.
         #
         # @overload replace(template_id, tenant_id:, template:, published: nil, request_options: {})
         #

data/lib/courier/resources/tenants.rb

@@ -2,14 +2,19 @@
 
 module Courier
   module Resources
+    # Manage tenants — the organizations, teams, or accounts your users belong to —
+    # along with their users and default preferences.
     class Tenants
       # @return [Courier::Resources::Tenants::Preferences]
       attr_reader :preferences
 
+      # Manage the templates and template versions scoped to a single tenant, including
+      # the ones authored in the embedded designer.
       # @return [Courier::Resources::Tenants::Templates]
       attr_reader :templates
 
-      # Get a Tenant
+      # Returns one tenant with its name, parent tenant id, default preferences,
+      # properties, and the user profile applied to its members.
       #
       # @overload retrieve(tenant_id, request_options: {})
       #
@@ -32,7 +37,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::TenantUpdateParams} for more details.
       #
-      # Create or Replace a Tenant
+      # Creates or replaces a tenant from a name, parent, brand, properties, and default
+      # preferences supplied in the request body.
       #
       # @overload update(tenant_id, name:, brand_id: nil, default_preferences: nil, parent_tenant_id: nil, properties: nil, user_profile: nil, request_options: {})
       #
@@ -69,7 +75,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::TenantListParams} for more details.
       #
-      # Get a List of Tenants
+      # Lists the workspace's tenants, each carrying a name, parent tenant, properties,
+      # and default preferences. Paged.
       #
       # @overload list(cursor: nil, limit: nil, parent_tenant_id: nil, request_options: {})
       #
@@ -96,7 +103,8 @@ module Courier
         )
       end
 
-      # Delete a Tenant
+      # Deletes a tenant. Its members' workspace-level profiles and preferences live
+      # outside the tenant and are managed separately.
       #
       # @overload delete(tenant_id, request_options: {})
       #
@@ -119,7 +127,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::TenantListUsersParams} for more details.
       #
-      # Get Users in Tenant
+      # Returns the users belonging to a tenant with cursor paging. Use it to see who a
+      # tenant-scoped send will reach.
       #
       # @overload list_users(tenant_id, cursor: nil, limit: nil, request_options: {})
       #

data/lib/courier/resources/translations.rb

@@ -2,11 +2,14 @@
 
 module Courier
   module Resources
+    # Store and retrieve the translation strings Courier uses to render localized
+    # template content.
     class Translations
       # Some parameter documentations has been truncated, see
       # {Courier::Models::TranslationRetrieveParams} for more details.
       #
-      # Get translations by locale
+      # Returns the translation strings stored for one domain and locale, for use in
+      # localized notification content.
       #
       # @overload retrieve(locale, domain:, request_options: {})
       #
@@ -36,7 +39,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::TranslationUpdateParams} for more details.
       #
-      # Update a translation
+      # Uploads the translation strings for one domain and locale. Courier uses them to
+      # render localized content for recipients in that locale.
       #
       # @overload update(locale, domain:, body:, request_options: {})
       #