mailblastr 1.0.0

data/lib/mailblastr/client.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "cgi"
+require "time"
+
+module Mailblastr
+  # Internal HTTP layer. Every resource funnels through Client.request;
+  # tests stub Client.deliver to avoid the network.
+  module Client
+    module_function
+
+    VERBS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      patch: Net::HTTP::Patch,
+      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.
+    RETRYABLE_STATUSES = [429, 503].freeze
+
+    # Upper bound (seconds) on any single backoff wait.
+    MAX_BACKOFF_SECONDS = 30.0
+
+    # 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.
+    def request(verb, path, body: nil, query: nil, options: {}, raw: false)
+      key = Mailblastr.api_key
+      if key.nil? || key.to_s.strip.empty?
+        raise Mailblastr::Error.new(
+          'Mailblastr.api_key is not set. Configure it first: Mailblastr.api_key = "mb_xxxxxxxxx"',
+          error_name: "missing_api_key"
+        )
+      end
+
+      uri = URI.parse("#{Mailblastr.base_url.to_s.sub(%r{/+\z}, '')}#{path}")
+      if query && !query.empty?
+        uri.query = [uri.query, URI.encode_www_form(query)].compact.reject(&:empty?).join("&")
+      end
+
+      req = build_request(verb, uri, body, options, key)
+      handle_response(deliver_with_retries(req, uri), raw: raw)
+    end
+
+    # The single request chokepoint: both the JSON and raw/binary paths funnel
+    # through here, so both get the timeout (applied inside deliver) and the
+    # bounded 429/503 retry loop. Non-retryable responses return immediately;
+    # network/timeout errors are NOT caught here (they propagate as before).
+    def deliver_with_retries(req, uri)
+      max = Mailblastr.max_retries.to_i
+      attempt = 0
+      loop do
+        resp = deliver(req, uri)
+        code = resp.code.to_i
+        return resp unless RETRYABLE_STATUSES.include?(code) && attempt < max
+
+        wait = retry_after_seconds(response_header(resp, "Retry-After"))
+        wait ||= [MAX_BACKOFF_SECONDS, 0.5 * (2**attempt)].min
+        backoff_sleep(wait) if wait.positive?
+        attempt += 1
+      end
+    end
+
+    # Wraps Kernel#sleep so tests can stub out the wait. Extracted so the
+    # retry loop stays deterministic under test.
+    def backoff_sleep(seconds)
+      sleep(seconds)
+    end
+
+    # Read a response header without assuming the response object shape
+    # (Net::HTTPResponse supports #[]; test doubles may not).
+    def response_header(resp, name)
+      return nil unless resp.respond_to?(:[])
+
+      resp[name]
+    rescue StandardError
+      nil
+    end
+
+    # Parse a Retry-After header into a number of seconds to wait:
+    # a numeric delta-seconds value, or an HTTP-date to wait until.
+    # Negative is treated as 0, and the wait is capped at 30 seconds.
+    # Returns nil when the header is absent or unparseable.
+    def retry_after_seconds(value)
+      return nil if value.nil?
+
+      str = value.to_s.strip
+      return nil if str.empty?
+
+      seconds =
+        begin
+          Float(str)
+        rescue ArgumentError, TypeError
+          begin
+            Time.httpdate(str) - Time.now
+          rescue ArgumentError
+            return nil
+          end
+        end
+
+      seconds = 0.0 if seconds.negative?
+      [seconds.to_f, MAX_BACKOFF_SECONDS].min
+    end
+
+    def build_request(verb, uri, body, options, key)
+      klass = VERBS.fetch(verb) { raise ArgumentError, "unsupported HTTP verb: #{verb.inspect}" }
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{key}"
+      req["User-Agent"] = "mailblastr-ruby/#{Mailblastr::VERSION}"
+      req["Accept"] = "application/json"
+      idem = opt(options, :idempotency_key)
+      req["Idempotency-Key"] = idem if idem
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      req
+    end
+
+    # The single seam that touches the network (stub me in tests).
+    # Applies the configured open/read timeout; 0 or nil means "no timeout".
+    def deliver(req, uri)
+      opts = { use_ssl: uri.scheme == "https" }
+      t = Mailblastr.timeout
+      if !t.nil? && t.to_f > 0
+        opts[:open_timeout] = t
+        opts[:read_timeout] = t
+      end
+      Net::HTTP.start(uri.host, uri.port, **opts) do |http|
+        http.request(req)
+      end
+    end
+
+    def handle_response(resp, raw: false)
+      code = resp.code.to_i
+      body = resp.body
+
+      if code >= 200 && code < 300
+        return body if raw
+        return nil if body.nil? || body.empty?
+
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          body
+        end
+      else
+        parsed = begin
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError, TypeError
+          nil
+        end
+        parsed = {} unless parsed.is_a?(Hash)
+        raise Mailblastr::Error.new(
+          parsed["message"] || "Request failed with status #{code}",
+          status_code: parsed["statusCode"] || code,
+          error_name: parsed["name"] || "application_error"
+        )
+      end
+    end
+
+    # Percent-encode one path segment so an id like "../api-keys" cannot
+    # traverse the URL path (spaces become %20, "/" becomes %2F).
+    def path_escape(value)
+      CGI.escape(value.to_s).gsub("+", "%20")
+    end
+
+    # Read a hash param by symbol or string key.
+    def opt(params, key)
+      return nil unless params.is_a?(Hash)
+
+      params.key?(key) ? params[key] : params[key.to_s]
+    end
+
+    # A copy of `params` without the given keys (symbol or string forms).
+    def without(params, *keys)
+      strs = keys.map(&:to_s)
+      params.reject { |k, _| strs.include?(k.to_s) }
+    end
+
+    # Extract the cursor-pagination params ({ limit, after, before }).
+    def pagination(params)
+      q = {}
+      %i[limit after before].each do |k|
+        v = opt(params, k)
+        q[k] = v unless v.nil?
+      end
+      q
+    end
+
+    # Domain-first guard: several resources require the sending domain.
+    def require_domain!(params, context)
+      v = opt(params, :domain)
+      if v.nil? || v.to_s.strip.empty?
+        raise ArgumentError,
+              "#{context} requires `domain` — the sending domain whose contact pool it targets, " \
+              'e.g. { domain: "yourdomain.com", ... }'
+      end
+      v
+    end
+  end
+end

data/lib/mailblastr/contact_properties.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Custom contact fields, usable as {{merge_tags}}.
+  module ContactProperties
+    class << self
+      # POST /contact-properties — params: { key:, type: "string"|"number", fallback_value: }
+      def create(params)
+        Client.request(:post, "/contact-properties", body: params)
+      end
+
+      # GET /contact-properties/:id
+      def get(property_id)
+        Client.request(:get, "/contact-properties/#{Client.path_escape(property_id)}")
+      end
+
+      # GET /contact-properties
+      def list(params = {})
+        Client.request(:get, "/contact-properties", query: Client.pagination(params))
+      end
+
+      # PATCH /contact-properties/:id — only fallback_value is mutable.
+      def update(property_id, params)
+        Client.request(:patch, "/contact-properties/#{Client.path_escape(property_id)}", body: params)
+      end
+
+      # DELETE /contact-properties/:id
+      def delete(property_id)
+        Client.request(:delete, "/contact-properties/#{Client.path_escape(property_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/contacts.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Contacts are DOMAIN-FIRST: each sending domain has its own contact pool,
+  # so the flat /contacts API takes `domain` (required on create/list). The
+  # nested audience variants (`audience_id:`) derive the pool from the path.
+  module Contacts
+    class << self
+      # Create a contact. POST /contacts (flat, `domain` required) or
+      # POST /audiences/:id/contacts when `audience_id` is given.
+      #   Mailblastr::Contacts.create({ domain: "yourdomain.com", email: "a@b.com" })
+      #   Mailblastr::Contacts.create({ audience_id: "aud_1", email: "a@b.com" })
+      def create(params)
+        audience_id = Client.opt(params, :audience_id)
+        if audience_id
+          body = Client.without(params, :audience_id, :domain)
+          Client.request(:post, "/audiences/#{Client.path_escape(audience_id)}/contacts", body: body)
+        else
+          Client.require_domain!(params, "Contacts.create (flat /contacts API)")
+          Client.request(:post, "/contacts", body: Client.without(params, :audience_id))
+        end
+      end
+
+      # Retrieve a contact by id (exact) or by email. An email can exist in
+      # several domains' pools, so pass `domain` to pick the pool.
+      #   Contacts.get({ id: "cont_1" })
+      #   Contacts.get({ id: "a@b.com", domain: "yourdomain.com" })
+      #   Contacts.get({ id: "cont_1", audience_id: "aud_1" })
+      def get(params)
+        id = Client.path_escape(Client.opt(params, :id))
+        audience_id = Client.opt(params, :audience_id)
+        return Client.request(:get, "/audiences/#{Client.path_escape(audience_id)}/contacts/#{id}") if audience_id
+
+        domain = Client.opt(params, :domain)
+        query = domain ? { domain: domain } : nil
+        Client.request(:get, "/contacts/#{id}", query: query)
+      end
+
+      # List contacts. Flat /contacts requires `domain` (names the pool);
+      # pass `audience_id` instead to use the nested API. `segment_id`
+      # filters either variant; limit/after/before paginate.
+      def list(params = {})
+        audience_id = Client.opt(params, :audience_id)
+        query = Client.pagination(params)
+        segment_id = Client.opt(params, :segment_id)
+        query[:segment_id] = segment_id if segment_id
+
+        if audience_id
+          Client.request(:get, "/audiences/#{Client.path_escape(audience_id)}/contacts", query: query)
+        else
+          query = { domain: Client.require_domain!(params, "Contacts.list (flat /contacts API)") }.merge(query)
+          Client.request(:get, "/contacts", query: query)
+        end
+      end
+
+      # Update a contact (id or email). PATCH /contacts/:id, or the nested
+      # route when `audience_id` is given. On the flat API pass `domain` when
+      # `id` is an email (disambiguates across pools).
+      #   Contacts.update({ id: "cont_1", unsubscribed: true })
+      def update(params)
+        id = Client.path_escape(Client.opt(params, :id))
+        audience_id = Client.opt(params, :audience_id)
+        if audience_id
+          body = Client.without(params, :audience_id, :domain, :id)
+          Client.request(:patch, "/audiences/#{Client.path_escape(audience_id)}/contacts/#{id}", body: body)
+        else
+          Client.request(:patch, "/contacts/#{id}", body: Client.without(params, :audience_id, :id))
+        end
+      end
+
+      # Delete a contact. DELETE /contacts/:id (pass `domain` when `id` is an
+      # email), or the nested route when `audience_id` is given.
+      def delete(params)
+        id = Client.path_escape(Client.opt(params, :id))
+        audience_id = Client.opt(params, :audience_id)
+        return Client.request(:delete, "/audiences/#{Client.path_escape(audience_id)}/contacts/#{id}") if audience_id
+
+        domain = Client.opt(params, :domain)
+        query = domain ? { domain: domain } : nil
+        Client.request(:delete, "/contacts/#{id}", query: query)
+      end
+
+      # Bulk-import contacts from an array (upsert by email; max 10,000).
+      # POST /audiences/:id/contacts/batch
+      #   Contacts.batch({ audience_id: "aud_1", contacts: [{ email: "a@b.com" }], on_conflict: "skip" })
+      def batch(params)
+        audience_id = Client.opt(params, :audience_id)
+        query = {}
+        on_conflict = Client.opt(params, :on_conflict)
+        query[:on_conflict] = on_conflict if on_conflict
+        Client.request(
+          :post,
+          "/audiences/#{Client.path_escape(audience_id)}/contacts/batch",
+          body: { contacts: Client.opt(params, :contacts) },
+          query: query
+        )
+      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
+      #   Contacts.import({ audience_id: "aud_1", csv: "email\na@b.com" })
+      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[:create_properties] = "false" if Client.opt(params, :create_properties) == false
+        Client.request(
+          :post,
+          "/audiences/#{Client.path_escape(audience_id)}/contacts/import",
+          body: { csv: Client.opt(params, :csv) },
+          query: query
+        )
+      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)}")
+      end
+
+      # Remove a contact from a segment. DELETE /contacts/:id/segments/:segment_id
+      def remove_from_segment(contact_id, segment_id)
+        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")
+      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")
+      end
+
+      # Update a contact's topic subscriptions. PATCH /contacts/:id/topics
+      #   Contacts.update_topics("cont_1", { topics: [{ id: "top_1", subscription: "opt_in" }] })
+      def update_topics(contact_id, params)
+        Client.request(:patch, "/contacts/#{Client.path_escape(contact_id)}/topics", body: params)
+      end
+    end
+  end
+end

data/lib/mailblastr/domains.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  module Domains
+    class << self
+      # Register a sending domain. POST /domains
+      def create(params)
+        Client.request(:post, "/domains", body: params)
+      end
+
+      # GET /domains/:id
+      def get(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}")
+      end
+
+      # GET /domains
+      def list(params = {})
+        Client.request(:get, "/domains", query: Client.pagination(params))
+      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)
+      end
+
+      # Trigger DNS verification. POST /domains/:id/verify
+      def verify(domain_id)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/verify")
+      end
+
+      # Claim a domain already verified in another account. POST /domains/claim
+      def claim(params)
+        Client.request(:post, "/domains/claim", body: params)
+      end
+
+      # Retrieve a domain's claim record. GET /domains/:id/claim
+      def get_claim(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/claim")
+      end
+
+      # Verify a domain claim's TXT record. POST /domains/:id/claim/verify
+      def verify_claim(domain_id)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/claim/verify")
+      end
+
+      # Detect the DNS provider and available one-click apply methods.
+      # GET /domains/:id/dns/detect
+      def detect_dns(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/dns/detect")
+      end
+
+      # Apply DNS records via the Cloudflare API, then auto-verify.
+      # POST /domains/:id/dns/cloudflare — params: { token: "..." }
+      def apply_cloudflare_dns(domain_id, params)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/cloudflare", body: params)
+      end
+
+      # Apply DNS records via the GoDaddy API, then auto-verify.
+      # POST /domains/:id/dns/godaddy — params: { key: "...", secret: "..." }
+      def apply_godaddy_dns(domain_id, params)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/godaddy", body: params)
+      end
+
+      # 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.
+      def apply_namecheap_dns(domain_id, params)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/namecheap", body: params)
+      end
+
+      # DELETE /domains/:id
+      def delete(domain_id)
+        Client.request(:delete, "/domains/#{Client.path_escape(domain_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/emails.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Send and inspect emails. Inbound mail lives under Mailblastr::Emails::Receiving.
+  module Emails
+    class << self
+      # Send a single email. POST /emails
+      #   Mailblastr::Emails.send({ from: "...", to: ["..."], subject: "...", html: "..." })
+      # Pass { idempotency_key: "order-123" } as the second argument to retry safely.
+      def send(params, options = {})
+        Client.request(:post, "/emails", body: params, options: options)
+      end
+
+      # Send up to 100 emails in one request. POST /emails/batch (alias of Batch.send).
+      def batch(payloads, options = {})
+        Client.request(:post, "/emails/batch", body: payloads, options: options)
+      end
+
+      # List sent emails (trimmed list items). GET /emails
+      def list(params = {})
+        Client.request(:get, "/emails", query: Client.pagination(params))
+      end
+
+      # Retrieve a sent email and its events. GET /emails/:id
+      def get(email_id)
+        Client.request(:get, "/emails/#{Client.path_escape(email_id)}")
+      end
+
+      # List a sent email's attachments. GET /emails/:id/attachments
+      def list_attachments(email_id)
+        Client.request(:get, "/emails/#{Client.path_escape(email_id)}/attachments")
+      end
+
+      # Retrieve one attachment's metadata. GET /emails/:id/attachments/:attachment_id
+      def get_attachment(email_id, attachment_id)
+        Client.request(:get, "/emails/#{Client.path_escape(email_id)}/attachments/#{Client.path_escape(attachment_id)}")
+      end
+
+      # Reschedule a scheduled email. PATCH /emails/:id
+      #   Mailblastr::Emails.update("email_id", { scheduled_at: "2026-08-01T09:00:00Z" })
+      def update(email_id, params)
+        Client.request(:patch, "/emails/#{Client.path_escape(email_id)}", body: params)
+      end
+
+      # Cancel a scheduled email. POST /emails/:id/cancel
+      def cancel(email_id)
+        Client.request(:post, "/emails/#{Client.path_escape(email_id)}/cancel")
+      end
+    end
+
+    # Inbound (received) email.
+    module Receiving
+      class << self
+        # List received emails. GET /emails/receiving
+        def list(params = {})
+          Client.request(:get, "/emails/receiving", query: Client.pagination(params))
+        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")
+        end
+
+        # Download one attachment as raw bytes (binary String).
+        # GET /emails/receiving/:id/attachments/:attachment_id
+        def get_attachment(email_id, attachment_id)
+          Client.request(
+            :get,
+            "/emails/receiving/#{Client.path_escape(email_id)}/attachments/#{Client.path_escape(attachment_id)}",
+            raw: true
+          )
+        end
+
+        # Download the original RFC822/MIME message as raw bytes (binary String).
+        # GET /emails/receiving/:id/raw
+        def raw(email_id)
+          Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}/raw", raw: true)
+        end
+
+        # 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)
+        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)
+        end
+
+        # Delete a received email. DELETE /emails/receiving/:id
+        def delete(email_id)
+          Client.request(:delete, "/emails/receiving/#{Client.path_escape(email_id)}")
+        end
+      end
+    end
+  end
+
+  # Batch send — Mailblastr::Batch.send([...]). POST /emails/batch
+  module Batch
+    class << self
+      def send(payloads, options = {})
+        Client.request(:post, "/emails/batch", body: payloads, options: options)
+      end
+    end
+  end
+end

data/lib/mailblastr/error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Raised for every non-2xx API response. Mirrors the API error shape
+  # { statusCode, name, message }:
+  #
+  #   begin
+  #     Mailblastr::Emails.send(params)
+  #   rescue Mailblastr::Error => e
+  #     e.status_code # => 422
+  #     e.name        # => "validation_error"
+  #     e.message     # => "The `from` address must use a verified domain."
+  #   end
+  class Error < StandardError
+    attr_reader :status_code, :error_name
+
+    def initialize(message = nil, status_code: nil, error_name: nil)
+      super(message)
+      @status_code = status_code
+      @error_name = error_name
+    end
+
+    # The API error `name` (e.g. "validation_error", "not_found").
+    def name
+      @error_name
+    end
+  end
+end

data/lib/mailblastr/events.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Custom events that automations trigger on. Events are DOMAIN-FIRST:
+  # `domain` is required on send, and only that domain's automations fire.
+  module Events
+    class << self
+      # 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.
+      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
+      #   Mailblastr::Events.create({ name: "signup.completed", schema: { plan: "string" } })
+      def create(params, options = {})
+        Client.request(:post, "/events", body: params, options: options)
+      end
+
+      # List custom-event definitions. GET /events
+      def list(params = {})
+        Client.request(:get, "/events", query: Client.pagination(params))
+      end
+
+      # Delete a custom-event definition. DELETE /events/:id
+      def delete(event_id)
+        Client.request(:delete, "/events/#{Client.path_escape(event_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/logs.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # API request logs.
+  module Logs
+    class << self
+      # List logs — cursor pagination plus optional server-side `method`
+      # (e.g. "POST") and `status` (e.g. 429) filters. GET /logs
+      def list(params = {})
+        query = Client.pagination(params)
+        method = Client.opt(params, :method)
+        status = Client.opt(params, :status)
+        query[:method] = method if method
+        query[:status] = status unless status.nil?
+        Client.request(:get, "/logs", query: query)
+      end
+
+      # Retrieve one log with request/response bodies. GET /logs/:id
+      def get(log_id)
+        Client.request(:get, "/logs/#{Client.path_escape(log_id)}")
+      end
+    end
+  end
+end

data/lib/mailblastr/polls.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailblastr
+  # Read-only results of the in-email poll widget.
+  module Polls
+    class << self
+      # One summary row per email that has poll responses. GET /polls
+      def list(params = {})
+        Client.request(:get, "/polls", query: Client.pagination(params))
+      end
+
+      # The aggregated answer breakdown for one email. GET /polls/:email_id
+      def get(email_id)
+        Client.request(:get, "/polls/#{Client.path_escape(email_id)}")
+      end
+    end
+  end
+end