mailblastr 3.0.1 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9de7ff5dac71bd3ba5db1b38369328167f9b2a52b59974201f868299f23d35c
-  data.tar.gz: bc48385e4675d1c6ef5163e5fb7a2583b145562bf43e8a4d5d3d33f9797eecea
+  metadata.gz: 53c08e2365d3814e563987d9625310f3cf42ed6d8aa5f1869b1603472dc72318
+  data.tar.gz: 0f0f31d046c3e508ed8a6812f79c1f8c502ec1354f7ac3885636bd4e8c5e9eb3
 SHA512:
-  metadata.gz: 40472dc57967817c0071973ecb6d7f353f5a927f9261c76f035f13552d47680481caad49fcf01da8a6698996278811f23c6a8b999a6aa8312461e92d88676a0e
-  data.tar.gz: 63131860cae2becb8dddc98c36aed13e970433541b81e4c0b93732ca968ab9a7a2db9c6ee7d5630d114a2e46ea3d09c21d7a49193f7e337b98dce95bf42c7057
+  metadata.gz: 1e0eb93701e40a42117102a427d80b7d3003669515e31d3f58d96ad46680993a9989e98e205227d434e7227a7fead48e16e2bc541491920fe30104177fab8059
+  data.tar.gz: 219ab57ee04faaf8817f98711a46887b87686c40df79189fd3b75d9076f804bcf579d76a3b126d21d714f329453936fcf548733c00a1636d0f30d1f6c2e31a84

data/README.md

@@ -35,13 +35,15 @@ end
 ```ruby
 sent = Mailblastr::Emails.send({
   from: "Acme <hello@yourdomain.com>",
-  to: ["user@example.com"],
+  to: ["delivered@mailblastr.dev"], # the mailbox simulator (see below)
   subject: "Hello from MailBlastr",
   html: "<p>Your first email 🎉</p>"
 })
 puts sent["id"]
 ```
 
+`delivered@mailblastr.dev` is MailBlastr's mailbox simulator: the send is accepted, produces a real email object and a delivery event, and never reaches a provider. `bounced@`, `complained@` and `suppressed@mailblastr.dev` exercise the other outcomes, and `delivered@` / `bounced@` / `complained@` accept a `+label` suffix (`delivered+signup@mailblastr.dev`). Do **not** point a send at `example.com`, `example.net`, `example.org`, or an address under `.test`, `.invalid`, `.localhost` or `.example`: those are reserved for documentation, so every recipient is suppressed and the call comes back 422 `validation_error` ("All `to` recipients are suppressed") having sent nothing. They are fine as *contact* records — only the send path rejects them.
+
 Params are plain hashes with snake_case keys, passed through as JSON. Successful calls return the parsed response (a Hash, or a raw String for binary downloads). Any non-2xx response raises `Mailblastr::Error`:
 
 ```ruby
@@ -109,10 +111,11 @@ Mailblastr::Emails.get_attachment(email_id, attachment_id)
 Mailblastr::Emails.update(email_id, { scheduled_at: "2026-08-01T09:00:00Z" }) # reschedule
 Mailblastr::Emails.cancel(email_id)
 
-# Batch send — up to 100 emails in one request
+# Batch send — up to 100 emails in one request.
+# Batch items reject `attachments` and `scheduled_at` (422) — send those individually.
 Mailblastr::Batch.send([
-  { from: from, to: ["a@example.com"], subject: "Hi A", html: "<p>A</p>" },
-  { from: from, to: ["b@example.com"], subject: "Hi B", html: "<p>B</p>" }
+  { from: from, to: ["delivered+a@mailblastr.dev"], subject: "Hi A", html: "<p>A</p>" },
+  { from: from, to: ["delivered+b@mailblastr.dev"], subject: "Hi B", html: "<p>B</p>" }
 ])
 
 # Attachments: hosted URL (path) or inline base64 (content)
@@ -274,7 +277,11 @@ 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" } })
+# `type` is REQUIRED on update_step: PATCH re-validates the whole step and
+# `config` REPLACES the stored config wholesale (there is no merge), so resend
+# every key you want to keep. A step's graph `key` is create-only — settable on
+# add_step, ignored here — so delete and re-add a step to re-key it.
+Mailblastr::Automations.update_step(automation["id"], step_id, { type: "send_email", config: { template_id: tmpl_id, 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)
@@ -383,7 +390,7 @@ 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.
+Defaults differ per endpoint. `GET /templates`, `/webhooks`, `/audiences`, `/automations`, `/events` and `/automations/:id/runs` cap an unpaginated call at 20 rows. `/domains`, `/api-keys`, `/topics`, `/campaigns`, `/contacts`, `/contact-properties`, `/segments` and `/polls` instead return the collection in one response when you pass neither `limit` nor a cursor — but still bounded, at 1,000 rows. That ceiling is not silent: `has_more` is `true` when it bites, so keep paging with `after` rather than treating the first response as the whole table. Always pass `limit` if you depend on page size.
 
 ## Idempotency
 
@@ -402,7 +409,7 @@ Only `Emails.send` and `Batch.send` honour the header. Every other endpoint —
 
 ## 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`.
+Only the `/emails` **send** routes are rate-limited: **30 requests per minute per IP**. Reads (`GET /emails`, `GET /emails/:id`, the `receiving` subtree and attachment listings) are NOT subject to that cap, so paging a large list no longer risks a 429. Capped 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
 

data/lib/mailblastr/api_keys.rb

@@ -8,9 +8,9 @@ module Mailblastr
   # means a leaked key cannot mint itself a replacement or widen its access.
   module ApiKeys
     class << self
-      # GET /api-keys — with no pagination params every non-revoked key is
-      # returned. `token` here is the 8-character display prefix, never the
-      # secret.
+      # GET /api-keys — with no pagination params one page carries up to 1,000
+      # non-revoked keys and `has_more` reports any truncation. `token` here is
+      # the 8-character display prefix, never the secret.
       def list(params = {})
         Client.request(:get, "/api-keys", query: Client.pagination(params))
       end

data/lib/mailblastr/automations.rb

@@ -42,7 +42,12 @@ module Mailblastr
       end
 
       # Edit a step in place (automation must be disabled).
-      # PATCH /automations/:id/steps/:step_id
+      # PATCH /automations/:id/steps/:step_id — params: { type:, config: }
+      # `type` is REQUIRED: the server re-validates the whole step, so omitting
+      # it is a validation_error naming the valid types. `config` REPLACES the
+      # stored config wholesale (there is no merge) — resend every key you want
+      # to keep. `key` is not accepted here; a step's graph key is create-only
+      # (set on add_step), so delete and re-add a step to re-key it.
       def update_step(automation_id, step_id, params)
         Client.request(
           :patch,

data/lib/mailblastr/campaigns.rb

@@ -42,7 +42,15 @@ module Mailblastr
         Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/send", body: params)
       end
 
-      # Cancel a scheduled campaign (returns it to draft). POST /campaigns/:id/cancel
+      # Stop a campaign's remaining work. Accepted on `scheduled`, `recurring`,
+      # `paused` and `queued`; anything else is a validation_error.
+      # `scheduled`/`recurring`/`paused` return to `draft` (editable, re-sendable);
+      # a `queued` campaign already fanning out becomes the TERMINAL `canceled`,
+      # which can never be edited, re-sent or deleted. Copies already handed to
+      # the mail service cannot be recalled; what stops is every remaining
+      # recipient (for a staggered campaign, every future batch-day).
+      # Read the returned `status` to see which happened.
+      # POST /campaigns/:id/cancel
       def cancel(campaign_id)
         Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/cancel")
       end

data/lib/mailblastr/domains.rb

@@ -13,9 +13,10 @@ module Mailblastr
         Client.request(:get, "/domains/#{Client.path_escape(domain_id)}")
       end
 
-      # 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.
+      # GET /domains — with no pagination params one page carries up to 1,000
+      # domains and `has_more` reports any truncation; pass `limit` and walk
+      # `after` to read past that. 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
@@ -79,8 +80,11 @@ 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: "..." } — the
-      # camelCase spellings (apiUser/apiKey/userName) are accepted too.
+      # params: { apiUser: "...", apiKey: "...", userName: "..." } — camelCase,
+      # the same spelling every MailBlastr SDK uses. `api_user` and `api_key`
+      # are accepted aliases, and the optional username may also be spelled
+      # `username`, but there is NO `user_name` alias: the API ignores that key,
+      # so a username sent under it is silently dropped.
       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

@@ -96,7 +96,8 @@ module Mailblastr
         end
 
         # List a received email's attachments. With no `limit` and no `after`
-        # every attachment is returned; supplying either paginates normally.
+        # one page carries up to 1,000 of them and `has_more` reports any
+        # truncation; supplying either paginates normally.
         # GET /emails/receiving/:id/attachments
         def list_attachments(email_id, params = {})
           Client.request(

data/lib/mailblastr/segments.rb

@@ -26,8 +26,10 @@ module Mailblastr
       end
 
       # 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
+      # plus explicit memberships). With no pagination params the response is
+      # capped at 1,000 contacts and sets `has_more` — a segment can hold far
+      # more than that, so page with `limit` + `after` to read all of it.
+      # GET /segments/:id/contacts
       def contacts(segment_id, params = {})
         Client.request(
           :get,

data/lib/mailblastr/version.rb

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

data/lib/mailblastr/webhooks.rb

@@ -63,14 +63,18 @@ module Mailblastr
       # signing secret. Pure local computation (OpenSSL HMAC-SHA256) — no HTTP.
       #
       # `payload` MUST be the exact raw request body string (do not re-serialize
-      # parsed JSON). `headers` is a Hash carrying svix-id / svix-timestamp /
-      # svix-signature (read case-insensitively; array values use the first
-      # element). The signature header may carry multiple space-separated
-      # `v1,<base64>` entries — any one match makes the delivery valid.
+      # parsed JSON). `headers` may be a Hash OR any pair-yielding header
+      # container (e.g. Rails' `request.headers`), carrying svix-id /
+      # svix-timestamp / svix-signature (read case-insensitively, rack
+      # `HTTP_SVIX_ID` spellings included; array values use the first element).
+      # The signature header may carry multiple space-separated `v1,<base64>`
+      # entries — any one match makes the delivery valid.
       #
       # Returns { valid: true } or { valid: false, reason: "..." }.
       #
-      #   result = Mailblastr::Webhooks.verify(request.raw_post, request.headers.to_h, secret)
+      #   # Rails: pass request.headers straight through — NOT .to_h, which
+      #   # hands you the rack env spellings instead of the header names.
+      #   result = Mailblastr::Webhooks.verify(request.raw_post, request.headers, secret)
       #   head :unauthorized unless result[:valid]
       def verify(payload, headers, secret, tolerance: 300)
         id = read_header(headers, "svix-id")
@@ -107,12 +111,38 @@ module Mailblastr
       private
 
       # Case-insensitively read one header value (first element if an array).
+      #
+      # Accepts a Hash AND any pair-yielding container, because Rails'
+      # `request.headers` is an ActionDispatch::Http::Headers — Enumerable, not
+      # a Hash — and the old `is_a?(Hash)` guard rejected it before any lookup,
+      # so the most natural call answered `missing_headers` for every genuinely
+      # signed delivery. Rack/WSGI spellings (`HTTP_SVIX_ID`) are matched too,
+      # since ActionDispatch's #each delegates to the raw rack env: that is what
+      # `request.headers.to_h` and a bare rack `env` actually contain, and
+      # downcased `http_svix_id` never equals `svix-id`.
+      #
+      # Enumerating is guarded: an exotic container whose #each demands a block
+      # would otherwise raise LocalJumpError out of `verify`, turning a 401 into
+      # a 500 inside a webhook controller. Caller-supplied input must never
+      # raise here — an unreadable container is just `missing_headers`.
       def read_header(headers, name)
-        return nil unless headers.is_a?(Hash)
+        return nil if headers.nil?
 
         lower = name.downcase
-        headers.each do |k, v|
-          next unless k.to_s.downcase == lower
+        rack = "http_#{lower.tr('-', '_')}"
+        pairs =
+          begin
+            if headers.respond_to?(:each_pair) then headers.each_pair.to_a
+            elsif headers.respond_to?(:each) then headers.each.to_a
+            else return nil
+            end
+          rescue StandardError
+            return nil
+          end
+
+        pairs.each do |k, v|
+          key = k.to_s.downcase
+          next unless key == lower || key == rack
 
           return v.is_a?(Array) ? v.first : v
         end
@@ -121,10 +151,20 @@ module Mailblastr
 
       # Derive the HMAC key from a `whsec_`-prefixed secret (base64-decode the
       # suffix); a secret without the prefix is used as raw UTF-8 bytes.
+      #
+      # `tr` FIRST: the signer decodes with Node's Buffer.from(suffix, 'base64')
+      # (lib/crypto.ts secretToKey), which reads "-"/"_" as the URL-safe
+      # spellings of "+"/"/". `unpack1("m")` tolerates missing padding but
+      # DROPS those two characters instead of translating them, yielding a
+      # SHORTER, different key than the signer derived — so a caller-supplied
+      # URL-safe secret (POST /webhooks accepts `secret` verbatim, unvalidated)
+      # made every genuinely signed delivery come back `no_match`. Standard,
+      # padded and unpadded suffixes are unaffected by the `tr`, which is why
+      # the failure looked arbitrary and secret-specific.
       def secret_to_key(secret)
         s = secret.to_s
         if s.start_with?("whsec_")
-          decoded = s["whsec_".length..].unpack1("m") # lenient base64 decode
+          decoded = s["whsec_".length..].tr("-_", "+/").unpack1("m")
           return decoded if decoded && !decoded.empty?
         end
         s

data/lib/mailblastr.rb

@@ -25,11 +25,16 @@ require "mailblastr/polls"
 #
 #   sent = Mailblastr::Emails.send({
 #     from: "Acme <hello@yourdomain.com>",
-#     to: ["user@example.com"],
+#     to: ["delivered@mailblastr.dev"],
 #     subject: "Hello from MailBlastr",
 #     html: "<p>Your first email</p>"
 #   })
 #   sent["id"] # => "..."
+#
+# `delivered@mailblastr.dev` is the mailbox simulator: the send is accepted and
+# produces a real email object without reaching a provider. Swap in a real
+# recipient when you go live — an address on a reserved documentation domain
+# (example.com, .test, .invalid) is refused with 422 `reserved_recipient`.
 module Mailblastr
   DEFAULT_BASE_URL = "https://www.mailblastr.com/api"
 

metadata

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