mailblastr 1.0.0

data/lib/mailblastr/segments.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Segments are DOMAIN-FIRST: `domain` is required on create and list. Names
+  # are unique within a domain (reusable across domains); every domain also
+  # carries an auto-created "General" (all contacts) segment.
+  module Segments
+    class << self
+      # POST /segments
+      #   Mailblastr::Segments.create({ domain: "yourdomain.com", name: "VIP",
+      #                                 filter: { status: "subscribed" } })
+      def create(params)
+        Client.require_domain!(params, "Segments.create")
+        Client.request(:post, "/segments", body: params)
+      end
+
+      # GET /segments/:id
+      def get(segment_id)
+        Client.request(:get, "/segments/#{Client.path_escape(segment_id)}")
+      end
+
+      # List a domain's segments (`domain` required). GET /segments?domain=
+      def list(params)
+        domain = Client.require_domain!(params, "Segments.list")
+        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")
+      end
+
+      # PATCH /segments/:id
+      def update(segment_id, params)
+        Client.request(:patch, "/segments/#{Client.path_escape(segment_id)}", body: params)
+      end
+
+      # DELETE /segments/:id
+      def delete(segment_id)
+        Client.request(:delete, "/segments/#{Client.path_escape(segment_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/templates.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  module Templates
+    class << self
+      # POST /templates — params: { name:, alias:, subject:, html:, text:, variables: [...] }
+      def create(params)
+        Client.request(:post, "/templates", body: params)
+      end
+
+      # GET /templates/:id (an alias works anywhere an id is accepted)
+      def get(template_id)
+        Client.request(:get, "/templates/#{Client.path_escape(template_id)}")
+      end
+
+      # GET /templates
+      def list(params = {})
+        Client.request(:get, "/templates", query: Client.pagination(params))
+      end
+
+      # PATCH /templates/:id
+      def update(template_id, params)
+        Client.request(:patch, "/templates/#{Client.path_escape(template_id)}", body: params)
+      end
+
+      # Duplicate a template. POST /templates/:id/duplicate — params: { name:, alias: }
+      def duplicate(template_id, params = {})
+        Client.request(:post, "/templates/#{Client.path_escape(template_id)}/duplicate", body: params)
+      end
+
+      # Publish a template (make its latest draft live). POST /templates/:id/publish
+      def publish(template_id)
+        Client.request(:post, "/templates/#{Client.path_escape(template_id)}/publish")
+      end
+
+      # DELETE /templates/:id
+      def delete(template_id)
+        Client.request(:delete, "/templates/#{Client.path_escape(template_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/topics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Topics (granular subscriptions) are DOMAIN-FIRST: `domain` is required on
+  # create and list. Topic names are reusable across domains.
+  module Topics
+    class << self
+      # POST /topics
+      #   Mailblastr::Topics.create({ domain: "yourdomain.com", name: "Product updates",
+      #                               default_subscription: "opt_in" })
+      def create(params)
+        Client.require_domain!(params, "Topics.create")
+        Client.request(:post, "/topics", body: params)
+      end
+
+      # GET /topics/:id
+      def get(topic_id)
+        Client.request(:get, "/topics/#{Client.path_escape(topic_id)}")
+      end
+
+      # List a domain's topics (`domain` required). GET /topics?domain=
+      def list(params)
+        domain = Client.require_domain!(params, "Topics.list")
+        Client.request(:get, "/topics", query: { domain: domain }.merge(Client.pagination(params)))
+      end
+
+      # PATCH /topics/:id
+      def update(topic_id, params)
+        Client.request(:patch, "/topics/#{Client.path_escape(topic_id)}", body: params)
+      end
+
+      # DELETE /topics/:id
+      def delete(topic_id)
+        Client.request(:delete, "/topics/#{Client.path_escape(topic_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/version.rb

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

data/lib/mailblastr/webhooks.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Mailblastr
+  module Webhooks
+    class << self
+      # Create a webhook. The plaintext signing secret is returned ONCE, only here.
+      # POST /webhooks — params: { endpoint:, events: [...], secret: }
+      def create(params)
+        Client.request(:post, "/webhooks", body: params)
+      end
+
+      # GET /webhooks/:id
+      def get(webhook_id)
+        Client.request(:get, "/webhooks/#{Client.path_escape(webhook_id)}")
+      end
+
+      # GET /webhooks
+      def list(params = {})
+        Client.request(:get, "/webhooks", query: Client.pagination(params))
+      end
+
+      # PATCH /webhooks/:id — params: { endpoint:, events:, status: }
+      def update(webhook_id, params)
+        Client.request(:patch, "/webhooks/#{Client.path_escape(webhook_id)}", body: params)
+      end
+
+      # Rotate the signing secret; the new plaintext secret is returned once and
+      # the old one stops verifying immediately. POST /webhooks/:id/rotate
+      def rotate(webhook_id)
+        Client.request(:post, "/webhooks/#{Client.path_escape(webhook_id)}/rotate")
+      end
+
+      # Send a synchronous test delivery and return the endpoint's live result.
+      # POST /webhooks/:id/test
+      def test(webhook_id)
+        Client.request(:post, "/webhooks/#{Client.path_escape(webhook_id)}/test")
+      end
+
+      # DELETE /webhooks/:id
+      def delete(webhook_id)
+        Client.request(:delete, "/webhooks/#{Client.path_escape(webhook_id)}")
+      end
+
+      # Verify a webhook delivery's Svix-style signature against your endpoint's
+      # 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.
+      #
+      # Returns { valid: true } or { valid: false, reason: "..." }.
+      #
+      #   result = Mailblastr::Webhooks.verify_signature(request.raw_post, request.headers.to_h, secret)
+      #   head :unauthorized unless result[:valid]
+      def verify_signature(payload, headers, secret, tolerance: 300)
+        id = read_header(headers, "svix-id")
+        timestamp = read_header(headers, "svix-timestamp")
+        sig_header = read_header(headers, "svix-signature")
+        return { valid: false, reason: "missing_headers" } if id.nil? || timestamp.nil? || sig_header.nil?
+        return { valid: false, reason: "missing_secret" } if secret.nil? || secret.to_s.empty?
+
+        # Optional timestamp freshness check (default 5 minutes; 0 disables).
+        if tolerance && tolerance.positive?
+          ts = begin
+            Integer(timestamp, 10)
+          rescue ArgumentError, TypeError
+            nil
+          end
+          return { valid: false, reason: "invalid_timestamp" } if ts.nil?
+          return { valid: false, reason: "timestamp_out_of_tolerance" } if (Time.now.to_i - ts).abs > tolerance
+        end
+
+        signed = "#{id}.#{timestamp}.#{payload}"
+        digest = OpenSSL::HMAC.digest("SHA256", secret_to_key(secret), signed)
+        expected = [digest].pack("m0") # strict base64, no newline
+
+        sig_header.split(" ").each do |part|
+          part = part.strip
+          next if part.empty?
+
+          sig = part.start_with?("v1,") ? part[3..] : part
+          return { valid: true } if secure_compare(sig, expected)
+        end
+        { valid: false, reason: "no_match" }
+      end
+
+      private
+
+      # Case-insensitively read one header value (first element if an array).
+      def read_header(headers, name)
+        return nil unless headers.is_a?(Hash)
+
+        lower = name.downcase
+        headers.each do |k, v|
+          next unless k.to_s.downcase == lower
+
+          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.
+      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
+      end
+
+      # Constant-time compare of two signature strings.
+      def secure_compare(a, b)
+        a = a.to_s
+        b = b.to_s
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack("C*")
+        res = 0
+        b.each_byte.with_index { |byte, i| res |= byte ^ l[i] }
+        res.zero?
+      end
+    end
+  end
+end

data/lib/mailblastr.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "mailblastr/version"
+require "mailblastr/error"
+require "mailblastr/client"
+require "mailblastr/emails"
+require "mailblastr/domains"
+require "mailblastr/audiences"
+require "mailblastr/contacts"
+require "mailblastr/contact_properties"
+require "mailblastr/segments"
+require "mailblastr/topics"
+require "mailblastr/campaigns"
+require "mailblastr/templates"
+require "mailblastr/automations"
+require "mailblastr/webhooks"
+require "mailblastr/events"
+require "mailblastr/api_keys"
+require "mailblastr/logs"
+require "mailblastr/polls"
+
+# The MailBlastr API client.
+#
+#   Mailblastr.api_key = "mb_xxxxxxxxx"
+#
+#   sent = Mailblastr::Emails.send({
+#     from: "Acme <hello@yourdomain.com>",
+#     to: ["user@example.com"],
+#     subject: "Hello from MailBlastr",
+#     html: "<p>Your first email</p>"
+#   })
+#   sent["id"] # => "..."
+module Mailblastr
+  DEFAULT_BASE_URL = "https://www.mailblastr.com/api"
+
+  # Per-request network timeout, in seconds, applied to both the connect
+  # (open) and read phases. 0 or nil means "no timeout".
+  DEFAULT_TIMEOUT = 30
+
+  # How many times a retryable response (HTTP 429/503) is retried before
+  # giving up. 0 disables retries (a single attempt).
+  DEFAULT_MAX_RETRIES = 2
+
+  class << self
+    # Your API key, e.g. "mb_xxxxxxxxx". Required before any call.
+    attr_accessor :api_key
+
+    # Override the API host (defaults to https://www.mailblastr.com/api).
+    attr_writer :base_url
+
+    # Per-request timeout in seconds (default 30). Set 0 (or nil) for none.
+    attr_writer :timeout
+
+    # Max automatic retries on HTTP 429/503 (default 2, i.e. up to 3 tries).
+    attr_writer :max_retries
+
+    def base_url
+      @base_url || DEFAULT_BASE_URL
+    end
+
+    def timeout
+      @timeout.nil? ? DEFAULT_TIMEOUT : @timeout
+    end
+
+    def max_retries
+      @max_retries.nil? ? DEFAULT_MAX_RETRIES : @max_retries
+    end
+
+    #   Mailblastr.configure do |config|
+    #     config.api_key = ENV["MAILBLASTR_API_KEY"]
+    #   end
+    def configure
+      yield self
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: mailblastr
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- MailBlastr
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 'Send transactional and marketing email from your own verified domain:
+  emails, domains, contacts, segments, campaigns, templates, automations, webhooks,
+  events and more. Zero runtime dependencies (Net::HTTP only).'
+email:
+- support@mailblastr.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mailblastr.rb
+- lib/mailblastr/api_keys.rb
+- lib/mailblastr/audiences.rb
+- lib/mailblastr/automations.rb
+- lib/mailblastr/campaigns.rb
+- lib/mailblastr/client.rb
+- lib/mailblastr/contact_properties.rb
+- lib/mailblastr/contacts.rb
+- lib/mailblastr/domains.rb
+- lib/mailblastr/emails.rb
+- lib/mailblastr/error.rb
+- lib/mailblastr/events.rb
+- lib/mailblastr/logs.rb
+- lib/mailblastr/polls.rb
+- lib/mailblastr/segments.rb
+- lib/mailblastr/templates.rb
+- lib/mailblastr/topics.rb
+- lib/mailblastr/version.rb
+- lib/mailblastr/webhooks.rb
+homepage: https://www.mailblastr.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.mailblastr.com
+  documentation_uri: https://www.mailblastr.com/docs
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the MailBlastr email API
+test_files: []