mailfloss 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae5fcc08d152608c98088bd9860eaaceaf47591f7ecca3b23e0a40b9260b4147
+  data.tar.gz: 2392c5185dba55e21924bbcdd1ee5593008d8ebe2111189dd5287461f39cf431
+SHA512:
+  metadata.gz: d22fc1c0323c1b97bca607b1caea7287cc29d674fbccf1cf7cd9c2233c60019b854ed01430601af1fb2219594848bdb1c5b672486e2b7acfb3ce4afffd44d9bf
+  data.tar.gz: 500f1b5415426ab0ef8036a7ef5539b694f4284787362f0db22bf527fff040b5c2e14634a5fe156b7c5b207ad47219f1ba9846a929a3403f1511e2285830ac22

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 (2026-07-06)
+
+Initial release.
+
+- Full coverage of the mailfloss v1 public API (all 26 endpoints):
+  verification (`/verify`, `/batch-verify` + status/results/cancel),
+  jobs, users, usage reports, `/check-key`, account (read + update),
+  organization, integrations (list/detail + connection
+  create/get/update/delete/sync/test + keyword rule list/add/delete),
+  and erasures.
+- Zero runtime dependencies — stdlib `Net::HTTP`, `JSON`, `SecureRandom`.
+- Automatic retries on 429/5xx (honoring `Retry-After`) and transient
+  connection errors, with exponential backoff and full jitter.
+- Automatic `Idempotency-Key` on every POST (caller-overridable).
+- Typed errors: `Mailfloss::APIError` with `status`, `code`, `type`,
+  `request_id`.
+- RBS type signatures under `sig/`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailfloss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# mailfloss — official Ruby SDK
+
+Ruby client for the [mailfloss](https://mailfloss.com) email verification API.
+Zero runtime dependencies (stdlib `Net::HTTP`), Ruby 2.6+.
+
+API reference: https://developers.mailfloss.com
+
+## Installation
+
+```sh
+gem install mailfloss
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "mailfloss", "~> 0.1"
+```
+
+## Authentication
+
+Grab an API key from your mailfloss dashboard, then either pass it
+directly:
+
+```ruby
+require "mailfloss"
+
+client = Mailfloss::Client.new(api_key: "mf_rk_your_key")
+```
+
+...or set the `MAILFLOSS_API_KEY` environment variable and omit the kwarg:
+
+```sh
+export MAILFLOSS_API_KEY="mf_rk_your_key"
+```
+
+```ruby
+client = Mailfloss::Client.new
+```
+
+If no key is available in either place, `Mailfloss::ConfigurationError` is
+raised. The key is sent as `Authorization: Bearer <key>` on every request.
+
+## Quickstart
+
+### Verify a single email — `GET /v1/verify`
+
+```ruby
+result = client.verify(email: "jane@acme.com")
+
+result[:status]      # "passed" | "undeliverable" | "risky" | "unknown"
+result[:passed]      # true
+result[:reason]      # e.g. "valid"
+result[:domain]      # "acme.com"
+result[:disposable]  # false
+result[:role]        # false
+result[:free]        # false
+result[:suggestion]  # typo suggestion, when detected
+```
+
+### Batch verification — `POST /v1/batch-verify`
+
+```ruby
+batch = client.batch_verify.create(
+  emails: ["jane@acme.com", "bob@invalid.example"],
+  webhook_url: "https://hooks.example.com/mailfloss-done" # optional callback
+)
+batch[:id] # => the batch job id
+
+# Poll progress
+status = client.batch_verify.status(batch[:id])
+status[:status]   # e.g. "processing"
+status[:progress] # 0.0..1.0
+
+# Page through results when done
+page = client.batch_verify.results(batch[:id], per_page: 100)
+page[:results]
+
+# Or cancel
+client.batch_verify.cancel(batch[:id]) # => { success: true }
+```
+
+All responses are JSON parsed with **symbol keys**.
+
+## Full surface
+
+| Resource | Methods |
+|---|---|
+| `client.verify(email:, timeout: nil)` | GET /verify |
+| `client.batch_verify` | `.create(emails:, webhook_url: nil)` · `.status(id)` · `.results(id, per_page:, next_cursor:)` · `.cancel(id)` |
+| `client.jobs` | `.list(per_page:, cursor:, source:, status:)` · `.get(id)` |
+| `client.users` | `.list(per_page:, cursor:)` · `.get(user_id)` |
+| `client.reports` | `.usage(period:, connection_id:)` — period: `this_week` / `this_month` / `this_year` / `lifetime` |
+| `client.check_key(...)` | GET /check-key |
+| `client.account` | `.get` · `.update(name:, organization:, phone:, vat_id:, country:, address:, notifications:)` |
+| `client.organization` | `.get` — plan, credits, usage, trial, entitlements |
+| `client.integrations` | `.list(per_page:, cursor:)` · `.get(type)` |
+| `client.integrations.connections` | `.create(type, credentials:, name:)` · `.get(type, id)` · `.update(type, id, aggressiveness:, manual_mode:, autofloss:, decay_protection:, action:, checks:)` · `.delete(type, id)` · `.sync(type, id)` · `.test(type, id)` |
+| `client.integrations.keywords` | `.list(type, id, list, per_page:, cursor:)` · `.add(type, id, list, rules:)` · `.delete(type, id, list, rule_id)` — list: `"blacklist"` / `"whitelist"` |
+| `client.erasures` | `.create(emails:, webhook_url: nil)` — GDPR/CCPA data erasure |
+
+List endpoints return a cursor-paginated envelope:
+
+```ruby
+page = client.jobs.list(per_page: 50)
+page[:data]                      # => [{ id:, status:, source:, ... }, ...]
+page[:pagination][:has_more]     # => true
+page[:pagination][:next_cursor]  # opaque — pass back as cursor:
+```
+
+### Example: connect an ESP and add keyword rules
+
+```ruby
+conn = client.integrations.connections.create(
+  "klaviyo",
+  credentials: { api_key: "pk_..." },
+  name: "Main Klaviyo account"
+)
+
+client.integrations.connections.update("klaviyo", conn[:id], autofloss: true)
+
+client.integrations.keywords.add(
+  "klaviyo", conn[:id], "whitelist",
+  rules: [{ keyword: "vip", match: "contains", applies_to: { domain: true } }]
+)
+```
+
+## Configuration
+
+```ruby
+client = Mailfloss::Client.new(
+  api_key:     "mf_rk_...",                     # or ENV["MAILFLOSS_API_KEY"]
+  base_url:    "https://api.mailfloss.com/v1",  # default
+  max_retries: 3,                               # retries after the first attempt
+  timeout:     30,                              # seconds (open/read)
+  transport:   nil                              # injectable, see below
+)
+```
+
+### Retries
+
+429 and 5xx responses are retried automatically (as are transient
+connection errors). A `Retry-After` header with integer seconds is
+honored; otherwise exponential backoff with full jitter is used
+(base 0.5s, factor 2, capped at 8s).
+
+### Idempotency
+
+Every `POST` carries an `Idempotency-Key` header — a fresh
+`SecureRandom.uuid` per call by default. Pass `idempotency_key:` on any
+create/cancel/sync/test call to supply your own (useful when you retry at
+the application level):
+
+```ruby
+client.batch_verify.create(emails: emails, idempotency_key: "import-2026-07-06")
+```
+
+### Errors
+
+Non-2xx responses raise `Mailfloss::APIError` (< `Mailfloss::Error`):
+
+```ruby
+begin
+  client.jobs.get("nope")
+rescue Mailfloss::APIError => e
+  e.status      # 404
+  e.code        # "not_found"
+  e.message     # human-readable message
+  e.type        # error type, when provided
+  e.request_id  # for support requests
+end
+```
+
+### Custom transport
+
+The low-level transport is injectable — any object responding to
+`call(method, url, headers, body)` and returning an object with `status`,
+`headers`, and `body`. This is how the test suite mocks HTTP without a
+network:
+
+```ruby
+fake = ->(method, url, headers, body) {
+  Mailfloss::Transport::Response.new(200, {}, '{"passed":true,"email":"a@b.com","status":"passed","reason":"valid"}')
+}
+client = Mailfloss::Client.new(api_key: "test", transport: fake)
+```
+
+## Type signatures
+
+RBS signatures for the client, resources, and all response shapes
+(hand-derived from the OpenAPI spec) ship under `sig/`.
+
+## Development
+
+```sh
+ruby test/run_tests.rb
+# or
+ruby -Ilib -Itest test/mailfloss_test.rb
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/mailfloss/client.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "uri"
+
+module Mailfloss
+  # Entry point for the mailfloss API.
+  #
+  #   client = Mailfloss::Client.new(api_key: "mf_rk_...")
+  #   client.verify(email: "jane@acme.com")
+  #
+  # The API key falls back to ENV["MAILFLOSS_API_KEY"] when the kwarg is
+  # omitted. All requests are retried automatically on 429 / 5xx (honoring
+  # Retry-After) and on transient connection errors.
+  class Client
+    DEFAULT_BASE_URL = "https://api.mailfloss.com/v1"
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_TIMEOUT = 30
+    RETRY_BASE_DELAY = 0.5
+    RETRY_MAX_DELAY = 8.0
+    USER_AGENT = "mailfloss-ruby/#{VERSION}"
+
+    attr_reader :base_url, :max_retries, :timeout
+
+    # @param api_key [String, nil] falls back to ENV["MAILFLOSS_API_KEY"]
+    # @param base_url [String]
+    # @param max_retries [Integer] retries after the initial attempt
+    # @param timeout [Numeric] per-request open/read timeout in seconds
+    # @param transport [#call, nil] injectable transport:
+    #   call(method, url, headers, body) -> #status/#headers/#body
+    # @param sleeper [#call, nil] injectable sleep proc (tests pass ->(_s){})
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, max_retries: DEFAULT_MAX_RETRIES,
+                   timeout: DEFAULT_TIMEOUT, transport: nil, sleeper: nil)
+      @api_key = api_key || ENV["MAILFLOSS_API_KEY"]
+      if @api_key.nil? || @api_key.to_s.strip.empty?
+        raise ConfigurationError,
+              "No API key. Pass api_key: to Mailfloss::Client.new or set the " \
+              "MAILFLOSS_API_KEY environment variable."
+      end
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @max_retries = max_retries
+      @timeout = timeout
+      @transport = transport || Transport.new(timeout: timeout)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    # -- Resource namespaces --------------------------------------------------
+
+    # GET /verify — single-email verification.
+    #
+    # @param email [String] the address to verify
+    # @param timeout [Numeric, String, nil] optional per-request timeout (seconds)
+    # @return [Hash] { email:, domain:, status:, reason:, passed:, role:,
+    #                  disposable:, free:, suggestion:, meta: }
+    def verify(email:, timeout: nil)
+      request(:get, "/verify", query: { email: email, timeout: timeout })
+    end
+
+    # GET /check-key — validate an API key and optionally return plan/credits.
+    #
+    # @return [Hash] { name:, organization:, planType:, freeMatches:, extraCredits: }
+    def check_key(api_key: nil, public_key: nil, check_plan: nil, get_token: nil, check_credits: nil)
+      request(:get, "/check-key", query: {
+                api_key: api_key, public_key: public_key, check_plan: check_plan,
+                get_token: get_token, check_credits: check_credits
+              })
+    end
+
+    def batch_verify
+      @batch_verify ||= Resources::BatchVerify.new(self)
+    end
+
+    def jobs
+      @jobs ||= Resources::Jobs.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    def reports
+      @reports ||= Resources::Reports.new(self)
+    end
+
+    def account
+      @account ||= Resources::Account.new(self)
+    end
+
+    def organization
+      @organization ||= Resources::Organization.new(self)
+    end
+
+    def integrations
+      @integrations ||= Resources::Integrations.new(self)
+    end
+
+    def erasures
+      @erasures ||= Resources::Erasures.new(self)
+    end
+
+    # -- Request plumbing -----------------------------------------------------
+
+    # Perform an authenticated request against the API.
+    #
+    # @param method [Symbol] :get, :post, :patch, :delete
+    # @param path [String] resource path relative to base_url (e.g. "/verify")
+    # @param query [Hash, nil] query params; nil values are dropped
+    # @param body [Hash, nil] JSON-serialized when present
+    # @param idempotency_key [String, nil] POST only; auto-generated when nil
+    # @return [Object, nil] parsed JSON (symbolized keys), or nil on empty body
+    def request(method, path, query: nil, body: nil, idempotency_key: nil)
+      url = build_url(path, query)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => USER_AGENT
+      }
+      headers["Content-Type"] = "application/json" if body
+      if method == :post
+        headers["Idempotency-Key"] = idempotency_key || SecureRandom.uuid
+      end
+      payload = body ? JSON.generate(body) : nil
+
+      response = perform_with_retries(method, url, headers, payload)
+      status = response_status(response)
+      raise APIError.new(status: status, body: response_body(response)) unless (200..299).cover?(status)
+
+      parse_body(response_body(response))
+    end
+
+    private
+
+    def build_url(path, query)
+      url = @base_url + path
+      if query
+        pairs = query.reject { |_k, v| v.nil? }
+        url += "?#{URI.encode_www_form(pairs)}" unless pairs.empty?
+      end
+      url
+    end
+
+    def perform_with_retries(method, url, headers, payload)
+      attempt = 0
+      begin
+        response = @transport.call(method, url, headers, payload)
+        status = response_status(response)
+        if retryable_status?(status) && attempt < @max_retries
+          delay = retry_after_seconds(response) || backoff_delay(attempt)
+          attempt += 1
+          @sleeper.call(delay)
+          raise RetrySignal
+        end
+        response
+      rescue RetrySignal
+        retry
+      rescue *Transport::CONNECTION_ERRORS => e
+        raise Error, "Connection error: #{e.class}: #{e.message}" unless attempt < @max_retries
+
+        @sleeper.call(backoff_delay(attempt))
+        attempt += 1
+        retry
+      end
+    end
+
+    RetrySignal = Class.new(StandardError)
+    private_constant :RetrySignal
+
+    def retryable_status?(status)
+      status == 429 || (500..599).cover?(status)
+    end
+
+    def retry_after_seconds(response)
+      headers = response_headers(response)
+      value = headers.find { |k, _v| k.to_s.downcase == "retry-after" }
+      return nil unless value
+
+      seconds = value[1].to_s
+      /\A\d+\z/.match?(seconds) ? seconds.to_i : nil
+    end
+
+    # Exponential backoff with full jitter: rand(0..min(cap, base * 2**attempt))
+    def backoff_delay(attempt)
+      cap = [RETRY_MAX_DELAY, RETRY_BASE_DELAY * (2**attempt)].min
+      rand * cap
+    end
+
+    def response_status(response)
+      response.respond_to?(:status) ? response.status : response.fetch(:status)
+    end
+
+    def response_headers(response)
+      value = response.respond_to?(:headers) ? response.headers : response[:headers]
+      value || {}
+    end
+
+    def response_body(response)
+      response.respond_to?(:body) ? response.body : response[:body]
+    end
+
+    def parse_body(body)
+      return nil if body.nil? || body.strip.empty?
+
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      body
+    end
+  end
+end

data/lib/mailfloss/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Mailfloss
+  # Base error class for everything raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when the client is misconfigured (e.g. no API key available).
+  class ConfigurationError < Error; end
+
+  # Raised when the API responds with a non-2xx status.
+  #
+  # The mailfloss API returns errors in the envelope:
+  #   { "error": { "code": "...", "message": "...", "type": "...", "request_id": "..." } }
+  #
+  # When the body is not JSON (or not in that envelope) the error degrades
+  # gracefully: +code+ becomes "unknown_error" and +message+ falls back to
+  # the raw body / a generic message.
+  class APIError < Error
+    attr_reader :status, :code, :type, :request_id
+
+    def initialize(status:, body: nil)
+      @status = status
+      parsed = parse_error(body)
+      @code = parsed[:code]
+      @type = parsed[:type]
+      @request_id = parsed[:request_id]
+      super(parsed[:message])
+    end
+
+    private
+
+    def parse_error(body)
+      fallback = {
+        code: "unknown_error",
+        message: default_message(body),
+        type: nil,
+        request_id: nil
+      }
+      return fallback if body.nil? || body.empty?
+
+      data = JSON.parse(body)
+      err = data.is_a?(Hash) ? data["error"] : nil
+      return fallback unless err.is_a?(Hash)
+
+      {
+        code: err["code"] || "unknown_error",
+        message: err["message"] || default_message(body),
+        type: err["type"],
+        request_id: err["request_id"]
+      }
+    rescue JSON::ParserError
+      fallback
+    end
+
+    def default_message(body)
+      snippet = body.to_s.strip
+      if snippet.empty?
+        "HTTP #{@status}"
+      else
+        "HTTP #{@status}: #{snippet[0, 200]}"
+      end
+    end
+  end
+end