millionsend 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d6e46f436a0805ef763edac14bbd254e6f17503c598a8374b6abe9f45efcc76
-  data.tar.gz: 04c8ab67229c03c8769c7f9ef872b0e11b98d8aa8919a21c0d4c6ce6cc0582f9
+  metadata.gz: e916d31911bcbb75dc0c6aae5f671a2034a6aff4eac3f0b9be4e9eaa58b5c747
+  data.tar.gz: ba3d5063d02bd243660dfe04dee0780a84b2bad05cd11cd2c2690f3ffcfeca2a
 SHA512:
-  metadata.gz: ea4ff1283155e92f65aea2088a6ae4abdfd5032b3c93c243eb838a30ab141070c328bc7d2a278e0399894ec1e18300abef83a727ace9ed48a4b7e3271941e284
-  data.tar.gz: e845a9d24731c584b931a0de44fd7f0adee3760bcaa8d45d55412e301c6e9ad545cc1d62e294938e8adbdba07ebc204d156a96584d2d5b16fc721826853137dc
+  metadata.gz: 5c5d558bf5d08c705e8ae11ba6a6ed5e7cf6220a9629eb5a83bcc5570a713e669b5a7718b6d0f10b8bef00c5bf730d1e89599f6072948d76931cffe675b1d46c
+  data.tar.gz: 65edabd5b84e8f224045a7ebaab207f962221a75aab27ca32330435bee190a15834c45a06c7fcaeeeda1a77c46c305be4a314304d256968657d4c1886ad12ef3

data/README.md

@@ -121,8 +121,13 @@ contact = Millionsend::Contacts.create(
 )
 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.remove("ada@acme.dev")              # the contact's emails stay in the send log
+Millionsend::Contacts.remove("ada@acme.dev", erase: true) # ?erase=true — also scrubs the address from email
+                                                          # history, event payloads and API logs (GDPR/LGPD)
 Millionsend::Contacts.list(limit: 50)
+# Bulk read (MillionSend extension): carry the property map and the topic subscriptions on every
+# item, so an audience reads in one request per 100 contacts instead of one per contact
+Millionsend::Contacts.list(limit: 100, include: ["properties", "topics"]) # ?include=properties,topics
 
 # 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
@@ -149,8 +154,15 @@ result[:data]   # [{ index:, id:, status: "created" | "updated" | "skipped" }]
 result[:counts] # { created:, updated:, skipped:, failed: }
 result[:errors] # permissive mode only: [{ index:, message: }]
 
+# Bulk lookup (MillionSend extension) — up to 1000 contacts by id or email in one request, in
+# request order; unknown entries are listed, not errors — one request against the rate limit
+found = Millionsend::Contacts::Batch.get([contact[:id], "b@acme.dev", { email: "c@acme.dev" }], include: ["topics"])
+found[:data]    # [{ object: "contact", id:, email:, first_name:, last_name:, created_at:, unsubscribed:, topics: }]
+found[:missing] # [{ index:, email: }] / [{ index:, id: }] — request entries that matched nobody
+
 # 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: [...]
+Millionsend::Contacts::Batch.remove(emails: ["a@acme.dev", "b@acme.dev"]) # or ids: [...]; emails stay in the log
+Millionsend::Contacts::Batch.remove(ids: [contact[:id]], erase: true)      # also scrubs each address, as Contacts.remove
 # => { data: [{ object: "contact", contact: "<uuid>", deleted: true }, ...] } — only the rows actually deleted
 ```
 
@@ -307,6 +319,7 @@ 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.contacts(segment[:id], include: ["properties", "topics"]) # with each contact's extras, as Contacts.list
 Millionsend::Segments.update(segment[:id], name: "Pro tier")
 Millionsend::Segments.remove(segment[:id])
 ```

data/lib/millionsend/contacts.rb

@@ -24,16 +24,21 @@ module Millionsend
         Millionsend::Request.new(method: :patch, path: member_path(params), body: body).perform
       end
 
-      # DELETE a contact by id or email.
-      def remove(id_or_email)
-        Millionsend::Request.new(method: :delete, path: member_path(id_or_email)).perform
+      # DELETE a contact by id or email. The contact's emails stay in the send
+      # log; erase: true also scrubs the address from email history, event
+      # payloads and API logs (a GDPR/LGPD erasure). The flag rides flat or in
+      # resend-ruby's addressing hash: remove(email: "a@x.dev", erase: true).
+      def remove(id_or_email, options = {})
+        erase = options.key?(:erase) ? options[:erase] : (id_or_email[:erase] if id_or_email.is_a?(Hash))
+        Millionsend::Request.new(method: :delete, path: member_path(id_or_email), query: { erase: erase }).perform
       end
 
-      # GET /contacts — accepts limit:/after:/before:.
+      # GET /contacts — accepts limit:/after:/before: and include:
+      # (["properties", "topics"]) to carry the property map and the topic
+      # subscriptions on every item, as Contacts.get and Topics.list return them.
       def list(options = {})
-        Millionsend::Request.new(
-          method: :get, path: "/contacts", query: Millionsend::Util.list_query(options)
-        ).perform
+        query = Millionsend::Util.list_query(options).merge(include: Millionsend::Util.include_query(options[:include]))
+        Millionsend::Request.new(method: :get, path: "/contacts", query: query).perform
       end
 
       # PATCH /contacts/:id_or_email/topics with a bare array of
@@ -53,8 +58,20 @@ module Millionsend
       # 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)}"
+        "/contacts/#{Millionsend::Util.encode(unwrap(id_or_email))}"
+      end
+
+      # One /contacts/batch/get entry. The wire wants { id: } and { email: }
+      # told apart, and only an email carries "@".
+      def address(id_or_email)
+        value = unwrap(id_or_email)
+        value.to_s.include?("@") ? { email: value } : { id: value }
+      end
+
+      private
+
+      def unwrap(id_or_email)
+        id_or_email.is_a?(Hash) ? id_or_email[:email] || id_or_email[:id] || id_or_email[:contact_id] : id_or_email
       end
     end
 
@@ -96,8 +113,21 @@ module Millionsend
           ).perform
         end
 
+        # POST /contacts/batch/get — up to 1000 contacts by id or email (bare
+        # values or addressing hashes, like Contacts.get) in one request, one
+        # call against the rate limit. Returns { data: [...] } in request order
+        # plus missing: [{ index:, id: | email: }] for the entries that matched
+        # nobody — those never fail the call. include: ["properties", "topics"]
+        # attaches the same extras as Contacts.list.
+        def get(addresses, options = {})
+          body = { contacts: addresses.map { |a| Millionsend::Contacts.address(a) }, include: options[:include] }
+          Millionsend::Request.new(method: :post, path: "/contacts/batch/get", body: body.compact).perform
+        end
+
         # POST /contacts/batch/remove — { ids: [...] } or { emails: [...] }
-        # (exactly one, up to 1000). Returns { data: [{ object:, contact:,
+        # (exactly one, up to 1000), plus erase: true to also scrub each
+        # address from email history, event payloads and API logs, as
+        # Contacts.remove does. Returns { data: [{ object:, contact:,
         # deleted: true }] } listing only the rows actually deleted; unknown
         # ids or addresses are skipped.
         def remove(params)

data/lib/millionsend/segments.rb

@@ -23,11 +23,12 @@ module Millionsend
       end
 
       # GET /segments/:id/contacts — the contacts currently matching, paginated
-      # with limit:/after:/before:.
+      # with limit:/after:/before:; include: (["properties", "topics"]) as on
+      # Contacts.list.
       def contacts(id, options = {})
+        query = Millionsend::Util.list_query(options).merge(include: Millionsend::Util.include_query(options[:include]))
         Millionsend::Request.new(
-          method: :get, path: "/segments/#{Millionsend::Util.encode(id)}/contacts",
-          query: Millionsend::Util.list_query(options)
+          method: :get, path: "/segments/#{Millionsend::Util.encode(id)}/contacts", query: query
         ).perform
       end
 

data/lib/millionsend/util.rb

@@ -33,6 +33,13 @@ module Millionsend
       { limit: options[:limit], after: options[:after], before: options[:before] }
     end
 
+    # ?include= for the contact lists: the names comma-joined, or nil (dropped
+    # from the query) when none were given.
+    def include_query(include)
+      names = Array(include)
+      names.empty? ? nil : names.join(",")
+    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

data/lib/millionsend/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: millionsend
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - MillionSend
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake