mailblastr 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a028b42e26c044b29d184717824743d50dc909638a11f26182373c29f39a801e
-  data.tar.gz: 9bc74f8a2d2dd6b8c795bde5c92e6fa3490e9e9aa4fe14ff87cca1d3ca3fe710
+  metadata.gz: 2f6ca9c697ddc14eea6b2e355749bfc000d513224e6afe32e04796b3c1cf954d
+  data.tar.gz: d0522dd6dfd919babce3fac4324e1adaafc7a9dff6b801815512a53a3d99147e
 SHA512:
-  metadata.gz: e9c966eea358f8d09c5f2087a7f209e9d78d642ccdff1a8e8a38b510ed0df4b32074474cfa06d8b4dc14743af868878f837d249be2303c3c53b017ebb8f3c236
-  data.tar.gz: '082c972bf7ed332f0b6b1ae5d851718ec0dab54c9ca2b9746da27047cb263bd19640a03b77f3ee7de18b618fde84d00adbeae9b8fa0936536b065c97c7c1a367'
+  metadata.gz: cd2e5834d366d29d01a797ef11db73cc074181084d76be044a2223684d76f0f1935c75df81b449c0f344234a96b9e31d4a941a2e4ff86e4b518c5727c53e7f5e
+  data.tar.gz: 977c69e7fcee5e616cc1e55166279d8b784bedeffb45e9d980e288cc6cdbb3a632556ff23a8e73c7412a22e5094413900e1e164cb7a098e0bc6e526a495b88db

data/README.md

@@ -104,6 +104,7 @@ That means `domain` (the sending domain, e.g. `"yourdomain.com"` — one of your
 Mailblastr::Emails.send({ from: from, to: to, subject: subject, html: html })
 Mailblastr::Emails.list({ limit: 20, after: cursor })   # cursor pagination
 Mailblastr::Emails.list({ status: "bounced", search: "acme.com" }) # filters
+Mailblastr::Emails.list({ folder: "scheduled" }) # one of outbox | sent | scheduled | failed — any other value is rejected (422)
 Mailblastr::Emails.sources                              # per-campaign/automation send metrics
 Mailblastr::Emails.get(email_id)
 Mailblastr::Emails.list_attachments(email_id)
@@ -407,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
 
@@ -420,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/contacts.rb

@@ -90,6 +90,9 @@ module Mailblastr
       #   Contacts.batch({ audience_id: "aud_1", contacts: [{ email: "a@b.com" }], on_conflict: "skip" })
       def batch(params)
         audience_id = Client.opt(params, :audience_id)
+        # "" is truthy in Ruby but names no audience — treat it as absent and
+        # take the flat route, matching the other MailBlastr SDKs.
+        audience_id = nil if audience_id == ""
         query = {}
         on_conflict = Client.opt(params, :on_conflict)
         query[:on_conflict] = on_conflict if on_conflict

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

@@ -27,10 +27,16 @@ module Mailblastr
 
       # List sent emails (trimmed list items) — cursor pagination plus optional
       # server-side filters: `campaign_id`, `automation_id`, `source`
-      # ("individual"), `domain_id`, `status` (matched case-insensitively
-      # against the row's `last_event`) and `search` (recipients, subject and
-      # sender). `q` is the server's alias for `search`, honoured only when
-      # `search` is absent. GET /emails
+      # ("individual" for all one-off sends with no campaign/automation origin,
+      # "api" for one-off sends made with an API key — which also covers mail
+      # sent before the send origin was recorded — or "dashboard" for one-off
+      # mail composed in the dashboard: the composer and inbox replies/forwards;
+      # honoured only when neither `campaign_id` nor `automation_id` is
+      # supplied), `domain_id`, `status` (matched case-insensitively
+      # against the row's `last_event`), `folder` (one of "outbox", "sent",
+      # "scheduled" or "failed" — any other value is rejected with a 422) and
+      # `search` (recipients, subject and sender). `q` is the server's alias
+      # for `search`, honoured only when `search` is absent. GET /emails
       def list(params = {})
         query = Client.pagination(params).merge(
           Client.filters(params, :campaign_id, :automation_id, :source, :domain_id, :status, :search, :q, :folder)
@@ -38,8 +44,11 @@ module Mailblastr
         Client.request(:get, "/emails", query: query)
       end
 
-      # Per-source send metrics, one row per campaign / automation / individual
-      # origin. Not paginated. GET /emails/sources
+      # Per-source send metrics, one row per origin. `kind` is "campaign",
+      # "automation", "api" (one-off API-key sends, including mail sent before
+      # the send origin was recorded) or "individual" (dashboard-composed
+      # one-offs); `id`, `name`, `subject` and `status` are null for both the
+      # "api" and "individual" rows. Not paginated. GET /emails/sources
       def sources
         Client.request(:get, "/emails/sources")
       end
@@ -125,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.0"
+  VERSION = "5.2.0"
 end

metadata

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