mailblastr 4.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af406b751cac271f65de584e43a1b405887cbfa13448eace04d4ba8a58f57567
-  data.tar.gz: 46c015562325cd114404e4f34e17ac44b7481ae781bb013aba951349fe016fc9
+  metadata.gz: ec78acb7d963058af8b922481262fcf7b3c1d6692876f304bdd373572b7a25b9
+  data.tar.gz: 29f2b545a15086968ad83e8f6e687868d9d4c575e292839852c540a797897d1d
 SHA512:
-  metadata.gz: b65ef435e4c88cc4415eba880b0be79ae107f7f20d374e6f30a4b19e7c85b5afb4c49833910a671979150407659b13e39a097d84cef3174a168cae3d0514b835
-  data.tar.gz: 157b75d0c9c47f2d0a78561238ab61ce03779ddf8da3b2a1a633cca472cfe0a66a2f392f2da54554aa2fa1dac319adac0ceddc03f313c871fde79dcd6dcd394c
+  metadata.gz: d3d399fe4c0db84908d49c0aa590dadc869ef661dabf0a9b3efea01ca106ec4a36bb5050d1ac760e5bd875ebaa85117750b9d8df8607f069a303391bc4763402
+  data.tar.gz: 8be077ef5c686252a518edf896002f48af3e6ac07450b1fbd3f18cf3fdf252cb05b05d186e502d342b8a00a8e40d67ec2ee9fca11fc74889527720810d61dbfa

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
 

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 = "4.0.0"
+  VERSION = "5.0.1"
 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,27 +111,142 @@ 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
         nil
       end
 
-      # 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.
+      # Derive the HMAC key from a `whsec_`-prefixed secret the way the SIGNER
+      # does, byte for byte. The signer is Node: base64-decode the suffix with
+      # `Buffer.from(suffix, 'base64')` and, when that yields ZERO bytes, fall
+      # back to the UTF-8 bytes of the WHOLE secret — `whsec_` prefix INCLUDED
+      # (mailblastr_webapp/lib/crypto.ts secretToKey). A secret without the
+      # prefix is used as raw UTF-8 bytes.
+      #
+      # The zero-byte fallback is not a curiosity: POST /webhooks stores
+      # `secret` verbatim with no shape validation, so "whsec_", "whsec_=",
+      # "whsec_!!!!" and "whsec_=YWJj" are all secrets a customer can really
+      # create, and each one keys the HMAC with its own literal text. Keying
+      # with an empty string instead — the obvious reading of "decode, then
+      # use the result" — costs the whole endpoint silently, because a key
+      # that differs from the signer's does not fail loudly: verify answers
+      # `no_match` and a correctly configured endpoint treats every genuine
+      # delivery as forged.
       def secret_to_key(secret)
         s = secret.to_s
-        if s.start_with?("whsec_")
-          decoded = s["whsec_".length..].unpack1("m") # lenient base64 decode
-          return decoded if decoded && !decoded.empty?
-        end
-        s
+        return s unless s.start_with?("whsec_")
+
+        decoded = node_base64_decode(s["whsec_".length..])
+        decoded.empty? ? s : decoded
+      end
+
+      # Node's `Buffer.from(str, 'base64')`, reproduced. Every rule here was
+      # read off Node itself, NOT off a base64 RFC — following the RFC is
+      # precisely how this shipped broken twice — and each one costs a real
+      # key when Ruby's own decoder is trusted instead:
+      #
+      #   * "=" TERMINATES the input. Everything from the first one onward is
+      #     DISCARDED; it is not "padding to be stripped". "YWJj====ZA" is
+      #     "abc", NOT "abcd", and a leading "=" leaves nothing at all (so the
+      #     caller's raw fallback takes over). `unpack1("m")` decodes straight
+      #     past an interior "=", deriving a LONGER key than the signer's.
+      #   * "-" and "_" are the URL-safe spellings of "+" and "/" and must be
+      #     TRANSLATED. `unpack1("m")` silently DROPS them, shortening the key.
+      #   * Any other out-of-alphabet byte is SKIPPED, never fatal: whitespace,
+      #     punctuation and non-ASCII are ignored, so "YW!Jj" is "abc".
+      #   * A trailing group of ONE character carries no whole byte, so it is
+      #     dropped here rather than left to `unpack1`'s discretion (2 chars ->
+      #     1 byte, 3 -> 2, 4 -> 3).
+      #   * The unit Node indexes the alphabet with is the LOW 8 BITS OF EACH
+      #     UTF-16 CODE UNIT, applied FIRST — see `utf16_low_bytes` below.
+      #
+      # Bytes, not characters, from the mask onward: a caller's secret need not
+      # be valid UTF-8, and an Encoding::CompatibilityError escaping this method
+      # would turn a webhook controller's 401 into a 500.
+      def node_base64_decode(suffix)
+        # Rule 5 runs BEFORE the "=" split, not after: U+013D masks to 0x3D and
+        # must TERMINATE the input like a literal "=" — splitting on the
+        # unmasked text would decode straight past it and derive a longer key.
+        s = utf16_low_bytes(suffix)
+        terminator = s.index("=")
+        s = s[0, terminator] if terminator
+
+        chars = s.tr("-_", "+/").gsub(%r{[^A-Za-z0-9+/]}n, "")
+        chars = chars[0, chars.bytesize - 1] if (chars.bytesize % 4) == 1
+        return "" if chars.empty?
+
+        chars.unpack1("m") || ""
+      end
+
+      # Rule 5, the one no SDK had: Node masks every UTF-16 CODE UNIT with 0xFF
+      # before the base64 table lookup, so the alphabet is indexed by a code
+      # unit's low byte, NOT by the codepoint and NOT by the UTF-8 bytes.
+      #
+      # Ruby strings are UTF-8, so the code units have to be materialised first:
+      # "Ł" (U+0141) is two UTF-8 bytes but ONE code unit masking to 0x41 "A",
+      # and "𝑁" (U+1D441) is ASTRAL — its four UTF-8 bytes are Node's TWO
+      # surrogate halves 0xD835/0xDC41, masking to 0x35 "5" and 0x41 "A". Taking
+      # UTF-8 bytes instead feeds the decoder continuation bytes that are all
+      # out-of-alphabet, silently shortening the key.
+      #
+      # Every codepoint below 0x100 masks to itself and every one at or above it
+      # is a different character entirely, so nothing under 0x100 can expose
+      # this — which is exactly why it survived a 31-vector corpus and a
+      # 2000-case ASCII fuzz, and why the cost lands only on the customer whose
+      # secret happens to carry a "Ł", a fullwidth letter or an emoji: their
+      # endpoint answers `no_match` to every genuine delivery.
+      #
+      # Undecodable input never raises out of here: invalid bytes become U+FFFD,
+      # whose low byte 0xFD is out of alphabet and therefore skipped — the same
+      # answer the old byte-wise reader gave — and a total conversion failure
+      # falls back to the raw bytes rather than 500-ing a webhook controller.
+      def utf16_low_bytes(str)
+        s = str.to_s
+        s = s.dup.force_encoding(Encoding::UTF_8) if s.encoding == Encoding::BINARY
+        s.encode(Encoding::UTF_16LE, invalid: :replace, undef: :replace)
+         .b.unpack("v*").map { |unit| unit & 0xFF }.pack("C*")
+      rescue StandardError
+        # Unreachable in practice: invalid:/undef: :replace make the encode total
+        # for any String. Kept so a webhook controller cannot 500 on a pathological
+        # input -- but it must NOT return str.b. Those are the raw UTF-8 bytes,
+        # which is exactly the pre-5.0.1 behaviour this method exists to replace,
+        # and returning them would silently derive a WRONG key that verifies
+        # nothing. Empty routes to the documented whole-secret fallback instead:
+        # still a mismatch, but a defined one rather than a reinstated bug.
+        ""
       end
 
       # Constant-time compare of two signature strings.

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: 4.0.0
+  version: 5.0.1
 platform: ruby
 authors:
 - MailBlastr
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest