mailblastr 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b33c9cbe102716978dacde6713e4cc66e25164cb91b26a0272c1f44dbcd5fab9
-  data.tar.gz: cb3b4fa5e7ba5bc85266c6cb0108e6a4a555daaf749963284d6045709ff05536
+  metadata.gz: da4eac6f929de305deb6c395655cb2658cc1ac3ee7410355846092ff6b61f66a
+  data.tar.gz: 05bfee5848400946fef957671b8bf891916bda6b7847988c531f2d5995ecb58a
 SHA512:
-  metadata.gz: 480c2cff7e78425b91e649421aa0ca5f1e883188f29a4fe63b68618f68ed11cee752b7e251a30ed7f720377596af3f40cf68e1b5bf23042ed27999fc3a86e977
-  data.tar.gz: 337481b2dbd5dd2b4b788706d302ae028aa823e992804bd7681c42a696c087b479c79370e14a803493e0564a121f68c87560a60ed70e7238124599b839778b45
+  metadata.gz: 1d3cd0f0741e9e55d2b6f24f34f33add0b192d305f5834fb4d481dbd70a0aacbdd8d05d516ba8797aa3201360d491a2a22bd6929a7ffdbd7b9ae57ae45ed4bbb
+  data.tar.gz: 907b8ec4abe3920ba6e94c04587cfcb72f4692420f461504f391dd6c44bc75cda2e562df73fe05911c1b40fa1e79ea8b581c948c0f64dc1f4fabd86bec489c8b

data/README.md

@@ -54,6 +54,36 @@ rescue Mailblastr::Error => e
 end
 ```
 
+Branch on `e.name`, never on `e.message` — messages are sanitized server-side and may change. The same `name` can arrive with different HTTP statuses depending on the endpoint, so read `e.status_code` rather than assuming one. Common names: `missing_api_key` (401), `restricted_api_key` (401, the key lacks the scope), `invalid_api_key` (403), `validation_error` (422), `not_found` (404), `plan_limit_reached` (402), `daily_quota_exceeded` / `monthly_quota_exceeded` / `rate_limit_exceeded` (429).
+
+Some errors carry more than that envelope. The extras are readers on the error and are `nil` on an ordinary one:
+
+```ruby
+rescue Mailblastr::Error => e
+  # WHICH quota ran out, and what would clear it.
+  if (cap = e.limit)
+    cap["kind"]                    # => "emails_daily"
+    cap["used"], cap["limit"]      # => 100, 100
+    cap["period"]                  # => "24h"
+    cap.dig("next_plan", "name")   # => "Pro"
+  end
+
+  # Reputation gates: whether waiting helps, and until when.
+  if (rep = e.reputation)
+    rep["retryable"], rep["scope"], rep["retry_at"]
+  end
+
+  # A batch that failed part way through — do NOT resend these.
+  if (sent = e.sent)
+    puts "#{e.sent_count} already went out: #{sent.map { |s| s['id'] }.join(', ')}"
+  end
+end
+```
+
+`e.body` is the whole parsed error body, so a field newer than this SDK version is still reachable.
+
+Every request carries a `User-Agent` automatically — the API rejects requests without one with a 403 `validation_error`.
+
 ## Domain-first model
 
 MailBlastr is **domain-first**: each sending domain has its own pool of contacts. The same email address on two domains is two records with separate consent, so unsubscribes on one product never leak into another.
@@ -71,6 +101,8 @@ That means `domain` (the sending domain, e.g. `"yourdomain.com"` — one of your
 ```ruby
 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.sources                              # per-campaign/automation send metrics
 Mailblastr::Emails.get(email_id)
 Mailblastr::Emails.list_attachments(email_id)
 Mailblastr::Emails.get_attachment(email_id, attachment_id)
@@ -97,6 +129,7 @@ Mailblastr::Emails.send({
 
 ```ruby
 Mailblastr::Emails::Receiving.list
+Mailblastr::Emails::Receiving.addresses # per-address inbound stats
 Mailblastr::Emails::Receiving.get(id)
 Mailblastr::Emails::Receiving.list_attachments(id)
 Mailblastr::Emails::Receiving.get_attachment(id, attachment_id) # => raw bytes (String)
@@ -114,6 +147,8 @@ Mailblastr::Domains.get(id)
 Mailblastr::Domains.list
 Mailblastr::Domains.update(id, { click_tracking: true })
 Mailblastr::Domains.verify(id)
+Mailblastr::Domains.mx_check("yourdomain.com") # inspect live MX before enabling receiving
+Mailblastr::Domains.records_csv(id)            # => CSV text (String)
 Mailblastr::Domains.delete(id)
 
 # Claim a domain verified in another account
@@ -146,6 +181,11 @@ Mailblastr::Contacts.list({ audience_id: aud_id, segment_id: seg_id })
 Mailblastr::Contacts.batch({ audience_id: aud_id, contacts: [{ email: "a@b.com" }], on_conflict: "skip" })
 Mailblastr::Contacts.import({ audience_id: aud_id, csv: "email,company\na@b.com,Acme" })
 
+# CSV too big to inline (5 MB / 10,000 rows)? Upload it directly, then import by key.
+slot = Mailblastr::Contacts.import_upload({ audience_id: aud_id, filename: "list.csv", size: bytes })
+# PUT the file to slot["upload_url"], then:
+Mailblastr::Contacts.import({ audience_id: aud_id, storage_key: slot["storage_key"] })
+
 # Segments & topics per contact
 Mailblastr::Contacts.add_to_segment(contact_id, segment_id)
 Mailblastr::Contacts.remove_from_segment(contact_id, segment_id)
@@ -201,6 +241,7 @@ Mailblastr::Campaigns.send(campaign["id"])                                    #
 Mailblastr::Campaigns.send(campaign["id"], { scheduled_at: "2026-08-01T09:00:00Z" }) # or schedule
 Mailblastr::Campaigns.cancel(campaign["id"])
 Mailblastr::Campaigns.stats(campaign["id"])
+Mailblastr::Campaigns.engagement(campaign["id"]) # who opened / clicked / replied
 Mailblastr::Campaigns.ab(campaign["id"]) # A/B winner evaluation
 Mailblastr::Campaigns.get(campaign["id"])
 Mailblastr::Campaigns.list({ limit: 25 })
@@ -233,8 +274,12 @@ automation = Mailblastr::Automations.create({
 })
 
 Mailblastr::Automations.add_step(automation["id"], { type: "send_email", config: { template_id: tmpl_id } })
+Mailblastr::Automations.update_step(automation["id"], step_id, { config: { subject: "New subject" } })
 Mailblastr::Automations.update(automation["id"], { status: "enabled" })
 
+# Or describe the flow and let the server build the steps (automation must be stopped)
+Mailblastr::Automations.create_with_ai(automation["id"], { prompt: "Wait 2 days, then send the onboarding email" })
+
 # Fire a custom event — only yourdomain.com's automations are triggered
 Mailblastr::Events.send({
   event: "signup.completed",
@@ -243,13 +288,15 @@ Mailblastr::Events.send({
   payload: { plan: "pro" }
 })
 
-# Event definitions
+# Event definitions — schema types are "string", "number", "boolean" or "date".
+# Event names cannot start with the reserved "mailblastr:" prefix.
 Mailblastr::Events.create({ name: "signup.completed", schema: { plan: "string" } })
 Mailblastr::Events.list
+Mailblastr::Events.update(event_id, { schema: { plan: "string", seats: "number" } }) # name is immutable
 Mailblastr::Events.delete(event_id)
 
 # Inspect execution
-runs = Mailblastr::Automations.runs(automation["id"], { limit: 25 })
+runs = Mailblastr::Automations.runs(automation["id"], { limit: 25, status: ["failed"] })
 Mailblastr::Automations.get_run(automation["id"], runs["data"].first["id"])
 Mailblastr::Automations.delete_step(automation["id"], step_id)
 Mailblastr::Automations.stop(automation["id"])
@@ -261,7 +308,7 @@ Mailblastr::Automations.delete(automation["id"])
 ```ruby
 hook = Mailblastr::Webhooks.create({
   endpoint: "https://yourapp.com/hooks/mailblastr",
-  events: ["email.delivered", "email.bounced", "contact.unsubscribed"]
+  events: ["email.delivered", "email.bounced", "email.unsubscribed"]
 })
 hook["signing_secret"] # shown ONCE — store it
 
@@ -272,6 +319,15 @@ Mailblastr::Webhooks.test(hook["id"])
 Mailblastr::Webhooks.delete(hook["id"])
 ```
 
+Endpoints must be `https://` and must not resolve to a private address. Valid event names are `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.received`, `email.replied`, `email.unsubscribed`, `contact.created`, `contact.updated`, `contact.deleted`, `domain.created`, `domain.updated` and `domain.deleted`. Anything else is a 422.
+
+`Webhooks.test` returns HTTP 200 even when the delivery failed — it does not raise. The outcome is `result["ok"]`, with `result["status"]` (your endpoint's HTTP status, when it responded) and `result["error"]` (e.g. `"lookup_failed"`):
+
+```ruby
+result = Mailblastr::Webhooks.test(hook["id"])
+warn "test delivery failed: #{result['error']}" unless result["ok"]
+```
+
 ### Verifying deliveries
 
 `verify_signature` checks the Svix-style HMAC-SHA256 signature locally (no HTTP request). Pass the **exact raw request body** — re-serializing parsed JSON breaks the signature.
@@ -296,9 +352,7 @@ Pass `tolerance: 0` to skip the timestamp freshness check (default 300 seconds).
 ## API keys, Logs & Polls
 
 ```ruby
-Mailblastr::ApiKeys.create({ name: "CI", permission: "sending_access" })
-Mailblastr::ApiKeys.list
-Mailblastr::ApiKeys.delete(key_id)
+Mailblastr::ApiKeys.list # `token` is the 8-character display prefix, never the secret
 
 Mailblastr::Logs.list({ limit: 100, method: "POST", status: 429 })
 Mailblastr::Logs.get(log_id)
@@ -307,22 +361,49 @@ Mailblastr::Polls.list
 Mailblastr::Polls.get(email_id) # aggregated answer breakdown
 ```
 
+`Mailblastr::ApiKeys.list` is the whole API-key surface: the SDK deliberately
+exposes no method to create, re-scope or revoke a key. Key lifecycle belongs to
+a signed-in dashboard session, and the API enforces it — `POST /api-keys`,
+`PATCH /api-keys/:id` and `DELETE /api-keys/:id` answer `403 dashboard_only` to
+any API-key caller, whatever its permission. That is the point: a key that leaks
+cannot mint itself a replacement, widen its own access, or revoke the keys you
+would use to shut it off. Create and revoke keys at
+[mailblastr.com](https://www.mailblastr.com).
+
 ## Pagination
 
 `list` methods accept cursor pagination — `{ limit:, after:, before: }` — appended as a query string:
 
 ```ruby
-Mailblastr::Campaigns.list({ limit: 25, after: "cursor_abc" })
+page = Mailblastr::Campaigns.list({ limit: 25, after: "cursor_abc" })
+page["object"]   # => "list"
+page["has_more"] # => true when more rows exist beyond this page
+page["data"]     # => [...]
 ```
 
+`limit` is an integer between 1 and 100 (default 20); `after` and `before` are item ids and cannot be combined. An unknown cursor returns an empty page, not an error. There is no `total` and no `next_cursor` — page forward with the last `data` entry's `id` as `after`.
+
+Defaults differ per endpoint. `GET /templates`, `/webhooks`, `/audiences`, `/automations`, `/events` and `/automations/:id/runs` cap an unpaginated call at 20 rows, while `/domains`, `/api-keys`, `/topics`, `/campaigns`, `/contacts`, `/contact-properties`, `/segments` and `/polls` return the whole collection when you pass neither `limit` nor a cursor. Always pass `limit` if you depend on page size.
+
 ## Idempotency
 
-Pass an idempotency key to safely retry a create (24h window):
+Pass an idempotency key to safely retry a send.
 
 ```ruby
 Mailblastr::Emails.send(payload, { idempotency_key: "order-123" })
+Mailblastr::Batch.send(payloads, { idempotency_key: "orders-2026-08-08" })
 ```
 
+The key must be **1–255 characters**, measured after the server trims it — 255, not 256. `Mailblastr::Client::IDEMPOTENCY_KEY_MAX_LENGTH` carries that number. The SDK sends the key verbatim and lets the **server** be the authority: an out-of-range key comes back as `400 invalid_idempotency_key` (a `Mailblastr::Error` with `name == "invalid_idempotency_key"`).
+
+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.
+
+## Rate limits
+
+Only the `/emails` routes are rate-limited: **30 requests per minute per IP**, covering reads as well as sends. Those responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers (on successes too) so you can throttle before being rejected. The SDK retries a 429 or 503 automatically — up to `Mailblastr.max_retries` times (default 2), honouring `Retry-After`.
+
 ## Documentation
 
 Full docs: <https://www.mailblastr.com/docs>

data/lib/mailblastr/api_keys.rb

@@ -1,25 +1,18 @@
 # frozen_string_literal: true
 
 module Mailblastr
+  # Listing only, by design. Keys are created, re-scoped and revoked in the
+  # MailBlastr dashboard by a signed-in user — POST /api-keys,
+  # PATCH /api-keys/:id and DELETE /api-keys/:id answer 403 `dashboard_only`
+  # to every API-key caller, whatever its permission. Exposing only `list`
+  # means a leaked key cannot mint itself a replacement or widen its access.
   module ApiKeys
     class << self
-      # Create an API key — the full token is returned only once, here.
-      # POST /api-keys — params: { name:, permission: "full_access"|"sending_access", domain_id:, domain_ids: }
-      # domain_ids: scopes the key to one or more domains (works with both
-      # permissions); domain_id: is the legacy single-domain form. Providing
-      # both is a 422.
-      def create(params)
-        Client.request(:post, "/api-keys", body: params)
-      end
-
-      # GET /api-keys
-      def list
-        Client.request(:get, "/api-keys")
-      end
-
-      # DELETE /api-keys/:id
-      def delete(api_key_id)
-        Client.request(:delete, "/api-keys/#{Client.path_escape(api_key_id)}")
+      # GET /api-keys — with no pagination params every non-revoked key is
+      # returned. `token` here is the 8-character display prefix, never the
+      # secret.
+      def list(params = {})
+        Client.request(:get, "/api-keys", query: Client.pagination(params))
       end
     end
   end

data/lib/mailblastr/automations.rb

@@ -35,18 +35,45 @@ module Mailblastr
       end
 
       # Append a step. POST /automations/:id/steps — params: { type:, config:, key: }
+      # The automation must be disabled first, and `type: "trigger"` is
+      # rejected here (the trigger lives on the automation, not in `steps`).
       def add_step(automation_id, params)
         Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/steps", body: params)
       end
 
+      # Edit a step in place (automation must be disabled).
+      # PATCH /automations/:id/steps/:step_id
+      def update_step(automation_id, step_id, params)
+        Client.request(
+          :patch,
+          "/automations/#{Client.path_escape(automation_id)}/steps/#{Client.path_escape(step_id)}",
+          body: params
+        )
+      end
+
       # Delete a step. DELETE /automations/:id/steps/:step_id
       def delete_step(automation_id, step_id)
         Client.request(:delete, "/automations/#{Client.path_escape(automation_id)}/steps/#{Client.path_escape(step_id)}")
       end
 
-      # List an automation's runs. GET /automations/:id/runs
+      # Build (or extend) the automation's steps from a prompt.
+      # POST /automations/:id/ai — params: { prompt:, template_ids:, events:, attach: }
+      # `prompt` is required and capped at 2000 characters. Without `attach` the
+      # automation must have no steps yet; pass `attach` ({ from:, type:,
+      # before: }) to append to an existing graph. The automation must be
+      # stopped, and the route is limited to 20 requests per minute per account.
+      def create_with_ai(automation_id, params)
+        Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/ai", body: params)
+      end
+
+      # List an automation's runs. `status` filters to specific run statuses
+      # ("running", "completed", "failed", "skipped") and accepts an Array or a
+      # comma-separated String. GET /automations/:id/runs
       def runs(automation_id, params = {})
-        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs", query: Client.pagination(params))
+        query = Client.pagination(params)
+        status = Client.opt(params, :status)
+        query[:status] = status.is_a?(Array) ? status.join(",") : status unless status.nil?
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs", query: query)
       end
 
       # Retrieve a single run with its step trace. GET /automations/:id/runs/:run_id

data/lib/mailblastr/campaigns.rb

@@ -52,6 +52,13 @@ module Mailblastr
         Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/stats")
       end
 
+      # Who opened, clicked and replied, contact by contact. Each list is
+      # capped at 500 rows and there is no pagination.
+      # GET /campaigns/:id/engagement
+      def engagement(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/engagement")
+      end
+
       # A/B winner evaluation for an A/B campaign. GET /campaigns/:id/ab
       def ab(campaign_id)
         Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/ab")

data/lib/mailblastr/client.rb

@@ -27,6 +27,16 @@ module Mailblastr
     # Upper bound (seconds) on any single backoff wait.
     MAX_BACKOFF_SECONDS = 30.0
 
+    # `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
+    # ignores it, so a retry there creates a second resource.
+    #
+    # Exposed for discoverability only: the SDK sends the key as given and lets
+    # the server be the authority.
+    IDEMPOTENCY_KEY_MAX_LENGTH = 255
+
     # Perform an API request and return the parsed JSON body (a Hash/Array),
     # or the raw body String when `raw: true` (binary download endpoints).
     # Raises Mailblastr::Error on any non-2xx response.
@@ -114,7 +124,7 @@ module Mailblastr
       req["Authorization"] = "Bearer #{key}"
       req["User-Agent"] = "mailblastr-ruby/#{Mailblastr::VERSION}"
       req["Accept"] = "application/json"
-      idem = opt(options, :idempotency_key)
+      idem = idempotency_key(opt(options, :idempotency_key))
       req["Idempotency-Key"] = idem if idem
       unless body.nil?
         req["Content-Type"] = "application/json"
@@ -157,10 +167,14 @@ module Mailblastr
           nil
         end
         parsed = {} unless parsed.is_a?(Hash)
+        # The whole body rides along: plan/quota errors add `limit`, reputation
+        # gates add `reputation`, and a partial batch failure adds
+        # `sent`/`sent_count` (see Mailblastr::Error).
         raise Mailblastr::Error.new(
           parsed["message"] || "Request failed with status #{code}",
           status_code: parsed["statusCode"] || code,
-          error_name: parsed["name"] || "application_error"
+          error_name: parsed["name"] || "application_error",
+          body: parsed
         )
       end
     end
@@ -171,6 +185,20 @@ module Mailblastr
       CGI.escape(value.to_s).gsub("+", "%20")
     end
 
+    # Normalize an `idempotency_key` option into the header value. nil/absent or
+    # an empty string means "no header"; anything else is sent VERBATIM.
+    #
+    # The 1-255 bound (IDEMPOTENCY_KEY_MAX_LENGTH) is the server's to enforce —
+    # it trims the value and answers an out-of-range key with
+    # 400 invalid_idempotency_key. Checking here would only risk drifting from
+    # the server, and would disagree with the other MailBlastr SDKs.
+    def idempotency_key(value)
+      return nil if value.nil?
+
+      key = value.to_s
+      key.empty? ? nil : key
+    end
+
     # Read a hash param by symbol or string key.
     def opt(params, key)
       return nil unless params.is_a?(Hash)
@@ -194,6 +222,16 @@ module Mailblastr
       q
     end
 
+    # Copy the given keys out of `params` into a query hash, skipping the
+    # ones the caller left out. Used to expose an endpoint's server-side
+    # filters without forwarding unrelated params.
+    def filters(params, *keys)
+      keys.each_with_object({}) do |k, q|
+        v = opt(params, k)
+        q[k] = v unless v.nil?
+      end
+    end
+
     # Domain-first guard: several resources require the sending domain.
     def require_domain!(params, context)
       v = opt(params, :domain)

data/lib/mailblastr/contacts.rb

@@ -96,24 +96,44 @@ module Mailblastr
         )
       end
 
-      # Bulk-import contacts from CSV text (header row optional; upsert by
-      # email). Non-builtin columns auto-register as custom properties unless
-      # `create_properties: false`. POST /audiences/:id/contacts/import
+      # Bulk-import contacts from CSV (header row optional; upsert by email).
+      # Non-builtin columns auto-register as custom properties unless
+      # `create_properties: false`. Pass `segment_id` to also add every
+      # imported email to one of this audience's segments.
+      # POST /audiences/:id/contacts/import
+      #
+      # Inline CSV text (capped at 5 MB and 10,000 rows):
       #   Contacts.import({ audience_id: "aud_1", csv: "email\na@b.com" })
+      # Or a file already uploaded via import_upload (no row cap — the
+      # overflow past your contact limit comes back as `limit_skipped`):
+      #   Contacts.import({ audience_id: "aud_1", storage_key: key })
       def import(params)
         audience_id = Client.opt(params, :audience_id)
-        query = {}
-        on_conflict = Client.opt(params, :on_conflict)
-        query[:on_conflict] = on_conflict if on_conflict
+        query = Client.filters(params, :on_conflict, :segment_id)
         query[:create_properties] = "false" if Client.opt(params, :create_properties) == false
+        body = Client.filters(params, :csv, :file_name, :storage_key)
         Client.request(
           :post,
           "/audiences/#{Client.path_escape(audience_id)}/contacts/import",
-          body: { csv: Client.opt(params, :csv) },
+          body: body,
           query: query
         )
       end
 
+      # Mint a presigned direct-upload URL for a CSV too large to inline
+      # (up to 256 MB). Upload the file to `upload_url`, then pass the returned
+      # `storage_key` to Contacts.import.
+      # POST /audiences/:id/contacts/import/upload — params: { filename:, size: }
+      # The `upload_url` is a bearer credential — do not log it.
+      def import_upload(params)
+        audience_id = Client.opt(params, :audience_id)
+        Client.request(
+          :post,
+          "/audiences/#{Client.path_escape(audience_id)}/contacts/import/upload",
+          body: Client.without(params, :audience_id)
+        )
+      end
+
       # Add a contact to a segment. POST /contacts/:id/segments/:segment_id
       def add_to_segment(contact_id, segment_id)
         Client.request(:post, "/contacts/#{Client.path_escape(contact_id)}/segments/#{Client.path_escape(segment_id)}")
@@ -124,14 +144,23 @@ module Mailblastr
         Client.request(:delete, "/contacts/#{Client.path_escape(contact_id)}/segments/#{Client.path_escape(segment_id)}")
       end
 
-      # List the segments a contact belongs to. GET /contacts/:id/segments
-      def list_segments(contact_id)
-        Client.request(:get, "/contacts/#{Client.path_escape(contact_id)}/segments")
+      # List the segments a contact belongs to — items carry id/name/created_at
+      # only, not the full segment object. GET /contacts/:id/segments
+      def list_segments(contact_id, params = {})
+        Client.request(
+          :get,
+          "/contacts/#{Client.path_escape(contact_id)}/segments",
+          query: Client.pagination(params)
+        )
       end
 
       # Get a contact's topic subscriptions. GET /contacts/:id/topics
-      def get_topics(contact_id)
-        Client.request(:get, "/contacts/#{Client.path_escape(contact_id)}/topics")
+      def get_topics(contact_id, params = {})
+        Client.request(
+          :get,
+          "/contacts/#{Client.path_escape(contact_id)}/topics",
+          query: Client.pagination(params)
+        )
       end
 
       # Update a contact's topic subscriptions. PATCH /contacts/:id/topics

data/lib/mailblastr/domains.rb

@@ -13,11 +13,27 @@ module Mailblastr
         Client.request(:get, "/domains/#{Client.path_escape(domain_id)}")
       end
 
-      # GET /domains
+      # GET /domains — with no pagination params every domain is returned.
+      # Rows still pending a DNS-TXT ownership claim are excluded; read those
+      # through get_claim instead.
       def list(params = {})
         Client.request(:get, "/domains", query: Client.pagination(params))
       end
 
+      # Check a domain's live MX records before adding receiving.
+      # `ours` is true only when every MX host is MailBlastr's. A DNS failure
+      # answers { has_mx: false, ours: false, records: [] }, not an error.
+      # GET /domains/mx-check?name=
+      def mx_check(name)
+        Client.request(:get, "/domains/mx-check", query: { name: name })
+      end
+
+      # Download the domain's DNS records as CSV text (a String, not JSON).
+      # GET /domains/:id/records.csv
+      def records_csv(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/records.csv", raw: true)
+      end
+
       # PATCH /domains/:id (returns the slim ack { object: "domain", id }).
       def update(domain_id, params)
         Client.request(:patch, "/domains/#{Client.path_escape(domain_id)}", body: params)
@@ -63,8 +79,8 @@ module Mailblastr
 
       # Apply DNS records via the Namecheap API (existing records preserved),
       # then auto-verify. POST /domains/:id/dns/namecheap
-      # params: { api_user: "...", api_key: "...", user_name: "..." } — note the
-      # backend expects camelCase keys (apiUser/apiKey/userName), so pass those.
+      # params: { api_user: "...", api_key: "...", user_name: "..." } — the
+      # camelCase spellings (apiUser/apiKey/userName) are accepted too.
       def apply_namecheap_dns(domain_id, params)
         Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/namecheap", body: params)
       end

data/lib/mailblastr/emails.rb

@@ -19,17 +19,24 @@ module Mailblastr
       end
 
       # List sent emails (trimmed list items) — cursor pagination plus optional
-      # server-side `campaign_id`, `automation_id`, `source` ("individual"),
-      # and `domain_id` filters. GET /emails
+      # 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
       def list(params = {})
-        query = Client.pagination(params)
-        %i[campaign_id automation_id source domain_id].each do |k|
-          v = Client.opt(params, k)
-          query[k] = v unless v.nil?
-        end
+        query = Client.pagination(params).merge(
+          Client.filters(params, :campaign_id, :automation_id, :source, :domain_id, :status, :search, :q)
+        )
         Client.request(:get, "/emails", query: query)
       end
 
+      # Per-source send metrics, one row per campaign / automation / individual
+      # origin. Not paginated. GET /emails/sources
+      def sources
+        Client.request(:get, "/emails/sources")
+      end
+
       # Retrieve a sent email and its events. GET /emails/:id
       def get(email_id)
         Client.request(:get, "/emails/#{Client.path_escape(email_id)}")
@@ -62,22 +69,34 @@ module Mailblastr
       class << self
         # List received emails — cursor pagination plus an optional
         # `received_for` filter (only messages received for that address).
+        # With no `limit` and no cursor the endpoint returns up to 1000 rows in
+        # one response; pass `limit` to get normal 1-100 pages.
         # GET /emails/receiving
         def list(params = {})
-          query = Client.pagination(params)
-          received_for = Client.opt(params, :received_for)
-          query[:received_for] = received_for unless received_for.nil?
+          query = Client.pagination(params).merge(Client.filters(params, :received_for))
           Client.request(:get, "/emails/receiving", query: query)
         end
 
+        # Per-address inbound stats (totals, replies, last received).
+        # Not paginated. GET /emails/receiving/addresses
+        def addresses
+          Client.request(:get, "/emails/receiving/addresses")
+        end
+
         # Retrieve a received email. GET /emails/receiving/:id
         def get(email_id)
           Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}")
         end
 
-        # List a received email's attachments. GET /emails/receiving/:id/attachments
-        def list_attachments(email_id)
-          Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}/attachments")
+        # List a received email's attachments. With no `limit` and no `after`
+        # every attachment is returned; supplying either paginates normally.
+        # GET /emails/receiving/:id/attachments
+        def list_attachments(email_id, params = {})
+          Client.request(
+            :get,
+            "/emails/receiving/#{Client.path_escape(email_id)}/attachments",
+            query: Client.pagination(params)
+          )
         end
 
         # Download one attachment as raw bytes (binary String).

data/lib/mailblastr/error.rb

@@ -11,18 +11,81 @@ module Mailblastr
   #     e.name        # => "validation_error"
   #     e.message     # => "The `from` address must use a verified domain."
   #   end
+  #
+  # Match on #name, never on #message — messages are scrubbed of provider
+  # identifiers server-side and are not a stable contract. A handler may also
+  # answer with a status other than the one a name usually maps to, so read
+  # #status_code rather than assuming one from the name.
+  #
+  # Some errors carry additive fields on top of those three. The whole parsed
+  # body is kept on #body, with the common extras surfaced as readers that
+  # return nil on an ordinary error:
+  #
+  #   rescue Mailblastr::Error => e
+  #     if (cap = e.limit)                   # WHICH quota ran out
+  #       cap["kind"]                        # => "emails_daily"
+  #       cap["used"]; cap["limit"]          # => 100, 100
+  #       cap.dig("next_plan", "name")       # => "Pro"
+  #     end
+  #     e.reputation                         # reputation gates
+  #     e.sent                               # a batch that failed part way through
+  #     e.sent_count                         #   — do NOT resend these
+  #   end
   class Error < StandardError
     attr_reader :status_code, :error_name
 
-    def initialize(message = nil, status_code: nil, error_name: nil)
+    # The full parsed error body ({} when the response was not a JSON object).
+    # Read it for any additive field newer than this SDK version.
+    attr_reader :body
+
+    def initialize(message = nil, status_code: nil, error_name: nil, body: nil)
       super(message)
       @status_code = status_code
       @error_name = error_name
+      @body = body.is_a?(Hash) ? body : {}
     end
 
     # The API error `name` (e.g. "validation_error", "not_found").
     def name
       @error_name
     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
+    # used, and the cheapest plan that would fit.
+    def limit
+      hash_field("limit")
+    end
+
+    # The reputation-gate detail on reputation_paused /
+    # reputation_limit_exceeded, else nil. Carries at least "retryable" and
+    # "scope" ("tenant" | "domain" | "platform").
+    def reputation
+      hash_field("reputation")
+    end
+
+    # The emails that were already sent before a batch failed part way through
+    # (POST /emails/batch with an idempotency_key), else nil. Do NOT resend them.
+    def sent
+      value = @body["sent"]
+      value.is_a?(Array) ? value : nil
+    end
+
+    # How many emails went out before a batch failed part way through, else nil.
+    # Falls back to #sent's size when the body carried the list but not the count.
+    def sent_count
+      count = @body["sent_count"]
+      return count if count.is_a?(Integer)
+
+      sent&.size
+    end
+
+    private
+
+    def hash_field(key)
+      value = @body[key]
+      value.is_a?(Hash) ? value : nil
+    end
   end
 end

data/lib/mailblastr/events.rb

@@ -8,19 +8,37 @@ module Mailblastr
       # Send a custom event. POST /events/send
       #   Mailblastr::Events.send({ event: "signup.completed", domain: "yourdomain.com",
       #                             email: "user@example.com", payload: { plan: "pro" } })
-      # Identify the contact by `contact_id` OR `email`. Pass
-      # { idempotency_key: "..." } as the second argument to retry safely.
+      # 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`.
+      # 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.
       def send(params, options = {})
         Client.require_domain!(params, "Events.send")
         Client.request(:post, "/events/send", body: params, options: options)
       end
 
-      # Create a custom-event definition (name + optional payload schema). POST /events
+      # Create a custom-event definition (name + optional payload schema).
+      # Schema values are one of "string", "number", "boolean", "date".
+      # POST /events
       #   Mailblastr::Events.create({ name: "signup.completed", schema: { plan: "string" } })
+      #
+      # NOTE: `options[:idempotency_key]` carries no guarantee here — see
+      # `send`. A duplicate event name is already a 422 validation_error.
       def create(params, options = {})
         Client.request(:post, "/events", body: params, options: options)
       end
 
+      # Update a definition's payload schema. PATCH /events/:id
+      # The event NAME is immutable (automations reference it) — passing `name`
+      # is a 422; pass `schema: nil` to clear the schema.
+      #   Mailblastr::Events.update("evt_1", { schema: { plan: "string" } })
+      def update(event_id, params)
+        Client.request(:patch, "/events/#{Client.path_escape(event_id)}", body: params)
+      end
+
       # List custom-event definitions. GET /events
       def list(params = {})
         Client.request(:get, "/events", query: Client.pagination(params))

data/lib/mailblastr/segments.rb

@@ -25,9 +25,15 @@ module Mailblastr
         Client.request(:get, "/segments", query: { domain: domain }.merge(Client.pagination(params)))
       end
 
-      # Preview the contacts a segment currently resolves to. GET /segments/:id/contacts
-      def contacts(segment_id)
-        Client.request(:get, "/segments/#{Client.path_escape(segment_id)}/contacts")
+      # Preview the contacts a segment currently resolves to (filter matches
+      # plus explicit memberships). With no pagination params every contact is
+      # returned. GET /segments/:id/contacts
+      def contacts(segment_id, params = {})
+        Client.request(
+          :get,
+          "/segments/#{Client.path_escape(segment_id)}/contacts",
+          query: Client.pagination(params)
+        )
       end
 
       # PATCH /segments/:id

data/lib/mailblastr/version.rb

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

data/lib/mailblastr/webhooks.rb

@@ -34,6 +34,22 @@ module Mailblastr
 
       # Send a synchronous test delivery and return the endpoint's live result.
       # POST /webhooks/:id/test
+      #
+      # A FAILED delivery is still HTTP 200, so this does NOT raise when your
+      # endpoint rejects the test. The outcome is the "ok" key:
+      #
+      #   { "object" => "webhook_test", "id" => "<id>",
+      #     "ok" => true,  "status" => 200 }          # endpoint accepted it
+      #   { "object" => "webhook_test", "id" => "<id>",
+      #     "ok" => false, "error" => "lookup_failed" } # it did not
+      #
+      #   result = Mailblastr::Webhooks.test(id)
+      #   warn "test delivery failed: #{result['error']}" unless result["ok"]
+      #
+      # "status" is your endpoint's HTTP status when it responded at all;
+      # "error" says why the delivery failed (e.g. "lookup_failed",
+      # "webhook missing or disabled"). It is a single attempt — no retries
+      # are scheduled.
       def test(webhook_id)
         Client.request(:post, "/webhooks/#{Client.path_escape(webhook_id)}/test")
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailblastr
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - MailBlastr
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-25 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest