millionsend 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15bda7d83e77437273c93cad192bc1da266e48ffb560b29037c898e26cc825d
-  data.tar.gz: be0dbc70f2210ff128541664405e74278f03825a2ea3e5eaa7ef887ce8c73a3b
+  metadata.gz: f44b4a952ce5037c565e1ba8071a29ddf7d2b7d875fd99cad7719e91155d3054
+  data.tar.gz: a6b58d948cd026fe50ff598cc46129d6e9c164de71453dcdd77855237c0376fd
 SHA512:
-  metadata.gz: 2a851400dfdff77ecd956e54df92b6ce0bf8b201c471b5354734e43a27dae34d66dff76602d61ac347758da0ee027f3cd9d331653752097dd13d637f10a38a17
-  data.tar.gz: aded65d56245645bef51bf1aa9954caf9f212c7c73e88946d3e6bc39ec59849ef3c05fd522b5dc259548c2408b01c834b684cd3609874ff23df4c960837d7e6c
+  metadata.gz: 4c16c5f8ee728136b872cc3f6a83d78052c62649c7b69497973d72845fb318669073078eb54406863fb0d83cd5336868896e098da794677b50667eefb4f0ec7f
+  data.tar.gz: d492c8d93ddcfff8e5f887f50aa7200fa0e30856effd041530a19a62cd2c2ad07ed47520c9f5fb57a32e4078103d6edad6619cb45cbba888cb94e0f01ff0faf8

data/README.md

@@ -48,54 +48,124 @@ 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.
-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`).
+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 go on the wire **exactly as given** — nothing is
+filtered or renamed (Ruby's snake_case is already the wire's snake_case: `reply_to`,
+`scheduled_at`, `segment_id`). A `nil` value is sent as JSON `null`, which is how the API
+clears a nullable field (`topic_id`, `first_name`, a template `alias`, …); omit the key to
+leave it unchanged.
+
+## Request options
+
+`Emails.send`, `Batch.send` and `Contacts::Batch.create` take a trailing options hash, in
+either of two shapes:
+
+```ruby
+Millionsend::Emails.send(payload, idempotency_key: "order-42")               # flat
+Millionsend::Emails.send(payload, options: { idempotency_key: "order-42" })  # resend-ruby keyword shape
+```
+
+| option             | header / query        | where                                   |
+| ------------------ | --------------------- | --------------------------------------- |
+| `idempotency_key`  | `Idempotency-Key`     | any POST                                |
+| `batch_validation` | `x-batch-validation`  | `Batch.send`, `Contacts::Batch.create`  |
+| `on_conflict`      | `?on_conflict=`       | `Contacts::Batch.create`                |
+
+`batch_validation` is `"strict"` by default (one invalid item rejects the whole batch) or
+`"permissive"` (the valid subset is processed and the failures come back under `errors:`
+as `[{ index:, message: }]`).
 
 ## Resources
 
 ### Emails
 
 ```ruby
-Millionsend::Emails.send(payload, idempotency_key: "order-42") # POST /emails
-Millionsend::Emails.get(id)                                    # GET  /emails/:id
-Millionsend::Emails.cancel(id)                                 # POST /emails/:id/cancel (scheduled only)
-
-Millionsend::Batch.send([payload_a, payload_b], idempotency_key: "run-7") # up to 100
+Millionsend::Emails.send(payload, idempotency_key: "order-42") # POST  /emails
+Millionsend::Emails.get(id)                                    # GET   /emails/:id (includes score: 0-10 or nil)
+Millionsend::Emails.list(limit: 20, after: id)                 # GET   /emails
+Millionsend::Emails.update(id, scheduled_at: "in 2 hours")     # PATCH /emails/:id (scheduled only)
+Millionsend::Emails.cancel(id)                                 # POST  /emails/:id/cancel (scheduled only)
+Millionsend::Emails.remove(id)                                 # DELETE /emails/:id
+Millionsend::Emails.get_insights(id)                           # GET   /emails/:id/insights (404 until computed)
+
+Millionsend::Batch.send([payload_a, payload_b], idempotency_key: "run-7", batch_validation: "permissive") # up to 100
 ```
 
-`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.
+The send payload accepts `from`, `to`, `subject`, `html`, `text`, `cc`, `bcc`, `reply_to`,
+`scheduled_at`, `tags: [{ name:, value: }]`, `topic_id`, `headers: { "X-..." => "..." }`,
+`attachments: [{ filename:, content: <base64>, content_type:, content_id:, path: }]` and
+`template` (passed through; the server currently answers 422 for it). `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. `Emails.update` also takes resend-ruby's single
+hash: `Emails.update(email_id: id, scheduled_at: ...)`.
 
 ### Contacts
 
 Contacts are team-global — one list per team, no audiences.
 
 ```ruby
-contact = Millionsend::Contacts.create(email: "ada@acme.dev", first_name: "Ada",
-                                       properties: { plan: "pro" })
-Millionsend::Contacts.get("ada@acme.dev") # by id or email
+contact = Millionsend::Contacts.create(
+  email: "ada@acme.dev", first_name: "Ada", last_name: "Lovelace", unsubscribed: false,
+  properties: { plan: "pro", seats: 3 },
+  segments: [{ id: segment_id }],
+  topics: [{ id: topic_id, subscription: "opt_in" }]
+)
+Millionsend::Contacts.get("ada@acme.dev") # by id or email; also resend-ruby's get(id: ...) / get(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" }])
+# Topic subscriptions (granular unsubscribe) — PATCH /contacts/:id/topics
+Millionsend::Contacts::Topics.update(email: "ada@acme.dev", topics: [{ id: topic_id, subscription: "opt_out" }]) # resend-ruby shape
+Millionsend::Contacts.topics_update("ada@acme.dev", [{ id: topic_id, subscription: "opt_out" }])                 # positional
+
+# Segment membership — POST / DELETE /contacts/:id/segments/:segment_id
+Millionsend::Contacts::Segments.add("ada@acme.dev", segment_id)
+Millionsend::Contacts::Segments.remove(contact_id: contact[:id], segment_id: segment_id) # resend-ruby shape
+
+# Bulk create (MillionSend extension) — up to 1000 per call
+result = Millionsend::Contacts::Batch.create(
+  [{ email: "a@acme.dev" }, { email: "b@acme.dev", first_name: "B" }],
+  on_conflict: "upsert",          # "error" (default) | "skip" | "upsert"
+  batch_validation: "permissive"  # "strict" (default) | "permissive"
+)
+result[:data]   # [{ index:, id:, status: "created" | "updated" | "skipped" }]
+result[:counts] # { created:, updated:, skipped:, failed: }
+result[:errors] # permissive mode only: [{ index:, message: }]
 ```
 
 Contacts are addressable by id or email; when an `update` hash carries both, the email wins.
 Emails are unique per team (case-insensitive) — a duplicate `create` raises
 `Millionsend::ValidationError`.
 
+### Contact properties
+
+Typed custom fields for contacts. `key` and `type` are fixed at creation.
+
+```ruby
+prop = Millionsend::ContactProperties.create(key: "plan", type: "string", fallback_value: "free")
+Millionsend::ContactProperties.get(prop[:id])
+Millionsend::ContactProperties.list(limit: 50)
+Millionsend::ContactProperties.update(prop[:id], fallback_value: nil) # nil clears
+Millionsend::ContactProperties.remove(prop[:id])
+```
+
 ### Topics
 
 ```ruby
-Millionsend::Topics.create(name: "Product updates", default_subscription: "opt_in")
+Millionsend::Topics.create(name: "Product updates", default_subscription: "opt_in", visibility: "public")
 Millionsend::Topics.get(id)
 Millionsend::Topics.list    # bare { data: [...] } — topics are unpaginated
+Millionsend::Topics.update(id, name: "Product news")
 Millionsend::Topics.remove(id)
 ```
 
@@ -103,19 +173,104 @@ Millionsend::Topics.remove(id)
 
 ```ruby
 broadcast = Millionsend::Broadcasts.create(
+  name: "Launch",           # internal name shown in the dashboard
   segment_id: segment[:id], # optional; omit segment_id and topic_id to send to all contacts
+  topic_id: topic[:id],     # optional; only contacts subscribed to it receive it
   from: "Acme <news@acme.dev>",
   subject: "Launch",
-  html: "<p>Hi {{{FIRST_NAME|there}}}</p>"
+  html: "<p>Hi {{{FIRST_NAME|there}}}</p>",
+  text: "Hi",
+  reply_to: "hello@acme.dev",
+  preview_text: "It's here",
+  send: false,              # true sends (or, with scheduled_at, schedules) instead of saving a draft
+  scheduled_at: nil         # "2026-09-01T09:00:00Z" or "in 1 hour" (requires send: true)
 )
 Millionsend::Broadcasts.list
 Millionsend::Broadcasts.get(broadcast[:id])
-Millionsend::Broadcasts.update(broadcast[:id], subject: "Launch 🚀") # draft only
+Millionsend::Broadcasts.update(broadcast[:id], subject: "Launch 🚀", topic_id: nil) # draft only; nil clears
 Millionsend::Broadcasts.send(broadcast[:id], scheduled_at: "2026-09-01T09:00:00Z") # omit to send now
 Millionsend::Broadcasts.cancel(broadcast[:id]) # scheduled only
 Millionsend::Broadcasts.remove(broadcast[:id]) # draft only
 ```
 
+### Suppressions
+
+Addresses the API refuses to send to. Entries are addressable by id or by email.
+
+```ruby
+Millionsend::Suppressions.add(email: "bounced@example.com", origin: "manual") # origin: bounce | complaint | manual | unsubscribe
+Millionsend::Suppressions.get("bounced@example.com")
+Millionsend::Suppressions.list(limit: 50, origin: "bounce")
+Millionsend::Suppressions.remove("bounced@example.com")
+
+Millionsend::Suppressions::Batch.add(emails: ["a@example.com", "b@example.com"], origin: "unsubscribe") # up to 1000
+Millionsend::Suppressions::Batch.remove(emails: ["a@example.com"])   # or ids: [...]
+```
+
+`Suppressions.create` is an alias of `Suppressions.add`.
+
+### Domains
+
+```ruby
+domain = Millionsend::Domains.create(
+  name: "acme.dev",
+  region: "us-east-1",          # optional; a deployment serves one region
+  custom_return_path: "send",   # optional
+  open_tracking: true, click_tracking: true, tracking_subdomain: "links"
+)
+domain[:records] # DNS records to publish, each with its own status
+Millionsend::Domains.get(domain[:id])
+Millionsend::Domains.list
+Millionsend::Domains.verify(domain[:id]) # re-check DNS now
+Millionsend::Domains.update(domain[:id], open_tracking: false, click_tracking: true, tracking_subdomain: nil) # nil clears
+Millionsend::Domains.remove(domain[:id])
+```
+
+### Webhooks
+
+```ruby
+hook = Millionsend::Webhooks.create(
+  endpoint: "https://acme.dev/hooks/millionsend",
+  events: ["email.delivered", "email.bounced", "email.complained"],
+  signing_secret: "whsec_..." # optional: reuse an existing secret so the receiver keeps verifying
+)
+hook[:signing_secret]
+Millionsend::Webhooks.get(hook[:id]) # also returns signing_secret
+Millionsend::Webhooks.list
+Millionsend::Webhooks.update(hook[:id], events: ["email.opened"], status: "disabled")
+Millionsend::Webhooks.remove(hook[:id])
+```
+
+Events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`,
+`email.complained`, `email.opened`, `email.clicked`, `deliverability.warning`,
+`deliverability.paused`, `quota.warning`, `quota.reached`.
+
+### API keys
+
+```ruby
+key = Millionsend::ApiKeys.create(name: "ci", permission: "sending_access", domain_id: domain[:id])
+key[:token] # only returned here
+Millionsend::ApiKeys.list
+Millionsend::ApiKeys.remove(key[:id])
+```
+
+### Templates
+
+Addressable by id or alias.
+
+```ruby
+tpl = Millionsend::Templates.create(name: "Welcome", html: "<p>Hi</p>", subject: "Welcome", text: "Hi", alias: "welcome")
+Millionsend::Templates.get("welcome")
+Millionsend::Templates.list
+Millionsend::Templates.update("welcome", subject: nil, alias: nil) # nil clears subject/text/alias
+Millionsend::Templates.publish(tpl[:id])   # templates are always published; kept as a no-op for compatibility
+Millionsend::Templates.duplicate(tpl[:id]) # returns the copy's id
+Millionsend::Templates.remove(tpl[:id])
+```
+
+Resend's `from`, `reply_to` and `variables` template fields are passed through untouched; the
+server currently answers 422 for them.
+
 ### Segments (MillionSend extension)
 
 Dynamic segments are a saved filter over the team's contacts — a MillionSend superset with
@@ -128,10 +283,33 @@ segment = Millionsend::Segments.create(
 )
 Millionsend::Segments.get(segment[:id]) # includes a live contact_count
 Millionsend::Segments.list
+Millionsend::Segments.contacts(segment[:id], limit: 50) # the contacts currently matching
 Millionsend::Segments.update(segment[:id], name: "Pro tier")
 Millionsend::Segments.remove(segment[:id])
 ```
 
+### Usage (MillionSend extension)
+
+```ruby
+usage = Millionsend::Usage.get # GET /usage
+usage[:plan]                   # "free" | "pro" | "scale" | nil (self-hosted)
+usage[:limits]                 # { emails_per_day:, domains: } — nil means unlimited
+usage[:today]                  # { emails_sent:, resets_at: }
+```
+
+### 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`,
@@ -148,9 +326,11 @@ rescue Millionsend::Error => e
 end
 ```
 
-Subclasses: `ValidationError`, `NotFoundError`, `RestrictedApiKeyError`, `SendingPausedError`,
-`InvalidIdempotentRequestError`, and `ApplicationError` (the fallback). Client-side and
-transport failures that never reached the API raise with `#status_code == nil`.
+Subclasses: `ValidationError`, `NotFoundError`, `MissingApiKeyError`, `InvalidApiKeyError`,
+`RestrictedApiKeyError`, `SendingPausedError`, `BroadcastsPausedError`, `RateLimitExceededError`,
+`DailyQuotaExceededError`, `InvalidIdempotentRequestError`, `ConcurrentIdempotentRequestsError`,
+`InternalServerError`, and `ApplicationError` (the fallback for unknown names). Client-side and
+transport failures that never reached the API raise `ApplicationError` with `#status_code == nil`.
 
 ## Migrating from Resend
 
@@ -164,15 +344,25 @@ transport failures that never reached the API raise with `#status_code == nil`.
 + Millionsend::Emails.send(from: "...", to: "...", subject: "Hi", html: "<p>hi</p>")
 ```
 
-Method names, nesting and payloads match. Notes:
-
-- **Domains and API keys** are managed in the MillionSend dashboard, not via the API, so there
-  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).
+Method names, nesting and payloads match; `options: { idempotency_key:, batch_validation: }`
+works as in resend-ruby. Notes:
+
+- **`update` takes the id first.** On domains, webhooks, contact properties, topics, broadcasts
+  and segments it is `update(id, params)` where resend-ruby takes one hash carrying the id
+  (`:id`, `:topic_id`, `:broadcast_id`, `:segment_id`); templates already match resend-ruby's
+  `update(id, params)`, `Contacts.update` keeps resend's single-hash shape, and `Emails.update`
+  accepts both.
+- `Contacts` member methods and `Contacts::Segments` / `Contacts::Topics` accept resend-ruby's
+  addressing hashes (`id:` / `email:` / `contact_id:`, `segment_id:`) as well as bare values.
+  `Suppressions::Batch` is nested as in resend-ruby.
 - **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.
+  `audience_id` params. The API's `/audiences/*` routes are a compatibility shim and are not
+  part of this SDK. `Millionsend::Segments` is the dynamic-filter feature (`/segments`), not
+  Resend's audiences alias.
+- Not in the API (yet), so not here: broadcast recipients/clicked links, email sharing and
+  metrics, contact imports, receiving, automations, logs, OAuth grants, webhook event replay.
+- MillionSend extensions with no Resend counterpart: `Segments`, `Contacts::Batch`, `Usage`,
+  `Deliverability`, `Emails.get_insights`, `Suppressions` `origin: "unsubscribe"`.
 
 ## License
 

data/lib/millionsend/api_keys.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # API keys. The token is only ever returned by create.
+  module ApiKeys
+    class << self
+      # POST /api-keys — name, permission ("full_access" default or
+      # "sending_access"), domain_id. Returns { id:, token: }.
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/api-keys", body: params).perform
+      end
+
+      # GET /api-keys — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(method: :get, path: "/api-keys", query: Millionsend::Util.list_query(options)).perform
+      end
+
+      # DELETE /api-keys/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: "/api-keys/#{Millionsend::Util.encode(id)}").perform
+      end
+    end
+  end
+end

data/lib/millionsend/batch.rb

@@ -4,11 +4,14 @@ module Millionsend
   # Send up to 100 emails in a single call.
   module Batch
     class << self
-      # POST /emails/batch with a bare array body. A trailing options hash
-      # carries idempotency_key (no keyword params, matching Emails.send).
+      # POST /emails/batch with a bare array body. The trailing hash carries
+      # idempotency_key and batch_validation ("strict", the default, rejects the
+      # whole batch on one invalid item; "permissive" sends the valid subset and
+      # lists the rest under errors[]) — either flat or under options:, like
+      # Emails.send.
       def send(list, options = {})
         Millionsend::Request.new(
-          method: :post, path: "/emails/batch", body: list, idempotency_key: options[:idempotency_key]
+          method: :post, path: "/emails/batch", body: list, **Millionsend::Util.request_options(options)
         ).perform
       end
       alias_method :create, :send

data/lib/millionsend/contact_properties.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Typed custom properties for contacts. key and type are fixed at creation;
+  # only fallback_value can change.
+  module ContactProperties
+    class << self
+      # POST /contact-properties — key, type ("string"/"number"), fallback_value.
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/contact-properties", body: params).perform
+      end
+
+      # GET /contact-properties/:id
+      def get(id)
+        Millionsend::Request.new(method: :get, path: member_path(id)).perform
+      end
+
+      # GET /contact-properties — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(
+          method: :get, path: "/contact-properties", query: Millionsend::Util.list_query(options)
+        ).perform
+      end
+
+      # PATCH /contact-properties/:id — fallback_value (nil clears it).
+      def update(id, params)
+        Millionsend::Request.new(method: :patch, path: member_path(id), body: params).perform
+      end
+
+      # DELETE /contact-properties/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: member_path(id)).perform
+      end
+
+      private
+
+      def member_path(id)
+        "/contact-properties/#{Millionsend::Util.encode(id)}"
+      end
+    end
+  end
+end

data/lib/millionsend/contacts.rb

@@ -5,7 +5,8 @@ module Millionsend
   # an update hash carries both).
   module Contacts
     class << self
-      # POST /contacts
+      # POST /contacts — email, first_name, last_name, unsubscribed, properties,
+      # segments: [{ id: }], topics: [{ id:, subscription: }].
       def create(params)
         Millionsend::Request.new(method: :post, path: "/contacts", body: params).perform
       end
@@ -19,9 +20,8 @@ module Millionsend
       # 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, _| [:id, :email].include?(k) }
-        Millionsend::Request.new(method: :patch, path: member_path(key), body: body).perform
+        Millionsend::Request.new(method: :patch, path: member_path(params), body: body).perform
       end
 
       # DELETE a contact by id or email.
@@ -37,16 +37,71 @@ module Millionsend
       end
 
       # PATCH /contacts/:id_or_email/topics with a bare array of
-      # { id:, subscription: }. Mirrors resend-ruby's contacts.topics.update.
+      # { id:, subscription: }. Contacts::Topics.update is the resend-ruby shape.
       def topics_update(id_or_email, topics)
         Millionsend::Request.new(method: :patch, path: "#{member_path(id_or_email)}/topics", body: topics).perform
       end
 
-      private
-
+      # Every member method also accepts resend-ruby's addressing hash
+      # ({ id: } / { email: } / { contact_id: }) in place of the bare value.
       def member_path(id_or_email)
+        id_or_email = id_or_email[:email] || id_or_email[:id] || id_or_email[:contact_id] if id_or_email.is_a?(Hash)
         "/contacts/#{Millionsend::Util.encode(id_or_email)}"
       end
     end
+
+    # Topic subscriptions of one contact, in resend-ruby's nested shape.
+    module Topics
+      class << self
+        # PATCH /contacts/:id_or_email/topics — { id: | email:, topics: [{ id:, subscription: }] }.
+        def update(params)
+          Millionsend::Contacts.topics_update(params, params[:topics])
+        end
+      end
+    end
+
+    # Bulk contact creation — a MillionSend extension (Resend imports via CSV).
+    module Batch
+      class << self
+        # POST /contacts/batch with a bare array of up to 1000 create payloads.
+        # Options (flat or under options:): on_conflict ("error" default,
+        # "skip", "upsert") for emails that already belong to a contact,
+        # batch_validation ("strict" default, "permissive" writes the valid
+        # subset and lists failures under errors[]), idempotency_key. Returns
+        # { data: [{ index:, id:, status: }], counts: {...}, errors: [...] }.
+        def create(list, options = {})
+          options = options[:options] if options.is_a?(Hash) && options.key?(:options)
+          Millionsend::Request.new(
+            method: :post, path: "/contacts/batch", body: list,
+            query: { on_conflict: options[:on_conflict] },
+            **Millionsend::Util.request_options(options)
+          ).perform
+        end
+      end
+    end
+
+    # Segment membership of one contact. Segments are dynamic filters, so this
+    # only applies to segments that hold an explicit member list.
+    module Segments
+      class << self
+        # POST /contacts/:id_or_email/segments/:segment_id. Takes
+        # (id_or_email, segment_id) or resend-ruby's { contact_id: | email:, segment_id: }.
+        def add(id_or_email, segment_id = nil)
+          Millionsend::Request.new(method: :post, path: path(id_or_email, segment_id)).perform
+        end
+
+        # DELETE /contacts/:id_or_email/segments/:segment_id — same shapes as add.
+        def remove(id_or_email, segment_id = nil)
+          Millionsend::Request.new(method: :delete, path: path(id_or_email, segment_id)).perform
+        end
+
+        private
+
+        def path(id_or_email, segment_id)
+          segment_id ||= id_or_email[:segment_id] if id_or_email.is_a?(Hash)
+          "#{Millionsend::Contacts.member_path(id_or_email)}/segments/#{Millionsend::Util.encode(segment_id)}"
+        end
+      end
+    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/domains.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Sending domains and their DNS records.
+  module Domains
+    class << self
+      # POST /domains — name, region, custom_return_path, open_tracking,
+      # click_tracking, tracking_subdomain. Returns the records to publish.
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/domains", body: params).perform
+      end
+
+      # GET /domains/:id — includes records[] with per-record status.
+      def get(id)
+        Millionsend::Request.new(method: :get, path: member_path(id)).perform
+      end
+
+      # GET /domains — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(method: :get, path: "/domains", query: Millionsend::Util.list_query(options)).perform
+      end
+
+      # PATCH /domains/:id — open_tracking, click_tracking, tracking_subdomain
+      # (nil or "" clears it).
+      def update(id, params)
+        Millionsend::Request.new(method: :patch, path: member_path(id), body: params).perform
+      end
+
+      # POST /domains/:id/verify — re-check DNS now.
+      def verify(id)
+        Millionsend::Request.new(method: :post, path: "#{member_path(id)}/verify").perform
+      end
+
+      # DELETE /domains/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: member_path(id)).perform
+      end
+
+      private
+
+      def member_path(id)
+        "/domains/#{Millionsend::Util.encode(id)}"
+      end
+    end
+  end
+end

data/lib/millionsend/emails.rb

@@ -1,28 +1,67 @@
 # frozen_string_literal: true
 
 module Millionsend
-  # Transactional email: send one, look it up, cancel a scheduled one.
+  # Transactional email: send one, look it up, reschedule or cancel a scheduled
+  # one, list what was sent. Params hashes go on the wire as-is (from, to, cc,
+  # bcc, reply_to, subject, html, text, headers, tags, attachments,
+  # scheduled_at, topic_id, template), so nothing a caller passes is dropped.
   module Emails
     class << self
       # POST /emails. Accepts a params hash or bare keywords
-      # (Emails.send(from: ..., to: ...)); a trailing options hash carries
-      # idempotency_key. No keyword parameters are declared on purpose — Ruby 3
-      # keyword separation would otherwise reject the bare-keyword call shape.
+      # (Emails.send(from: ..., to: ...)); a trailing hash carries the request
+      # options as either `idempotency_key: "k"` or resend-ruby's
+      # `options: { idempotency_key: "k" }`. No keyword parameters are declared
+      # on purpose — Ruby 3 keyword separation would otherwise reject the
+      # bare-keyword call shape.
       def send(params = {}, options = {})
         Millionsend::Request.new(
-          method: :post, path: "/emails", body: params, idempotency_key: options[:idempotency_key]
+          method: :post, path: "/emails", body: params, **Millionsend::Util.request_options(options)
         ).perform
       end
       alias_method :create, :send
 
       # GET /emails/:id
       def get(id)
-        Millionsend::Request.new(method: :get, path: "/emails/#{Millionsend::Util.encode(id)}").perform
+        Millionsend::Request.new(method: :get, path: member_path(id)).perform
+      end
+
+      # GET /emails — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(method: :get, path: "/emails", query: Millionsend::Util.list_query(options)).perform
+      end
+
+      # PATCH /emails/:id — reschedule a scheduled, unsent email. Takes
+      # (id, { scheduled_at: }) or resend-ruby's single hash with :email_id.
+      def update(id, params = nil)
+        if id.is_a?(Hash)
+          params = id.reject { |k, _| k == :email_id }
+          id = id[:email_id]
+        end
+        Millionsend::Request.new(method: :patch, path: member_path(id), body: params).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: "#{member_path(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
+        Millionsend::Request.new(method: :post, path: "#{member_path(id)}/cancel").perform
+      end
+
+      # DELETE /emails/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: member_path(id)).perform
+      end
+
+      private
+
+      def member_path(id)
+        "/emails/#{Millionsend::Util.encode(id)}"
       end
     end
   end

data/lib/millionsend/error.rb

@@ -32,17 +32,31 @@ module Millionsend
 
   class ValidationError < Error; end
   class NotFoundError < Error; end
+  class MissingApiKeyError < Error; end
+  class InvalidApiKeyError < Error; end
   class RestrictedApiKeyError < Error; end
   class SendingPausedError < Error; end
+  class BroadcastsPausedError < Error; end
+  class RateLimitExceededError < Error; end
+  class DailyQuotaExceededError < Error; end
   class InvalidIdempotentRequestError < Error; end
+  class ConcurrentIdempotentRequestsError < Error; end
+  class InternalServerError < Error; end
   class ApplicationError < Error; end
 
   ERROR_TYPES = {
     "validation_error" => ValidationError,
     "not_found" => NotFoundError,
+    "missing_api_key" => MissingApiKeyError,
+    "invalid_api_key" => InvalidApiKeyError,
     "restricted_api_key" => RestrictedApiKeyError,
     "sending_paused" => SendingPausedError,
+    "broadcasts_paused" => BroadcastsPausedError,
+    "rate_limit_exceeded" => RateLimitExceededError,
+    "daily_quota_exceeded" => DailyQuotaExceededError,
     "invalid_idempotent_request" => InvalidIdempotentRequestError,
+    "concurrent_idempotent_requests" => ConcurrentIdempotentRequestsError,
+    "internal_server_error" => InternalServerError,
     "application_error" => ApplicationError,
   }.freeze
 end

data/lib/millionsend/request.rb

@@ -26,12 +26,13 @@ module Millionsend
       Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
     ].freeze
 
-    def initialize(method:, path:, body: nil, query: nil, idempotency_key: nil)
+    def initialize(method:, path:, body: nil, query: nil, idempotency_key: nil, batch_validation: nil)
       @method = method
       @path = path
       @body = body
       @query = query
       @idempotency_key = idempotency_key
+      @batch_validation = batch_validation
     end
 
     def perform
@@ -65,6 +66,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
@@ -81,6 +89,7 @@ module Millionsend
       end
       # Idempotency is POST-only on the wire; ignored on other verbs.
       request["Idempotency-Key"] = @idempotency_key if @idempotency_key && @method == :post
+      request["x-batch-validation"] = @batch_validation.to_s if @batch_validation
       request
     end
 

data/lib/millionsend/segments.rb

@@ -22,6 +22,15 @@ module Millionsend
         ).perform
       end
 
+      # GET /segments/:id/contacts — the contacts currently matching, paginated
+      # with limit:/after:/before:.
+      def contacts(id, options = {})
+        Millionsend::Request.new(
+          method: :get, path: "/segments/#{Millionsend::Util.encode(id)}/contacts",
+          query: Millionsend::Util.list_query(options)
+        ).perform
+      end
+
       # PATCH /segments/:id
       def update(id, params)
         Millionsend::Request.new(method: :patch, path: "/segments/#{Millionsend::Util.encode(id)}", body: params).perform

data/lib/millionsend/suppressions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Suppression list — addresses the API refuses to send to. Entries are
+  # addressable by id or by email.
+  module Suppressions
+    class << self
+      # POST /suppressions — email, origin ("manual" default, "bounce",
+      # "complaint", "unsubscribe"). Adding an already suppressed address
+      # returns the existing entry.
+      def add(params)
+        Millionsend::Request.new(method: :post, path: "/suppressions", body: params).perform
+      end
+      alias_method :create, :add
+
+      # GET /suppressions — accepts limit:/after:/before: and origin:.
+      def list(options = {})
+        query = Millionsend::Util.list_query(options).merge(origin: options[:origin])
+        Millionsend::Request.new(method: :get, path: "/suppressions", query: query).perform
+      end
+
+      # GET /suppressions/:id_or_email
+      def get(id_or_email)
+        Millionsend::Request.new(method: :get, path: member_path(id_or_email)).perform
+      end
+
+      # DELETE /suppressions/:id_or_email — allows sending to that address again.
+      def remove(id_or_email)
+        Millionsend::Request.new(method: :delete, path: member_path(id_or_email)).perform
+      end
+
+      private
+
+      def member_path(id_or_email)
+        "/suppressions/#{Millionsend::Util.encode(id_or_email)}"
+      end
+    end
+
+    # Up to 1000 suppressions per call.
+    module Batch
+      class << self
+        # POST /suppressions/batch/add — { emails: [...], origin: }.
+        def add(params)
+          Millionsend::Request.new(method: :post, path: "/suppressions/batch/add", body: params).perform
+        end
+
+        # POST /suppressions/batch/remove — { emails: [...] } or { ids: [...] }.
+        def remove(params)
+          Millionsend::Request.new(method: :post, path: "/suppressions/batch/remove", body: params).perform
+        end
+      end
+    end
+  end
+end

data/lib/millionsend/templates.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Email templates, addressable by id or alias. Templates are always
+  # published: publish is kept as a no-op for resend-ruby compatibility.
+  module Templates
+    class << self
+      # POST /templates — name, html, subject, text, alias.
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/templates", body: params).perform
+      end
+
+      # GET /templates/:id_or_alias
+      def get(id_or_alias)
+        Millionsend::Request.new(method: :get, path: member_path(id_or_alias)).perform
+      end
+
+      # GET /templates — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(method: :get, path: "/templates", query: Millionsend::Util.list_query(options)).perform
+      end
+
+      # PATCH /templates/:id_or_alias — name, html, subject, text, alias; nil
+      # clears subject/text/alias.
+      def update(id_or_alias, params)
+        Millionsend::Request.new(method: :patch, path: member_path(id_or_alias), body: params).perform
+      end
+
+      # POST /templates/:id_or_alias/publish
+      def publish(id_or_alias)
+        Millionsend::Request.new(method: :post, path: "#{member_path(id_or_alias)}/publish").perform
+      end
+
+      # POST /templates/:id_or_alias/duplicate — returns the copy's id.
+      def duplicate(id_or_alias)
+        Millionsend::Request.new(method: :post, path: "#{member_path(id_or_alias)}/duplicate").perform
+      end
+
+      # DELETE /templates/:id_or_alias
+      def remove(id_or_alias)
+        Millionsend::Request.new(method: :delete, path: member_path(id_or_alias)).perform
+      end
+
+      private
+
+      def member_path(id_or_alias)
+        "/templates/#{Millionsend::Util.encode(id_or_alias)}"
+      end
+    end
+  end
+end

data/lib/millionsend/topics.rb

@@ -4,7 +4,7 @@ module Millionsend
   # Subscription topics — granular unsubscribe categories.
   module Topics
     class << self
-      # POST /topics
+      # POST /topics — name, default_subscription, description, visibility.
       def create(params)
         Millionsend::Request.new(method: :post, path: "/topics", body: params).perform
       end
@@ -19,6 +19,11 @@ module Millionsend
         Millionsend::Request.new(method: :get, path: "/topics").perform
       end
 
+      # PATCH /topics/:id — name, description, visibility.
+      def update(id, params)
+        Millionsend::Request.new(method: :patch, path: "/topics/#{Millionsend::Util.encode(id)}", body: params).perform
+      end
+
       # DELETE /topics/:id
       def remove(id)
         Millionsend::Request.new(method: :delete, path: "/topics/#{Millionsend::Util.encode(id)}").perform

data/lib/millionsend/usage.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Plan limits and today's send count — a MillionSend extension.
+  module Usage
+    class << self
+      # GET /usage
+      def get
+        Millionsend::Request.new(method: :get, path: "/usage").perform
+      end
+    end
+  end
+end

data/lib/millionsend/util.rb

@@ -16,11 +16,31 @@ 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)
       options ||= {}
       { limit: options[:limit], after: options[:after], before: options[:before] }
     end
+
+    # Per-request options for the Request constructor. Both call shapes land in
+    # the same trailing positional hash: the original `idempotency_key: "k"` and
+    # resend-ruby's keyword form `options: { idempotency_key: "k" }`, so the
+    # latter is unwrapped here.
+    def request_options(options)
+      options = options[:options] if options.is_a?(Hash) && options.key?(:options)
+      options ||= {}
+      { idempotency_key: options[:idempotency_key], batch_validation: options[:batch_validation] }
+    end
   end
 end

data/lib/millionsend/version.rb

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

data/lib/millionsend/webhooks.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Webhook endpoints. The signing secret is returned on create and on get.
+  module Webhooks
+    class << self
+      # POST /webhooks — endpoint, events[], signing_secret (optional; pass an
+      # existing whsec_ value to keep a receiver verifying unchanged).
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/webhooks", body: params).perform
+      end
+
+      # GET /webhooks/:id — includes signing_secret.
+      def get(id)
+        Millionsend::Request.new(method: :get, path: member_path(id)).perform
+      end
+
+      # GET /webhooks — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(method: :get, path: "/webhooks", query: Millionsend::Util.list_query(options)).perform
+      end
+
+      # PATCH /webhooks/:id — endpoint, events, status ("enabled"/"disabled").
+      def update(id, params)
+        Millionsend::Request.new(method: :patch, path: member_path(id), body: params).perform
+      end
+
+      # DELETE /webhooks/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: member_path(id)).perform
+      end
+
+      private
+
+      def member_path(id)
+        "/webhooks/#{Millionsend::Util.encode(id)}"
+      end
+    end
+  end
+end

data/lib/millionsend.rb

@@ -7,9 +7,17 @@ require "millionsend/request"
 require "millionsend/emails"
 require "millionsend/batch"
 require "millionsend/contacts"
+require "millionsend/contact_properties"
 require "millionsend/topics"
 require "millionsend/broadcasts"
 require "millionsend/segments"
+require "millionsend/suppressions"
+require "millionsend/domains"
+require "millionsend/webhooks"
+require "millionsend/api_keys"
+require "millionsend/templates"
+require "millionsend/usage"
+require "millionsend/deliverability"
 
 # Ruby client for the MillionSend HTTP API. Configure once, then call the
 # resource modules:
@@ -21,14 +29,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.4.0
 platform: ruby
 authors:
 - MillionSend
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -52,9 +52,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.19'
-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.'
+description: 'Ruby client for the MillionSend HTTP API: emails, batch, contacts, contact
+  properties, topics, broadcasts, segments, suppressions, domains, webhooks, API keys,
+  templates and usage. Wire-compatible with Resend and mirror-shaped after resend-ruby,
+  so migrating is mostly an import swap plus a base_url.'
 email:
 executables: []
 extensions: []
@@ -63,16 +64,24 @@ files:
 - LICENSE
 - README.md
 - lib/millionsend.rb
+- lib/millionsend/api_keys.rb
 - lib/millionsend/batch.rb
 - lib/millionsend/broadcasts.rb
+- lib/millionsend/contact_properties.rb
 - lib/millionsend/contacts.rb
+- lib/millionsend/deliverability.rb
+- lib/millionsend/domains.rb
 - lib/millionsend/emails.rb
 - lib/millionsend/error.rb
 - lib/millionsend/request.rb
 - lib/millionsend/segments.rb
+- lib/millionsend/suppressions.rb
+- lib/millionsend/templates.rb
 - lib/millionsend/topics.rb
+- lib/millionsend/usage.rb
 - lib/millionsend/util.rb
 - lib/millionsend/version.rb
+- lib/millionsend/webhooks.rb
 homepage: https://github.com/MillionSend/millionsend-ruby
 licenses:
 - MIT