millionsend 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da6448e6cf8b24c1c2badb8bb4c4d4904d873882ede341fefdbcb6949561753e
-  data.tar.gz: e68c0e3c988f18fee505aa780fbfc1974593da463f1aba01162eff0e50d4a0b4
+  metadata.gz: 3a05f5a8a6f73d20210b65a538c84b985206374628dd5298793c01d37bd9138f
+  data.tar.gz: 7fe8ff20393c98a38072d70617e0df869aefebdb14a577db320f8514d17eca05
 SHA512:
-  metadata.gz: dc6a03a18b27ff92b46203c37df82eed46687420b14ac010e7b671ca6506f4f4c008e9177728c4640bb8aff3019f67fd7dbf23b9636a64a75b48cbfc658e2007
-  data.tar.gz: f5988d2662081f5bb34323cf482c10fc3762051b0b44e307a391cb867214d6dd6306664b052ed5f59e6ea5e2ef0e9187f6dba582c1c1b9c5ca4341ecdc076c4d
+  metadata.gz: ec4a59041ec45a8c620b9fa2ff618971273b0dc6ba43ba75e758cec70653978e9a428249acd52c060b79ab83cdc70b5f119b019b2407b2ce802f2407444cbee9
+  data.tar.gz: 2fc47253ed0511c373c8273f84457ad90f812db1d4d6d9df8c4d58019780e34e484681239679033f9b9d0ca435cebac24c19f23f5438c26cd92c2d388bf6be85

data/README.md

@@ -48,12 +48,17 @@ 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`, `audience_id`).
+the wire's snake_case: `reply_to`, `scheduled_at`, `segment_id`).
 
 ## Resources
 
@@ -61,7 +66,8 @@ the wire's snake_case: `reply_to`, `scheduled_at`, `audience_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
@@ -70,28 +76,25 @@ Millionsend::Batch.send([payload_a, payload_b], idempotency_key: "run-7") # up t
 `to`, `cc`, `bcc` and `reply_to` accept either a string or an array. `Emails.create` is
 an alias of `Emails.send` (as is `Batch.create`), mirroring Resend.
 
-### Audiences & contacts
+### Contacts
+
+Contacts are team-global — one list per team, no audiences.
 
 ```ruby
-audience = Millionsend::Audiences.create(name: "Registered users")
-Millionsend::Audiences.list(limit: 20, after: cursor)
-Millionsend::Audiences.get(id)
-Millionsend::Audiences.remove(id)
-
-Millionsend::Contacts.create(audience_id: audience[:id], email: "ada@acme.dev",
-                             first_name: "Ada", properties: { plan: "pro" })
-Millionsend::Contacts.get("ada@acme.dev", audience_id: audience[:id]) # by id or email
-Millionsend::Contacts.get(contact_id)                                  # top-level, by id
-Millionsend::Contacts.update(id: contact_id, unsubscribed: true, first_name: nil) # nil clears
-Millionsend::Contacts.remove("ada@acme.dev", audience_id: audience[:id])
-Millionsend::Contacts.list(audience_id: audience[:id], limit: 50)
+contact = Millionsend::Contacts.create(email: "ada@acme.dev", first_name: "Ada",
+                                       properties: { plan: "pro" })
+Millionsend::Contacts.get("ada@acme.dev") # by id or email
+Millionsend::Contacts.update(id: contact[:id], unsubscribed: true, first_name: nil) # nil clears
+Millionsend::Contacts.remove("ada@acme.dev")
+Millionsend::Contacts.list(limit: 50)
 
 # Topic subscriptions (granular unsubscribe) — mirrors resend's contacts.topics.update
 Millionsend::Contacts.topics_update("ada@acme.dev", [{ id: topic_id, subscription: "opt_out" }])
 ```
 
 Contacts are addressable by id or email; when an `update` hash carries both, the email wins.
-Omit `audience_id:` to use the top-level `/contacts` endpoints.
+Emails are unique per team (case-insensitive) — a duplicate `create` raises
+`Millionsend::ValidationError`.
 
 ### Topics
 
@@ -106,7 +109,7 @@ Millionsend::Topics.remove(id)
 
 ```ruby
 broadcast = Millionsend::Broadcasts.create(
-  audience_id: audience[:id],
+  segment_id: segment[:id], # optional; omit segment_id and topic_id to send to all contacts
   from: "Acme <news@acme.dev>",
   subject: "Launch",
   html: "<p>Hi {{{FIRST_NAME|there}}}</p>"
@@ -121,13 +124,12 @@ Millionsend::Broadcasts.remove(broadcast[:id]) # draft only
 
 ### Segments (MillionSend extension)
 
-Dynamic segments are a saved filter over an audience's contacts — a MillionSend superset with
-no Resend equivalent, served under `/segments2`.
+Dynamic segments are a saved filter over the team's contacts — a MillionSend superset with
+no Resend equivalent.
 
 ```ruby
 segment = Millionsend::Segments.create(
   name: "Pro plan",
-  audience_id: audience[:id],
   filter: { match: "all", conditions: [{ field: "property:plan", op: "equals", value: "pro" }] }
 )
 Millionsend::Segments.get(segment[:id]) # includes a live contact_count
@@ -136,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`,
@@ -174,8 +189,9 @@ Method names, nesting and payloads match. Notes:
   are no `Domains` / `ApiKeys` resources here.
 - Resend's `Contacts.topics.update` becomes `Millionsend::Contacts.topics_update` (Ruby has no
   nested-module method on a module function).
-- `Millionsend::Segments` is the distinct dynamic-filter feature (`/segments2`), not Resend's
-  audiences alias. Use `Millionsend::Audiences` for a straight port.
+- **No audiences** — contacts are team-global, so there is no `Audiences` resource and no
+  `audience_id` params. `Millionsend::Segments` is the dynamic-filter feature (`/segments`),
+  not Resend's audiences alias.
 
 ## License
 

data/lib/millionsend/broadcasts.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Millionsend
-  # Broadcasts — one email sent to a whole audience or segment.
+  # Broadcasts — one email sent to a segment, a topic's subscribers, or every
+  # contact (pass neither segment_id nor topic_id).
   module Broadcasts
     class << self
       # POST /broadcasts

data/lib/millionsend/contacts.rb

@@ -1,59 +1,51 @@
 # frozen_string_literal: true
 
 module Millionsend
-  # Contacts live inside an audience or at the top level, and are addressable by
-  # id or by email (email wins when an update hash carries both).
+  # Contacts are team-global and addressable by id or by email (email wins when
+  # an update hash carries both).
   module Contacts
     class << self
-      # POST /audiences/:audience_id/contacts (or /contacts). audience_id is
-      # addressing, not a body field, so it is stripped from the payload.
+      # POST /contacts
       def create(params)
-        body = params.reject { |k, _| k == :audience_id }
-        Millionsend::Request.new(method: :post, path: collection_path(params[:audience_id]), body: body).perform
+        Millionsend::Request.new(method: :post, path: "/contacts", body: params).perform
       end
 
       # GET a single contact by id or email.
-      def get(id_or_email, audience_id: nil)
-        Millionsend::Request.new(method: :get, path: member_path(id_or_email, audience_id)).perform
+      def get(id_or_email)
+        Millionsend::Request.new(method: :get, path: member_path(id_or_email)).perform
       end
 
-      # PATCH a contact. Addressing keys (:audience_id, :id, :email) are pulled
-      # out; everything else is the body. A nil value clears a field; omit a key
-      # to leave it unchanged.
+      # PATCH a contact. Addressing keys (:id, :email) are pulled out;
+      # everything else is the body. A nil value clears a field; omit a key to
+      # leave it unchanged.
       def update(params)
         key = params[:email] || params[:id]
-        body = params.reject { |k, _| [:audience_id, :id, :email].include?(k) }
-        Millionsend::Request.new(method: :patch, path: member_path(key, params[:audience_id]), body: body).perform
+        body = params.reject { |k, _| [:id, :email].include?(k) }
+        Millionsend::Request.new(method: :patch, path: member_path(key), body: body).perform
       end
 
       # DELETE a contact by id or email.
-      def remove(id_or_email, audience_id: nil)
-        Millionsend::Request.new(method: :delete, path: member_path(id_or_email, audience_id)).perform
+      def remove(id_or_email)
+        Millionsend::Request.new(method: :delete, path: member_path(id_or_email)).perform
       end
 
-      # GET a list of contacts; pass audience_id: to scope it, plus limit:/after:/before:.
+      # GET /contacts — accepts limit:/after:/before:.
       def list(options = {})
         Millionsend::Request.new(
-          method: :get, path: collection_path(options[:audience_id]), query: Millionsend::Util.list_query(options)
+          method: :get, path: "/contacts", query: Millionsend::Util.list_query(options)
         ).perform
       end
 
       # PATCH /contacts/:id_or_email/topics with a bare array of
       # { id:, subscription: }. Mirrors resend-ruby's contacts.topics.update.
       def topics_update(id_or_email, topics)
-        path = "/contacts/#{Millionsend::Util.encode(id_or_email)}/topics"
-        Millionsend::Request.new(method: :patch, path: path, body: topics).perform
+        Millionsend::Request.new(method: :patch, path: "#{member_path(id_or_email)}/topics", body: topics).perform
       end
 
       private
 
-      def collection_path(audience_id)
-        audience_id ? "/audiences/#{Millionsend::Util.encode(audience_id)}/contacts" : "/contacts"
-      end
-
-      def member_path(id_or_email, audience_id)
-        key = Millionsend::Util.encode(id_or_email)
-        audience_id ? "/audiences/#{Millionsend::Util.encode(audience_id)}/contacts/#{key}" : "/contacts/#{key}"
+      def member_path(id_or_email)
+        "/contacts/#{Millionsend::Util.encode(id_or_email)}"
       end
     end
   end

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/segments.rb

@@ -1,35 +1,35 @@
 # frozen_string_literal: true
 
 module Millionsend
-  # Dynamic segments — a saved filter over an audience's contacts. A MillionSend
-  # extension with no Resend equivalent; served under /segments2.
+  # Dynamic segments — a saved filter over the team's contacts. A MillionSend
+  # extension with no Resend equivalent.
   module Segments
     class << self
-      # POST /segments2
+      # POST /segments
       def create(params)
-        Millionsend::Request.new(method: :post, path: "/segments2", body: params).perform
+        Millionsend::Request.new(method: :post, path: "/segments", body: params).perform
       end
 
-      # GET /segments2/:id — also returns a live contact_count.
+      # GET /segments/:id — also returns a live contact_count.
       def get(id)
-        Millionsend::Request.new(method: :get, path: "/segments2/#{Millionsend::Util.encode(id)}").perform
+        Millionsend::Request.new(method: :get, path: "/segments/#{Millionsend::Util.encode(id)}").perform
       end
 
-      # GET /segments2 — accepts limit:/after:/before:.
+      # GET /segments — accepts limit:/after:/before:.
       def list(options = {})
         Millionsend::Request.new(
-          method: :get, path: "/segments2", query: Millionsend::Util.list_query(options)
+          method: :get, path: "/segments", query: Millionsend::Util.list_query(options)
         ).perform
       end
 
-      # PATCH /segments2/:id
+      # PATCH /segments/:id
       def update(id, params)
-        Millionsend::Request.new(method: :patch, path: "/segments2/#{Millionsend::Util.encode(id)}", body: params).perform
+        Millionsend::Request.new(method: :patch, path: "/segments/#{Millionsend::Util.encode(id)}", body: params).perform
       end
 
-      # DELETE /segments2/:id
+      # DELETE /segments/:id
       def remove(id)
-        Millionsend::Request.new(method: :delete, path: "/segments2/#{Millionsend::Util.encode(id)}").perform
+        Millionsend::Request.new(method: :delete, path: "/segments/#{Millionsend::Util.encode(id)}").perform
       end
     end
   end

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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/millionsend.rb

@@ -6,11 +6,11 @@ require "millionsend/error"
 require "millionsend/request"
 require "millionsend/emails"
 require "millionsend/batch"
-require "millionsend/audiences"
 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:
@@ -22,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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - MillionSend
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -52,10 +52,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.19'
-description: 'Ruby client for the MillionSend HTTP API: emails, batch, audiences,
-  contacts, topics, broadcasts, and dynamic segments. Wire-compatible with Resend
-  and mirror-shaped after resend-ruby, so migrating is mostly an import swap plus
-  a base_url.'
+description: 'Ruby client for the MillionSend HTTP API: emails, batch, contacts, topics,
+  broadcasts, and dynamic segments. Wire-compatible with Resend and mirror-shaped
+  after resend-ruby, so migrating is mostly an import swap plus a base_url.'
 email:
 executables: []
 extensions: []
@@ -64,10 +63,10 @@ files:
 - LICENSE
 - README.md
 - lib/millionsend.rb
-- lib/millionsend/audiences.rb
 - 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

data/lib/millionsend/audiences.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Millionsend
-  # Audiences — named contact lists (Resend-compatible).
-  module Audiences
-    class << self
-      # POST /audiences
-      def create(params)
-        Millionsend::Request.new(method: :post, path: "/audiences", body: { name: params[:name] }).perform
-      end
-
-      # GET /audiences/:id
-      def get(id)
-        Millionsend::Request.new(method: :get, path: "/audiences/#{Millionsend::Util.encode(id)}").perform
-      end
-
-      # GET /audiences — accepts limit:/after:/before:.
-      def list(options = {})
-        Millionsend::Request.new(
-          method: :get, path: "/audiences", query: Millionsend::Util.list_query(options)
-        ).perform
-      end
-
-      # DELETE /audiences/:id
-      def remove(id)
-        Millionsend::Request.new(method: :delete, path: "/audiences/#{Millionsend::Util.encode(id)}").perform
-      end
-    end
-  end
-end