millionsend 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f44b4a952ce5037c565e1ba8071a29ddf7d2b7d875fd99cad7719e91155d3054
-  data.tar.gz: a6b58d948cd026fe50ff598cc46129d6e9c164de71453dcdd77855237c0376fd
+  metadata.gz: 0d6e46f436a0805ef763edac14bbd254e6f17503c598a8374b6abe9f45efcc76
+  data.tar.gz: 04c8ab67229c03c8769c7f9ef872b0e11b98d8aa8919a21c0d4c6ce6cc0582f9
 SHA512:
-  metadata.gz: 4c16c5f8ee728136b872cc3f6a83d78052c62649c7b69497973d72845fb318669073078eb54406863fb0d83cd5336868896e098da794677b50667eefb4f0ec7f
-  data.tar.gz: d492c8d93ddcfff8e5f887f50aa7200fa0e30856effd041530a19a62cd2c2ad07ed47520c9f5fb57a32e4078103d6edad6619cb45cbba888cb94e0f01ff0faf8
+  metadata.gz: ea4ff1283155e92f65aea2088a6ae4abdfd5032b3c93c243eb838a30ab141070c328bc7d2a278e0399894ec1e18300abef83a727ace9ed48a4b7e3271941e284
+  data.tar.gz: e845a9d24731c584b931a0de44fd7f0adee3760bcaa8d45d55412e301c6e9ad545cc1d62e294938e8adbdba07ebc204d156a96584d2d5b16fc721826853137dc

data/README.md

@@ -5,7 +5,7 @@ self-hostable, Resend-compatible email API on AWS SES.
 
 The API is wire-compatible with Resend, and this gem deliberately mirrors the shape of
 [`resend`](https://github.com/resend/resend-ruby), so migrating is mostly a find-and-replace:
-swap the constant, set `base_url` to your instance.
+swap the constant (and, on a self-hosted instance, set `base_url`).
 
 ## Install
 
@@ -26,8 +26,8 @@ Requires Ruby 3.0+. Only the standard library is used at runtime (`net/http`, `j
 ```ruby
 require "millionsend"
 
-Millionsend.api_key  = "ms_123"
-Millionsend.base_url = "https://mail.acme.dev"
+Millionsend.api_key = "ms_123"
+# Millionsend.base_url = "https://mail.acme.dev" # self-hosted only; defaults to MillionSend Cloud
 
 email = Millionsend::Emails.send(
   from: "Acme <onboarding@acme.dev>",
@@ -47,12 +47,12 @@ on any non-2xx response (see [Error handling](#error-handling)).
 ```ruby
 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
+                                               # then https://api.millionsend.com (Cloud)
 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.
+MillionSend Cloud works with just the API key; a self-hosted instance sets `base_url` to
+its origin. 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
@@ -127,6 +127,13 @@ Millionsend::Contacts.list(limit: 50)
 # 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
+Millionsend::Contacts::Topics.list(email: "ada@acme.dev") # GET /contacts/:id/topics — every topic with its effective
+                                                          # subscription (explicit: false when it is the topic's default)
+                                                          # and its visibility ("public" | "private")
+
+# Preference-center link (MillionSend extension) — POST /contacts/:id/preferences-link
+link = Millionsend::Contacts.preferences_link("ada@acme.dev") # by id or email; also preferences_link(id: ...) / (email: ...)
+link[:url] # the contact's hosted preference page; no expiry, so show it only to that contact
 
 # Segment membership — POST / DELETE /contacts/:id/segments/:segment_id
 Millionsend::Contacts::Segments.add("ada@acme.dev", segment_id)
@@ -141,6 +148,10 @@ result = Millionsend::Contacts::Batch.create(
 result[:data]   # [{ index:, id:, status: "created" | "updated" | "skipped" }]
 result[:counts] # { created:, updated:, skipped:, failed: }
 result[:errors] # permissive mode only: [{ index:, message: }]
+
+# Bulk delete (MillionSend extension) — up to 1000 per call, exactly one of ids: / emails:
+Millionsend::Contacts::Batch.remove(emails: ["a@acme.dev", "b@acme.dev"]) # or ids: [...]
+# => { data: [{ object: "contact", contact: "<uuid>", deleted: true }, ...] } — only the rows actually deleted
 ```
 
 Contacts are addressable by id or email; when an `update` hash carries both, the email wins.
@@ -235,15 +246,27 @@ hook = Millionsend::Webhooks.create(
   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.get(hook[:id]) # also returns signing_secret and previous_secret_expires_at
 Millionsend::Webhooks.list
 Millionsend::Webhooks.update(hook[:id], events: ["email.opened"], status: "disabled")
 Millionsend::Webhooks.remove(hook[:id])
+
+# Rotate the signing secret (MillionSend extension) — POST /webhooks/:id/rotate
+rotated = Millionsend::Webhooks.rotate(hook[:id])                                         # mints a new secret, 24h overlap
+rotated = Millionsend::Webhooks.rotate(hook[:id], signing_secret: "whsec_...", overlap_hours: 0) # bring your own, no overlap
+rotated[:signing_secret]              # the secret now signing deliveries
+rotated[:previous_secret_expires_at]  # ISO time until which the old secret also signs, or nil
 ```
 
+During the overlap window (`overlap_hours`, 0–72, default 24) every delivery carries both
+signatures, so a receiver holding either verifies; `Webhooks.get` reports the window's end
+as `previous_secret_expires_at` (`nil` when none is open).
+
 Events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`,
-`email.complained`, `email.opened`, `email.clicked`, `deliverability.warning`,
-`deliverability.paused`, `quota.warning`, `quota.reached`.
+`email.complained`, `email.opened`, `email.clicked`, `contact.created`, `contact.updated`,
+`contact.deleted`, `contact.unsubscribed`, `contact.resubscribed`, `contact.topic_opt_in`,
+`contact.topic_opt_out`, `suppression.added`, `suppression.removed`, `deliverability.warning`,
+`deliverability.paused`, `quota.warning`, `quota.reached`, `quota.paused`.
 
 ### API keys
 
@@ -326,12 +349,16 @@ rescue Millionsend::Error => e
 end
 ```
 
-Subclasses: `ValidationError`, `NotFoundError`, `MissingApiKeyError`, `InvalidApiKeyError`,
-`RestrictedApiKeyError`, `SendingPausedError`, `BroadcastsPausedError`, `RateLimitExceededError`,
-`DailyQuotaExceededError`, `InvalidIdempotentRequestError`, `ConcurrentIdempotentRequestsError`,
-`InternalServerError`, and `ApplicationError` (the fallback for unknown names). Client-side and
+Subclasses: `ValidationError`, `AllRecipientsSuppressedError`, `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`.
 
+`Emails.send` and `Batch.send` raise `AllRecipientsSuppressedError` (`all_recipients_suppressed`,
+422) when every `to` recipient is on the suppression list or opted out of the send's `topic_id`.
+
 ## Migrating from Resend
 
 ```diff
@@ -340,7 +367,7 @@ transport failures that never reached the API raise `ApplicationError` with `#st
 - Resend::Emails.send(from: "...", to: "...", subject: "Hi", html: "<p>hi</p>")
 + require "millionsend"
 + Millionsend.api_key  = "ms_123"
-+ Millionsend.base_url = "https://mail.acme.dev"
++ Millionsend.base_url = "https://mail.acme.dev" # self-hosted only
 + Millionsend::Emails.send(from: "...", to: "...", subject: "Hi", html: "<p>hi</p>")
 ```
 
@@ -354,6 +381,7 @@ works as in resend-ruby. Notes:
   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.
+  `Contacts::Topics.list` is unpaginated, so resend-ruby's `limit:`/`after:`/`before:` are not sent.
   `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. The API's `/audiences/*` routes are a compatibility shim and are not
@@ -361,8 +389,9 @@ works as in resend-ruby. Notes:
   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"`.
+- MillionSend extensions with no Resend counterpart: `Segments`, `Contacts::Batch`,
+  `Contacts.preferences_link`, `Webhooks.rotate`, `Usage`, `Deliverability`,
+  `Emails.get_insights`, `Suppressions` `origin: "unsubscribe"`.
 
 ## License
 

data/lib/millionsend/contacts.rb

@@ -42,6 +42,14 @@ module Millionsend
         Millionsend::Request.new(method: :patch, path: "#{member_path(id_or_email)}/topics", body: topics).perform
       end
 
+      # POST /contacts/:id_or_email/preferences-link — the contact's hosted
+      # preference page, { object: "preferences_link", contact:, url: }. The
+      # url is a contact-scoped capability with no expiry: hand it only to that
+      # contact. 422 when the instance cannot build hosted links.
+      def preferences_link(id_or_email)
+        Millionsend::Request.new(method: :post, path: "#{member_path(id_or_email)}/preferences-link").perform
+      end
+
       # 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)
@@ -53,6 +61,15 @@ module Millionsend
     # Topic subscriptions of one contact, in resend-ruby's nested shape.
     module Topics
       class << self
+        # GET /contacts/:id_or_email/topics — { id: | email: } or a bare id/email.
+        # Every topic comes back with the contact's effective subscription
+        # (explicit: false means it is the topic's default, not a stored
+        # choice) and its visibility ("public" | "private"). Unpaginated, like
+        # Topics.list.
+        def list(params)
+          Millionsend::Request.new(method: :get, path: "#{Millionsend::Contacts.member_path(params)}/topics").perform
+        end
+
         # PATCH /contacts/:id_or_email/topics — { id: | email:, topics: [{ id:, subscription: }] }.
         def update(params)
           Millionsend::Contacts.topics_update(params, params[:topics])
@@ -60,7 +77,8 @@ module Millionsend
       end
     end
 
-    # Bulk contact creation — a MillionSend extension (Resend imports via CSV).
+    # Bulk contact creation and deletion — MillionSend extensions (Resend
+    # imports via CSV and deletes one at a time).
     module Batch
       class << self
         # POST /contacts/batch with a bare array of up to 1000 create payloads.
@@ -77,6 +95,14 @@ module Millionsend
             **Millionsend::Util.request_options(options)
           ).perform
         end
+
+        # POST /contacts/batch/remove — { ids: [...] } or { emails: [...] }
+        # (exactly one, up to 1000). Returns { data: [{ object:, contact:,
+        # deleted: true }] } listing only the rows actually deleted; unknown
+        # ids or addresses are skipped.
+        def remove(params)
+          Millionsend::Request.new(method: :post, path: "/contacts/batch/remove", body: params).perform
+        end
       end
     end
 

data/lib/millionsend/error.rb

@@ -31,6 +31,7 @@ module Millionsend
   end
 
   class ValidationError < Error; end
+  class AllRecipientsSuppressedError < Error; end
   class NotFoundError < Error; end
   class MissingApiKeyError < Error; end
   class InvalidApiKeyError < Error; end
@@ -46,6 +47,7 @@ module Millionsend
 
   ERROR_TYPES = {
     "validation_error" => ValidationError,
+    "all_recipients_suppressed" => AllRecipientsSuppressedError,
     "not_found" => NotFoundError,
     "missing_api_key" => MissingApiKeyError,
     "invalid_api_key" => InvalidApiKeyError,

data/lib/millionsend/version.rb

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

data/lib/millionsend/webhooks.rb

@@ -10,7 +10,8 @@ module Millionsend
         Millionsend::Request.new(method: :post, path: "/webhooks", body: params).perform
       end
 
-      # GET /webhooks/:id — includes signing_secret.
+      # GET /webhooks/:id — includes signing_secret and
+      # previous_secret_expires_at (nil unless a rotation's overlap window is open).
       def get(id)
         Millionsend::Request.new(method: :get, path: member_path(id)).perform
       end
@@ -30,6 +31,14 @@ module Millionsend
         Millionsend::Request.new(method: :delete, path: member_path(id)).perform
       end
 
+      # POST /webhooks/:id/rotate — signing_secret (optional whsec_ value to
+      # bring your own; omitted mints one) and overlap_hours (0..72, default
+      # 24) during which deliveries carry both signatures. Returns { object:,
+      # id:, signing_secret:, previous_secret_expires_at: }.
+      def rotate(id, params = {})
+        Millionsend::Request.new(method: :post, path: "#{member_path(id)}/rotate", body: params).perform
+      end
+
       private
 
       def member_path(id)

data/lib/millionsend.rb

@@ -28,13 +28,13 @@ require "millionsend/deliverability"
 #                            subject: "Hi", html: "<strong>it works</strong>")
 #
 # 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). Plain http is only accepted for
+# MILLIONSEND_BASE_URL and then MillionSend Cloud, so a self-hosted instance
+# sets its own origin. 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"
+  DEFAULT_BASE_URL = "https://api.millionsend.com"
   USER_AGENT = "millionsend-ruby/#{VERSION}"
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: millionsend
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - MillionSend
@@ -55,7 +55,7 @@ dependencies:
 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.'
+  so migrating is mostly an import swap.'
 email:
 executables: []
 extensions: []