mailblastr 5.1.1 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4827370704c9533943a763c3797f16b472f80655940a911111abff606769fe71
-  data.tar.gz: 9a924fc0cc8bb4d7d29c78ef6a5b3e1290c82139dee33ea05fe0009b504b2a14
+  metadata.gz: 2f6ca9c697ddc14eea6b2e355749bfc000d513224e6afe32e04796b3c1cf954d
+  data.tar.gz: d0522dd6dfd919babce3fac4324e1adaafc7a9dff6b801815512a53a3d99147e
 SHA512:
-  metadata.gz: 111d3d1c97ef0a2e4cf398b90327b48ac389de59f1dad3b80f8df34e16811f32385c2502c98a8672176339bdd7c5056a3467a8ed5a59f8dc14646803317c0dfc
-  data.tar.gz: 4ddd8faaba6b557b100c7177f15b9bbcdbf06df0a413088763ad8b174dc6f3fb6f69aac814445a7f8bd9dce1a4f22e2eed2ef324040de2503f63272e48db927b
+  metadata.gz: cd2e5834d366d29d01a797ef11db73cc074181084d76be044a2223684d76f0f1935c75df81b449c0f344234a96b9e31d4a941a2e4ff86e4b518c5727c53e7f5e
+  data.tar.gz: 977c69e7fcee5e616cc1e55166279d8b784bedeffb45e9d980e288cc6cdbb3a632556ff23a8e73c7412a22e5094413900e1e164cb7a098e0bc6e526a495b88db

data/README.md

@@ -408,7 +408,7 @@ The key must be **1–255 characters**, measured after the server trims it — 2
 
 Reusing a key replays the original response; reusing it with a *different* body is a 409 (`invalid_idempotent_request`), and a second request while the first is still in flight is a 409 (`concurrent_idempotent_requests`).
 
-Only `Emails.send` and `Batch.send` honour the header. Every other endpoint — including `Events.send` — accepts and forwards it but the API ignores it, so a retry there creates a second record. De-duplicate on your side instead.
+`Emails.send`, `Batch.send`, and received-email reply/forward honour the header. Every other endpoint — including `Events.send` — accepts and forwards it but the API ignores it, so a retry there creates a second record. De-duplicate on your side instead.
 
 ## Rate limits
 
@@ -421,3 +421,49 @@ Full docs: <https://www.mailblastr.com/docs>
 ## License
 
 MIT
+
+## Recovery and tracking contracts
+
+Use a stable, unique operation key for each intended send, batch, reply, or
+forward. Keep the same key and payload when recovering that operation. These
+are the supported idempotent send endpoints; events do not implement this
+header. Existing calls without options still work.
+
+```ruby
+Mailblastr::Emails::Receiving.reply(id, reply, idempotency_key: "reply-operation-1")
+Mailblastr::Emails::Receiving.forward(id, forward, idempotency_key: "forward-operation-1")
+health = Mailblastr::Domains.tracking_health(domain_id)
+```
+
+Automatic retries consider only 429/503. They stop on an original email `id`,
+positive `sent_count`, nonempty `sent` or `reserved`, or `batch_incomplete`.
+An ordinary rate limit can retry; a generic 503 can retry a read or a send with
+the same supported key. Other writes retry only documented pre-processing
+rejections (`service_unavailable`, `sending_service_unavailable`,
+`sending_configuration_unavailable`, `contacts_busy`, `contacts_timeout`).
+No network/body-read failure, 409, 422, or other 5xx is retried automatically.
+The default transport refuses redirects; a custom transport/client must enforce
+its own policy.
+
+On a failed or unconfirmed send, inspect `id` with the email retrieval method
+before creating another send. A 422 with an ID can identify an uncertain
+provider handoff; 422 does not always mean nothing happened. For interrupted
+batches, `sent` contains confirmed sends, `reserved` contains the original
+attempted prefix (including uncertain handoffs), and `unsent_count` counts the
+never-attempted tail. Do not resend the full batch or the reserved prefix under
+a new key. Reconcile original IDs first, then submit only known unattempted
+items as a new operation. Recovery fields remain available in the full error
+body as well as language-specific fields/accessors.
+
+Tracking health returns `custom_host`, `status` (`shared`, `ready`, or
+`unavailable`), and `checked_at`. Configure custom tracking through the domain
+API and check health before relying on it. A healthy endpoint cannot guarantee
+an open event: recipients may block images, and coupon redemption alone is not
+proof that the tracking pixel loaded. SDKs preserve supplied HTML/text and do
+not infer opens or rewrite editor spacing.
+
+Campaign cancellation also stops pending follow-ups for an already-sent
+campaign while retaining its sent history. Permanent received-email deletion
+acknowledges a durable cleanup request; attachment/object cleanup can finish
+asynchronously. Retrying that deletion is safe; it cannot be undone after the
+purge request is accepted.

data/lib/mailblastr/client.rb

@@ -19,9 +19,8 @@ module Mailblastr
       delete: Net::HTTP::Delete
     }.freeze
 
-    # Only 429 and 503 are safe to retry automatically: the server guarantees
-    # it did NOT apply the request, so a retry cannot duplicate a non-idempotent
-    # side effect (e.g. sending an email twice). Everything else propagates.
+    # Only 429/503 are candidates; retry_allowed? also checks progress and
+    # whether a write was rejected before processing or protected by a key.
     RETRYABLE_STATUSES = [429, 503].freeze
 
     # Upper bound (seconds) on any single backoff wait.
@@ -30,7 +29,7 @@ module Mailblastr
     # `Idempotency-Key` is stored in a VARCHAR(255) column, so the API accepts
     # 1-255 characters measured after it trims the value — 255, not 256 — and
     # answers anything else with 400 invalid_idempotency_key. Only
-    # POST /emails and POST /emails/batch read the header; every other endpoint
+    # POST /emails, POST /emails/batch, and received-email reply/forward read the header; every other endpoint
     # ignores it, so a retry there creates a second resource.
     #
     # Exposed for discoverability only: the SDK sends the key as given and lets
@@ -68,7 +67,7 @@ module Mailblastr
       loop do
         resp = deliver(req, uri)
         code = resp.code.to_i
-        return resp unless RETRYABLE_STATUSES.include?(code) && attempt < max
+        return resp unless RETRYABLE_STATUSES.include?(code) && attempt < max && retry_allowed?(req, uri, code, resp.body)
 
         wait = retry_after_seconds(response_header(resp, "Retry-After"))
         wait ||= [MAX_BACKOFF_SECONDS, 0.5 * (2**attempt)].min
@@ -77,6 +76,25 @@ module Mailblastr
       end
     end
 
+    def retry_allowed?(req, uri, status, raw)
+      body = begin
+        JSON.parse(raw.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+      body = {} unless body.is_a?(Hash)
+      return false if (body["id"].is_a?(String) && !body["id"].empty?) ||
+                      (body["sent_count"].is_a?(Numeric) && body["sent_count"].positive?) ||
+                      (body["sent"].is_a?(Array) && !body["sent"].empty?) ||
+                      (body["reserved"].is_a?(Array) && !body["reserved"].empty?) ||
+                      body["name"] == "batch_incomplete"
+      return true if status != 503 || %w[GET HEAD].include?(req.method)
+      return true if %w[service_unavailable sending_service_unavailable sending_configuration_unavailable contacts_busy contacts_timeout].include?(body["name"])
+
+      req.method == "POST" && !req["Idempotency-Key"].to_s.strip.empty? &&
+        %r{/emails(?:/batch|/receiving/[^/]+/(?:reply|forward))?\z}.match?(uri.path)
+    end
+
     # Wraps Kernel#sleep so tests can stub out the wait. Extracted so the
     # retry loop stays deterministic under test.
     def backoff_sleep(seconds)
@@ -114,6 +132,7 @@ module Mailblastr
           end
         end
 
+      return nil unless seconds.finite?
       seconds = 0.0 if seconds.negative?
       [seconds.to_f, MAX_BACKOFF_SECONDS].min
     end
@@ -172,7 +191,7 @@ module Mailblastr
         # `sent`/`sent_count` (see Mailblastr::Error).
         raise Mailblastr::Error.new(
           parsed["message"] || "Request failed with status #{code}",
-          status_code: parsed["statusCode"] || code,
+          status_code: code,
           error_name: parsed["name"] || "application_error",
           body: parsed
         )

data/lib/mailblastr/domains.rb

@@ -3,6 +3,11 @@
 module Mailblastr
   module Domains
     class << self
+      # HTTPS readiness; an unavailable host schedules server-side repair.
+      def tracking_health(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/tracking-health")
+      end
+
       # Register a sending domain. POST /domains
       def create(params)
         Client.request(:post, "/domains", body: params)

data/lib/mailblastr/emails.rb

@@ -134,14 +134,14 @@ module Mailblastr
 
         # Forward a received email. POST /emails/receiving/:id/forward
         #   Receiving.forward(id, { from: "you@yourdomain.com", to: "team@you.com" })
-        def forward(email_id, params)
-          Client.request(:post, "/emails/receiving/#{Client.path_escape(email_id)}/forward", body: params)
+        def forward(email_id, params, options = {})
+          Client.request(:post, "/emails/receiving/#{Client.path_escape(email_id)}/forward", body: params, options: options)
         end
 
         # Reply to a received email's sender, threaded into the conversation.
         # POST /emails/receiving/:id/reply
-        def reply(email_id, params)
-          Client.request(:post, "/emails/receiving/#{Client.path_escape(email_id)}/reply", body: params)
+        def reply(email_id, params, options = {})
+          Client.request(:post, "/emails/receiving/#{Client.path_escape(email_id)}/reply", body: params, options: options)
         end
 
         # Delete a received email. DELETE /emails/receiving/:id

data/lib/mailblastr/error.rb

@@ -50,6 +50,24 @@ module Mailblastr
       @error_name
     end
 
+    # Original email for a failed or unconfirmed send; inspect before resending.
+    def id
+      value = @body["id"]
+      value.is_a?(String) ? value : nil
+    end
+
+    # Reserved prefix, including uncertain sends. Never automatically resend it.
+    def reserved
+      value = @body["reserved"]
+      value.is_a?(Array) ? value : nil
+    end
+
+    # The never-attempted tail; distinct from uncertain reserved items.
+    def unsent_count
+      value = @body["unsent_count"]
+      value.is_a?(Integer) ? value : nil
+    end
+
     # The plan/quota cap this request hit, else nil. Carried by
     # plan_limit_reached, every *_quota_exceeded, contact_limit_reached and
     # ai_credits_exceeded — it says WHICH quota ran out, how much of it was

data/lib/mailblastr/events.rb

@@ -11,7 +11,7 @@ module Mailblastr
       # Identify the contact by `contact_id` OR `email`. Event names cannot
       # start with the reserved "mailblastr:" prefix.
       #
-      # NOTE: only POST /emails and POST /emails/batch honour `Idempotency-Key`.
+      # NOTE: only POST /emails, POST /emails/batch, and received-email reply/forward honour `Idempotency-Key`.
       # An `idempotency_key` passed here is still forwarded, but the server
       # ignores it, so a retry ingests a SECOND event and can enroll the contact
       # twice — de-duplicate on your side instead.

data/lib/mailblastr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailblastr
-  VERSION = "5.1.1"
+  VERSION = "5.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailblastr
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 5.2.0
 platform: ruby
 authors:
 - MailBlastr
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest