sendly 3.37.0 → 3.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43ce471688134e41cbed23f9d6b8bcc82895c867a4f42340120f670424d5a5f7
-  data.tar.gz: 628de06e8a2f2a25fc4837c94cb3bb651dc877f6d27ad8967af8b732d97f0a30
+  metadata.gz: 76b3722f8971a04363ce5a5ea47d61eba59db05698652f21cd5ab347c24c74c1
+  data.tar.gz: 478881a38dac65c6f9696d0de53114fadc10651152304542519616794ed64bfe
 SHA512:
-  metadata.gz: a012fb951c1c7e1f000e83e031d8c35eb3145bcdef3ce7ddc2eacc400263dae269223c4631e12f2db621ea0aa3a887142c18614773fcb5f577eee09bda0a1d92
-  data.tar.gz: f01118db4ee6fd181b148a2d2c1d7ea551b14c2e748cc0d01cf16cf5e097ba5718e53b943423ded434c071f17f2f27adbb63ed5064312c2d5ddebcdb0b22fa0e
+  metadata.gz: db802e6f2ac77bd0978de8a043b8a34488168e820e8b2e6ad3aca7033f43377b1524ccdee742077471486013d6f6e8607465b1fbaf68038dfb8d37d3f119915c
+  data.tar.gz: 33103fdeb0adf5816c3ffcdc23c4107eb52cc814ed904ae2b9d64f314d8fb88bbf2f0e837c0d4bd66781903710c7ffab770da166e5372eebe79d8522c3ace7d8

data/CHANGELOG.md

@@ -1,5 +1,67 @@
 # sendly (Ruby)
 
+## 3.38.0
+
+### Minor Changes
+
+- **Every `POST` now sends an `Idempotency-Key` header.** The client generates one key per logical request (`sendly-ruby-retry-<uuid>`) and holds it across its own retries, so a request that already reached the server before a rate-limit retry is recognised as a repeat instead of being executed a second time. The server records a key only once the first attempt has finished, so this narrows the duplicate-send window rather than closing it: a retry that fires while the original is still running is not seen as a repeat. No code change is needed to get this. To extend the same protection across process restarts or your own retry loop, supply the key yourself:
+
+  ```ruby
+  client.messages.send(
+    to: "+15551234567",
+    text: "Your order shipped",
+    idempotency_key: "order-4821-shipped"
+  )
+  ```
+
+  Repeating a request with the same key inside 24 hours returns the original response instead of sending again. `idempotency_key:` is accepted on `messages.send` (the SMS, WhatsApp and RCS branches alike), `messages.send_group`, `messages.schedule`, `messages.send_batch`, and on `client.post` for any call you assemble by hand. A key must be 1 to 255 printable ASCII characters. Surrounding whitespace is trimmed, an empty or whitespace-only key is treated as if you passed nothing, and anything else raises `Sendly::ValidationError` before a request leaves the process.
+
+- **How keys behave across retries.** On a rate-limit retry the same key is reused. On a 5xx retry an auto-generated key is swapped for a fresh one, because the server responded, so the outcome is known and the retry should be a fresh attempt rather than a repeat of the failed one. The server does not record a 5xx against a key either. A key you supplied is never swapped, which is the whole point of supplying one. `messages.send_batch` is the deliberate exception: it sends no auto-generated key, because the batch endpoint already dedupes header-less retries by hashing the send itself and an auto key would step around that safety net. A key you pass to `send_batch` yourself is still sent. Worth knowing: this client raises `Sendly::TimeoutError` on a timeout rather than retrying, so a timeout is exactly the case where you should pass your own `idempotency_key:` before retrying by hand.
+
+- **Multipart uploads carry a key as well.** `media.upload`, the enterprise verification-document upload, and `business_upgrade.start` / `business_upgrade.resubmit` now attach an auto-generated `Idempotency-Key` to their uploads, so a retried document upload is far less likely to land twice. These methods generate the key internally and do not take an `idempotency_key:` argument yet.
+
+- **Templates were addressing a path the API does not serve. They now work.** Every method on `client.templates` other than `generate` pointed at `/verify/templates...`, which is not registered at any version of the API, so `list`, `get`, `create`, `update`, `delete` and `publish` could only ever raise `Sendly::NotFoundError`. They now address `/api/v1/templates`, which is served, and have been exercised end to end against production. If you wrote code against this resource and concluded it was broken, note carefully that it is live now: calls that previously failed without side effects will really create, edit, publish and delete templates.
+
+- **`Sendly::Template` now mirrors what the API actually returns**, and templates have a draft/published lifecycle. The response body field is `text`, not `body`, and a template carries `status` (`"draft"` or `"published"`, see the new `Sendly::Template::STATUSES`), `version`, `published_at`, `is_preset` and `preset_slug`. New templates are always created as drafts; call `publish` to make one usable. Only drafts can be edited, so an `update` on a published template is rejected by the API, and preset templates cannot be edited at all.
+
+  ```ruby
+  t = client.templates.create(name: "Order shipped", text: "Hi {{name}}, order {{order_id}} has shipped!")
+  t.status          # => "draft"
+  client.templates.publish(t.id)
+  client.templates.list[:templates].each { |x| puts "#{x.name}: #{x.status}" }
+  ```
+
+- **Template members that disappeared in the reshape are back, and deprecated.** If your editor or `ruby -w` starts pointing at these, this is why:
+  - `Template#body` is an alias of `#text`. Use `#text`.
+  - `Template#type` is derived from `#is_preset` and still returns `"preset"` or `"custom"`. Use `#is_preset` or `#preset?`. `Template::TYPES` is kept for the same reason.
+  - `Template#is_published` is derived from `#status`. Use `#status` or `#published?`.
+  - `Template#locale` is **always `nil`** and `Template#is_default` is **always `false`**. These are not deprecated in favour of anything: templates are not scoped by locale and the API has no concept of a default template, so it returns no such fields. There is no replacement. Keep per-locale wording in separate templates.
+
+  `Template#to_h` includes all of the above alongside the current fields, so hashes built from it keep their old keys.
+
+- **Deprecated template keyword arguments now raise instead of lying.** `templates.list` accepts `limit:`, `type:` and `locale:` again, and `templates.create` / `templates.update` accept `body:`, `locale:` and `is_published:` again, but the ones the API cannot honour raise `ArgumentError` with an explanation rather than silently doing nothing:
+  - `list(limit:)` and `list(type:)` raise: the list route returns every visible template in one response and neither paginates nor filters. Slice the returned array, or select over it with `Template#preset?` / `#custom?`. `list` still returns a `:pagination` key so existing destructuring does not blow up, but it is always `nil`.
+  - `locale:` raises everywhere it is accepted.
+  - `create(is_published: true)` and `update(is_published: true)` raise, and point you at `publish(id)`. `is_published: false` is accepted as a no-op, since templates are created as drafts and an update never changes status.
+  - `body:` on `create` and `update` is accepted and sent as `text`. Prefer `text:`.
+
+- **API key management was pointed at routes that do not exist.** `account.api_keys`, `account.api_key(id)` and `account.api_key_usage(id)` requested `/keys...`, which the versioned API does not serve, so they returned 404 no matter what. They now use `/account/keys...`. `account.api_keys` also unwraps the `keys` envelope the API returns, which it previously did not, so it now gives you the `Sendly::ApiKey` array its signature always promised.
+
+- **`account.revoke_api_key` could never revoke anything.** It sent `DELETE /account/keys/:id`, and that path is registered for `GET` only, so every revocation failed. It now sends `PATCH /account/keys/:id/revoke`, which is the verb the server accepts, takes an optional `reason:` recorded on the key's audit trail, and returns the `{ "id", "name", "revoked", "revokedAt" }` hash from the API instead of nothing. Treat this as live: code that has been calling it fruitlessly will now actually revoke keys.
+
+  ```ruby
+  client.account.revoke_api_key("key_abc123", reason: "rotated")
+  ```
+
+- **`account.transactions` raised `TypeError` on every call.** The endpoint returns `{ "transactions": [...] }` and the SDK mapped over that hash directly, so it tried to index an array with a string and blew up before you saw any data. It now unwraps the envelope and returns `Sendly::CreditTransaction` objects, or an empty array for an account with no history. One caveat: `offset:` is still accepted by the method but the endpoint ignores it, so it has no effect. `limit:` works and the server caps it at 100 (50 when omitted).
+
+- **Not fixed, so you are not left hunting:** `templates.unpublish` and `templates.clone` now address `/api/v1/templates/:id/unpublish` and `/api/v1/templates/:id/clone`, but the versioned API serves neither route, so both still fail with a 404. Their docs say so. To retire a published template today, create and publish a replacement and delete the old one; to copy one, read it with `get` and pass its `text` to `create`. Separately, `account.create_api_key` still fails with a 400: the API requires a `type` of `"test"` or `"live"` and the SDK does not send one. Mint keys from the dashboard until that is fixed.
+
+### Patch Changes
+
+- **`faraday` and `faraday-retry` are deprecated dependencies.** The client is built on Ruby's standard-library `net/http` and has not used Faraday at runtime for some time. Both gems stay declared in the gemspec so that this minor release does not pull a dependency out from under anyone resolving it transitively, but they are unused and are slated for removal in the next major version. The README no longer lists Faraday as a requirement.
+- The gem's packaged file list is now an explicit manifest plus `lib/**/*.rb` and `examples/**/*.rb`, rather than a `git ls-files` shell-out. The contents are unchanged, but building the gem from a source tree that is not a git checkout now produces the same gem instead of an empty one.
+
 ## 3.33.0
 
 ### Minor Changes
@@ -87,7 +149,7 @@
 
 - `/api/v1/enterprise/workspaces/:id/verification/submit` now returns specific missing-field errors (e.g. `"Missing required fields: website"`) instead of listing every required field whether present or not.
 - Endpoint accepts both flat and `{ verification: {...} }` wrapped shapes (matches `/enterprise/provision`).
-- `use_case` validation expanded from 23 entries to the full 43-value Telnyx enum.
+- `use_case` validation expanded from 23 entries to the full 43-value carrier use-case enum.
 
 ## 3.29.0
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.37.0)
+    sendly (3.38.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 
@@ -74,7 +74,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
     uri (1.1.1)
-    webmock (3.26.2)
+    webmock (3.26.4)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -330,13 +330,13 @@ puts "Total: #{credits['balance']} credits"
 # View credit transaction history
 transactions = client.account.transactions
 transactions.each do |tx|
-  puts "#{tx['type']}: #{tx['amount']} credits - #{tx['description']}"
+  puts "#{tx.type}: #{tx.amount} credits - #{tx.description}"
 end
 
 # List API keys
 keys = client.account.api_keys
 keys.each do |key|
-  puts "#{key['name']}: #{key['prefix']}*** (#{key['type']})"
+  puts "#{key.name}: #{key.prefix} (#{key.type})"
 end
 
 # Create a new API key
@@ -457,20 +457,17 @@ client.campaigns.delete(campaign.id)
 Reusable message templates with variables. AI can also draft one for you.
 
 ```ruby
-# Create / list / get
+# Create / list / get. New templates start as drafts; publish to lock one for use.
 template = client.templates.create(
   name: "Order shipped",
-  body: "Hi {{name}}, order #{{order_id}} has shipped!",
-  is_published: true
+  text: "Hi {{name}}, order {{order_id}} has shipped!"
 )
-client.templates.list(type: "custom")[:templates].each { |t| puts t.name }
+client.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
 t = client.templates.get(template.id)
 
-# Update, publish/unpublish, clone
-client.templates.update(template.id, body: "Hi {{name}}, your order is on the way!")
+# Update (drafts only), publish, delete
+client.templates.update(template.id, text: "Hi {{name}}, your order is on the way!")
 client.templates.publish(template.id)
-client.templates.unpublish(template.id)
-client.templates.clone(template.id, name: "Order shipped (copy)")
 client.templates.delete(template.id)
 
 # Generate a template with AI
@@ -745,6 +742,177 @@ status = client.links.update(link.code, disabled: true)
 puts status.disabled?
 ```
 
+## WhatsApp
+
+Connect a number you own to WhatsApp, create Meta-reviewed message
+templates, and send via `client.messages.send(channel: "whatsapp", ...)`.
+Connecting is a one-time $19 setup (no monthly fee) and always ends with a
+human step: the signup returns a connect URL a person must open in a
+browser and log in with Facebook to link their WhatsApp Business Account.
+
+Free-form text and media only deliver inside a 24-hour customer-service
+window (opened by the recipient messaging you); an approved template works
+anytime. Templates are reviewed by Meta (typically 24-48h) and categorized
+as authentication, utility, or marketing — pricing follows the category and
+destination country. Note: Meta has paused marketing template delivery to
+US (+1) numbers.
+
+```ruby
+# 1. Connect a number ($19 one-time; a human must open the connect URL)
+signup = client.whatsapp.signup.create(phone_number: "+15559876543")
+puts "Have your user open: #{signup.connect_url}"
+
+# 2. Poll until active
+status = client.whatsapp.signup.get(signup.id)
+puts status.failure_reasons if status.failed?
+
+# List your connected senders
+client.whatsapp.senders.list[:senders].each do |s|
+  puts "#{s.phone_number} (#{s.display_name || 'no name yet'}) — #{s.status}"
+end
+
+# Read and update a sender's business profile (what recipients see when
+# they open your details in WhatsApp)
+profile = client.whatsapp.senders.get_profile("+15559876543")
+puts profile.display_name
+puts profile.about
+
+client.whatsapp.senders.update_profile(
+  "+15559876543",
+  about: "Fresh roasted coffee, delivered.",               # max 139 chars
+  description: "Small-batch roaster shipping nationwide.", # max 512 chars
+  website: "https://acme.example"
+)
+
+# 3. Create a template (Meta reviews it, usually 24-48h)
+template = client.whatsapp.templates.create(
+  sender: "+15559876543",
+  name: "order_shipped",
+  language: "en_US",
+  category: "UTILITY",
+  body: "Hi {{1}}, your order {{2}} has shipped!",
+  examples: { "1" => "Sam", "2" => "#4821" }
+)
+puts template.status  # "PENDING"
+
+# List, edit-and-resubmit (the recovery path for rejections), or delete
+client.whatsapp.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
+client.whatsapp.templates.update(template.id, body: "Hi {{1}}, order {{2}} is on its way!",
+                                              examples: { "1" => "Sam", "2" => "#4821" })
+client.whatsapp.templates.delete(template.id)
+
+# 4. Send — free-form inside an open 24h window, template anytime
+window = client.whatsapp.window(from: "+15559876543", to: "+15551234567")
+if window.open?
+  client.messages.send(
+    channel: "whatsapp",
+    to: "+15551234567",
+    from: "+15559876543",
+    text: "Your table is ready!"
+  )
+else
+  message = client.messages.send(
+    channel: "whatsapp",
+    to: "+15551234567",
+    from: "+15559876543",
+    template: {
+      name: "order_shipped",
+      language: "en_US",
+      variables: { "1" => "Acme Inc", "2" => "#4821" }
+    }
+  )
+  puts message.whatsapp.kind  # "template"
+end
+
+# Media with a caption (also window-bound; one attachment per message)
+client.messages.send(
+  channel: "whatsapp",
+  to: "+15551234567",
+  from: "+15559876543",
+  text: "Here is your receipt",
+  media_urls: ["https://example.com/receipt.pdf"]
+)
+```
+
+## RCS
+
+Send branded rich messages — text with suggested replies and actions, or
+rich cards with an image and buttons — through your workspace's RCS agent
+by passing `channel: "rcs"` to `client.messages.send`. Delivery is
+per-recipient: not every device or network supports RCS. Text sends fall
+back to plain SMS automatically (billed as SMS) unless you disable the
+fallback; rich cards have no SMS form and only deliver to RCS-capable
+recipients.
+
+The RCS channel is being rolled out gradually and is not yet generally
+available; until it is enabled for your account the endpoints read as
+absent and calls raise `Sendly::NotFoundError` (HTTP 404). RCS sends and
+capability checks require a live API key. RCS agents are registered by
+Sendly for your brand — contact support to set one up.
+
+```ruby
+# Discover your RCS agents ("testing" reaches invited test devices only;
+# "approved" reaches everyone). Pass agent_id on sends and capability
+# checks when your workspace has more than one agent.
+client.rcs.agents.list[:agents].each do |a|
+  puts "#{a.name} — #{a.status}#{a.sendable? ? ' (sendable)' : ''}"
+end
+
+# Pre-flight: can this recipient receive RCS?
+capability = client.rcs.capability(to: "+15551234567")
+puts capability.capable? ? "RCS" : "would fall back to SMS"
+
+# Text with suggested replies and actions. Nested suggestion and card
+# hashes are passed through verbatim, so they use the camelCase keys the
+# API expects.
+message = client.messages.send(
+  channel: "rcs",
+  to: "+15551234567",
+  text: "Your order has shipped! Want live updates?",
+  suggestions: [
+    { reply: { text: "Yes, notify me", postbackData: "notify_yes" } },
+    { action: { text: "Track order", postbackData: "track",
+                url: "https://acme.example/orders/4821" } }
+  ]
+)
+
+# The response discloses which channel delivered
+puts message.channel # "rcs", or "sms" when it fell back
+if message.fell_back?
+  # Delivered as plain SMS (billed as SMS). Suggestions have no SMS form
+  # and were dropped — message.rcs.suggestions_dropped is true.
+else
+  puts message.rcs.kind       # "text" or "card"
+  puts message.rcs.agent_name # the brand name recipients see
+end
+
+# Rich card (RCS-capable recipients only — cards have no SMS form)
+client.messages.send(
+  channel: "rcs",
+  to: "+15551234567",
+  card: {
+    title: "Spring collection",
+    description: "New arrivals are in - take a look.",
+    mediaUrl: "https://example.com/spring.jpg", # public JPEG, PNG, or GIF
+    orientation: "vertical",                    # or "horizontal"
+    suggestions: [
+      { action: { text: "Shop now", postbackData: "shop",
+                  url: "https://acme.example/spring" } }
+    ]
+  }
+)
+
+# Opt out of the SMS fallback — the send raises Sendly::ValidationError
+# (HTTP 422 rcs_not_supported_for_recipient) when the recipient can't
+# receive RCS
+client.messages.send(
+  channel: "rcs",
+  to: "+15551234567",
+  text: "RCS or nothing",
+  fallback_to_sms: false
+)
+```
+
 ## Error Handling
 
 ```ruby
@@ -893,7 +1061,8 @@ Full enterprise docs: [sendly.live/docs/enterprise](https://sendly.live/docs/ent
 ## Requirements
 
 - Ruby 3.0+
-- Faraday 2.0+
+
+The client is built on Ruby's standard-library `net/http` and does not use Faraday at runtime. The gemspec still declares `faraday` and `faraday-retry` so this release does not drop a runtime dependency that callers may be resolving transitively. Both are unused and are slated for removal in the next major version.
 
 ## License
 

data/lib/sendly/account_resource.rb

@@ -39,15 +39,15 @@ module Sendly
       params[:offset] = offset if offset
 
       response = @client.get("/credits/transactions", params)
-      response.map { |data| CreditTransaction.new(data) }
+      (response["transactions"] || []).map { |data| CreditTransaction.new(data) }
     end
 
     # List API keys for the account
     #
     # @return [Array<Sendly::ApiKey>]
     def api_keys
-      response = @client.get("/keys")
-      response.map { |data| ApiKey.new(data) }
+      response = @client.get("/account/keys")
+      (response["keys"] || []).map { |data| ApiKey.new(data) }
     end
 
     # Get a specific API key by ID
@@ -55,7 +55,7 @@ module Sendly
     # @param key_id [String] API key ID
     # @return [Sendly::ApiKey]
     def api_key(key_id)
-      response = @client.get("/keys/#{key_id}")
+      response = @client.get("/account/keys/#{key_id}")
       ApiKey.new(response)
     end
 
@@ -64,7 +64,7 @@ module Sendly
     # @param key_id [String] API key ID
     # @return [Hash] Usage statistics
     def api_key_usage(key_id)
-      @client.get("/keys/#{key_id}/usage")
+      @client.get("/account/keys/#{key_id}/usage")
     end
 
     # Create a new API key
@@ -88,11 +88,15 @@ module Sendly
     # Revoke an API key
     #
     # @param key_id [String] API key ID to revoke
-    # @return [void]
-    def revoke_api_key(key_id)
+    # @param reason [String, nil] Optional reason recorded on the key's audit trail
+    # @return [Hash] +{ "id" => ..., "name" => ..., "revoked" => true, "revokedAt" => ... }+
+    def revoke_api_key(key_id, reason: nil)
       raise ArgumentError, "API key ID is required" if key_id.nil? || key_id.empty?
 
-      @client.delete("/account/keys/#{key_id}")
+      body = {}
+      body[:reason] = reason if reason
+
+      @client.patch("/account/keys/#{key_id}/revoke", body)
     end
 
     # Rotate an API key.

data/lib/sendly/business_upgrade_resource.rb

@@ -383,6 +383,8 @@ module Sendly
       req["User-Agent"] = "sendly-ruby/#{Sendly::VERSION}"
       req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
       req["X-Organization-Id"] = @client.organization_id if @client.organization_id
+      # Single-use auto key (this path has no retry loop).
+      req["Idempotency-Key"] = @client.generate_idempotency_key
       req.body = body_parts.join
 
       begin

data/lib/sendly/client.rb

@@ -178,6 +178,20 @@ module Sendly
       @links ||= LinksResource.new(self)
     end
 
+    # Access the WhatsApp resource
+    #
+    # @return [Sendly::WhatsAppResource]
+    def whatsapp
+      @whatsapp ||= WhatsAppResource.new(self)
+    end
+
+    # Access the RCS resource
+    #
+    # @return [Sendly::RcsResource]
+    def rcs
+      @rcs ||= RcsResource.new(self)
+    end
+
     # Make a GET request
     #
     # @param path [String] API path
@@ -189,11 +203,21 @@ module Sendly
 
     # Make a POST request
     #
+    # Every POST carries an Idempotency-Key header. By default the client
+    # generates one per logical request ("sendly-ruby-retry-<uuid>") so the
+    # server can dedupe the client's own retries; pass +idempotency_key+ to
+    # supply your own (1-255 printable ASCII characters) and extend that
+    # protection across process restarts, or +auto_idempotency_key: false+
+    # to skip auto-generation for endpoints that dedupe by other means.
+    #
     # @param path [String] API path
     # @param body [Hash] Request body
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
+    # @param auto_idempotency_key [Boolean] Auto-generate a key when none is supplied (default: true)
     # @return [Hash] Response body
-    def post(path, body = {})
-      request(:post, path, body: body)
+    def post(path, body = {}, idempotency_key: nil, auto_idempotency_key: true)
+      request(:post, path, body: body, idempotency_key: idempotency_key,
+                           auto_idempotency_key: auto_idempotency_key)
     end
 
     # Make a PATCH request
@@ -257,11 +281,15 @@ module Sendly
     # @param file [String, IO] File path or IO object
     # @param content_type [String] MIME type of the file
     # @param filename [String] Name for the uploaded file
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def post_multipart(path, file, content_type: "image/jpeg", filename: "upload.jpg")
+    def post_multipart(path, file, content_type: "image/jpeg", filename: "upload.jpg", idempotency_key: nil)
       uri = build_uri(path, {})
       http = build_http(uri)
 
+      explicit_key = normalize_idempotency_key(idempotency_key)
+      key = explicit_key || generate_idempotency_key
+
       boundary = "SendlyRuby#{SecureRandom.hex(16)}"
 
       file_data = file.is_a?(String) ? File.binread(file) : file.read
@@ -283,6 +311,7 @@ module Sendly
 
       attempt = 0
       begin
+        req["Idempotency-Key"] = key
         response = http.request(req)
         handle_response(response)
       rescue Net::OpenTimeout, Net::ReadTimeout
@@ -299,6 +328,10 @@ module Sendly
       rescue ServerError => e
         attempt += 1
         if attempt <= max_retries
+          # A 5xx response may be cached under the key server-side, so an
+          # auto-generated key is rotated to let the retry re-execute.
+          # Caller-supplied keys are never rotated.
+          key = generate_idempotency_key if explicit_key.nil?
           sleep(2 ** attempt)
           retry
         end
@@ -306,6 +339,13 @@ module Sendly
       end
     end
 
+    # Generate an idempotency key for a logical request. Reused across retry
+    # attempts so the server can recognize a retry of a POST that already
+    # reached it and return the original result instead of executing again.
+    def generate_idempotency_key
+      "sendly-ruby-retry-#{SecureRandom.uuid}"
+    end
+
     private
 
     def validate_api_key!
@@ -316,13 +356,19 @@ module Sendly
       end
     end
 
-    def request(method, path, params: {}, body: nil, unversioned: false)
+    def request(method, path, params: {}, body: nil, unversioned: false, idempotency_key: nil,
+                auto_idempotency_key: true)
       uri = build_uri(path, params, unversioned: unversioned)
       http = build_http(uri)
       req = build_request(method, uri, body)
 
+      explicit_key = normalize_idempotency_key(idempotency_key)
+      key = explicit_key
+      key = generate_idempotency_key if key.nil? && method == :post && auto_idempotency_key
+
       attempt = 0
       begin
+        req["Idempotency-Key"] = key if key
         response = http.request(req)
         handle_response(response)
       rescue Net::OpenTimeout, Net::ReadTimeout
@@ -339,6 +385,10 @@ module Sendly
       rescue ServerError => e
         attempt += 1
         if attempt <= max_retries
+          # A 5xx response may be cached under the key server-side, so an
+          # auto-generated key is rotated to let the retry re-execute.
+          # Caller-supplied keys are never rotated.
+          key = generate_idempotency_key if key && explicit_key.nil?
           sleep(2 ** attempt) # Exponential backoff
           retry
         end
@@ -346,6 +396,23 @@ module Sendly
       end
     end
 
+    # Validate and normalize a caller-supplied idempotency key. Empty and
+    # whitespace-only values are treated as absent (auto-generation still
+    # applies); invalid values fail fast instead of surfacing later as an
+    # API error.
+    def normalize_idempotency_key(key)
+      return nil if key.nil?
+
+      trimmed = key.to_s.strip
+      return nil if trimmed.empty?
+
+      if trimmed.length > 255 || !trimmed.match?(/\A[\x20-\x7E]+\z/)
+        raise ValidationError, "Idempotency key must be 1-255 printable ASCII characters"
+      end
+
+      trimmed
+    end
+
     def build_uri(path, params, unversioned: false)
       base = unversioned ? api_origin : base_url
       url = "#{base}#{path}"

data/lib/sendly/enterprise.rb

@@ -505,6 +505,8 @@ module Sendly
       req["User-Agent"] = "sendly-ruby/#{Sendly::VERSION}"
       req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
       req["X-Organization-Id"] = @client.organization_id if @client.organization_id
+      # Single-use auto key (this path has no retry loop).
+      req["Idempotency-Key"] = @client.generate_idempotency_key
       req.body = body_parts.join
 
       response = http.request(req)