millionsend 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15bda7d83e77437273c93cad192bc1da266e48ffb560b29037c898e26cc825d
-  data.tar.gz: be0dbc70f2210ff128541664405e74278f03825a2ea3e5eaa7ef887ce8c73a3b
+  metadata.gz: 3a05f5a8a6f73d20210b65a538c84b985206374628dd5298793c01d37bd9138f
+  data.tar.gz: 7fe8ff20393c98a38072d70617e0df869aefebdb14a577db320f8514d17eca05
 SHA512:
-  metadata.gz: 2a851400dfdff77ecd956e54df92b6ce0bf8b201c471b5354734e43a27dae34d66dff76602d61ac347758da0ee027f3cd9d331653752097dd13d637f10a38a17
-  data.tar.gz: aded65d56245645bef51bf1aa9954caf9f212c7c73e88946d3e6bc39ec59849ef3c05fd522b5dc259548c2408b01c834b684cd3609874ff23df4c960837d7e6c
+  metadata.gz: ec4a59041ec45a8c620b9fa2ff618971273b0dc6ba43ba75e758cec70653978e9a428249acd52c060b79ab83cdc70b5f119b019b2407b2ce802f2407444cbee9
+  data.tar.gz: 2fc47253ed0511c373c8273f84457ad90f812db1d4d6d9df8c4d58019780e34e484681239679033f9b9d0ca435cebac24c19f23f5438c26cd92c2d388bf6be85

data/README.md

@@ -48,10 +48,15 @@ on any non-2xx response (see [Error handling](#error-handling)).
 Millionsend.api_key  = "ms_123"                # falls back to ENV["MILLIONSEND_API_KEY"]
 Millionsend.base_url = "https://mail.acme.dev" # falls back to ENV["MILLIONSEND_BASE_URL"],
                                                # then http://localhost:3001
+Millionsend.allow_insecure_http = false        # accept a non-loopback http:// base_url
 ```
 
 MillionSend is self-hosted, so there is no cloud default — **set `base_url` to your
 deployment in production.** An explicitly assigned value always wins over the environment.
+Plain `http://` is only accepted for loopback hosts (`localhost`, `127.0.0.1`, `::1`); any
+other `http://` URL raises `Millionsend::ApplicationError` on the first call, since the API
+key is sent as a bearer header. Set `allow_insecure_http = true` to talk to a non-TLS
+instance elsewhere (e.g. inside a private network).
 Params are symbol-keyed hashes and map straight to the wire (Ruby's snake_case is already
 the wire's snake_case: `reply_to`, `scheduled_at`, `segment_id`).
 
@@ -61,7 +66,8 @@ the wire's snake_case: `reply_to`, `scheduled_at`, `segment_id`).
 
 ```ruby
 Millionsend::Emails.send(payload, idempotency_key: "order-42") # POST /emails
-Millionsend::Emails.get(id)                                    # GET  /emails/:id
+Millionsend::Emails.get(id)                                    # GET  /emails/:id (includes score: 0-10 or nil)
+Millionsend::Emails.get_insights(id)                           # GET  /emails/:id/insights (404 until computed)
 Millionsend::Emails.cancel(id)                                 # POST /emails/:id/cancel (scheduled only)
 
 Millionsend::Batch.send([payload_a, payload_b], idempotency_key: "run-7") # up to 100
@@ -132,6 +138,19 @@ Millionsend::Segments.update(segment[:id], name: "Pro tier")
 Millionsend::Segments.remove(segment[:id])
 ```
 
+### Deliverability (MillionSend extension)
+
+Per-email best-practice insights and the account-level deliverability score.
+
+```ruby
+insights = Millionsend::Emails.get_insights(email[:id]) # score, band, checks: [{id:, severity:, status:, penalty:, detail:}]
+account  = Millionsend::Deliverability.get              # GET /deliverability — trailing-30-day account score
+puts account[:score] # 0-10 (one decimal) or nil when there is not enough data
+```
+
+Check ids and the band/severity/status values are an open set that grows across score
+versions — treat them as strings, not a closed enum.
+
 ## Error handling
 
 No `{ data, error }` tuple — a non-2xx response raises. The base class is `Millionsend::Error`,

data/lib/millionsend/deliverability.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Account-level deliverability score over the trailing window
+  # (scores are 0-10, one decimal; null means not enough data).
+  module Deliverability
+    class << self
+      # GET /deliverability
+      def get
+        Millionsend::Request.new(method: :get, path: "/deliverability").perform
+      end
+    end
+  end
+end

data/lib/millionsend/emails.rb

@@ -20,6 +20,14 @@ module Millionsend
         Millionsend::Request.new(method: :get, path: "/emails/#{Millionsend::Util.encode(id)}").perform
       end
 
+      # GET /emails/:id/insights — the pre-send best-practice report computed
+      # when the email was sent. 404 when the email is unknown or has no
+      # insights yet. Check ids and band/severity/status values are an open
+      # set that grows across score versions; they arrive as plain strings.
+      def get_insights(id)
+        Millionsend::Request.new(method: :get, path: "/emails/#{Millionsend::Util.encode(id)}/insights").perform
+      end
+
       # POST /emails/:id/cancel — scheduled, unsent emails only.
       def cancel(id)
         Millionsend::Request.new(method: :post, path: "/emails/#{Millionsend::Util.encode(id)}/cancel").perform

data/lib/millionsend/request.rb

@@ -65,6 +65,13 @@ module Millionsend
     def build_uri
       base = Millionsend.base_url.to_s.sub(%r{/+\z}, "")
       uri = URI.parse("#{base}#{@path}")
+      if !Millionsend.allow_insecure_http && Millionsend::Util.insecure_http?(uri)
+        raise Millionsend::ApplicationError.new(
+          "Refusing to send the API key over plain http to #{base}. " \
+          "Use https, or set Millionsend.allow_insecure_http = true.",
+          nil, "application_error"
+        )
+      end
       query = (@query || {}).reject { |_, v| v.nil? }
       uri.query = URI.encode_www_form(query) unless query.empty?
       uri

data/lib/millionsend/util.rb

@@ -16,6 +16,16 @@ module Millionsend
       URI.encode_www_form_component(value.to_s).gsub("+", "%20")
     end
 
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+    # True for an http:// URI whose host is not loopback.
+    def insecure_http?(uri)
+      return false unless uri.scheme == "http"
+
+      host = uri.host.to_s.downcase
+      !LOOPBACK_HOSTS.include?(host) && !host.start_with?("127.")
+    end
+
     # The keyset pagination params every list endpoint accepts. nil values are
     # dropped when the query string is built.
     def list_query(options)

data/lib/millionsend/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Millionsend
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/millionsend.rb

@@ -10,6 +10,7 @@ require "millionsend/contacts"
 require "millionsend/topics"
 require "millionsend/broadcasts"
 require "millionsend/segments"
+require "millionsend/deliverability"
 
 # Ruby client for the MillionSend HTTP API. Configure once, then call the
 # resource modules:
@@ -21,14 +22,17 @@ require "millionsend/segments"
 #
 # api_key falls back to the MILLIONSEND_API_KEY env var; base_url to
 # MILLIONSEND_BASE_URL and then http://localhost:3001 (MillionSend is
-# self-hosted, so there is no cloud default). Every call returns a symbol-keyed
-# Hash on success and raises a Millionsend::Error on any non-2xx response.
+# self-hosted, so there is no cloud default). Plain http is only accepted for
+# loopback hosts unless allow_insecure_http is set, since the API key travels
+# as a bearer header. Every call returns a symbol-keyed Hash on success and
+# raises a Millionsend::Error on any non-2xx response.
 module Millionsend
   DEFAULT_BASE_URL = "http://localhost:3001"
   USER_AGENT = "millionsend-ruby/#{VERSION}"
 
   class << self
     attr_writer :api_key, :base_url
+    attr_accessor :allow_insecure_http
 
     def api_key
       @api_key || ENV["MILLIONSEND_API_KEY"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: millionsend
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - MillionSend
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -66,6 +66,7 @@ files:
 - lib/millionsend/batch.rb
 - lib/millionsend/broadcasts.rb
 - lib/millionsend/contacts.rb
+- lib/millionsend/deliverability.rb
 - lib/millionsend/emails.rb
 - lib/millionsend/error.rb
 - lib/millionsend/request.rb