mailhive 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be565bac6c57f6bc2292b802192122794dfc98d9ac4060423b0ed51faa08510c
-  data.tar.gz: fb4e61ecfa08f93e3f553673947f3d930cb8f61ad632155cbb4fa2e3a5466746
+  metadata.gz: edcbe7300fa0125e510b97d0225cd3b04b134e3ffa31cb6b53c8964659600615
+  data.tar.gz: e7de31bd34f7cc7d0b2339bcdc63fdee039d02304c4b8d3554885aa159743f50
 SHA512:
-  metadata.gz: abe61a7f497e628a1031476ccb99d1dbc76df57054341f742cb7905f268fabba0a2590204c46e8b4819d806899b4f37138da482c743ed1a69e4f938cd0ac846b
-  data.tar.gz: 19171faa17039b7778eb150fc09938191a830cfb4c53dde81533265e9c945c3f81235f0d1c43131d405c8c0b416c2bd96400c9eae037cb49d2ddf0118ae8df81
+  metadata.gz: a971410f091c7727ba4e967457b781da96af928427ae27deed1e751ca58334d3c4dcd1d8fffdc412008d27be4378002fd5ff257c0eda1e40fbaafb5b1fe641c6
+  data.tar.gz: ce3e746f965c8ca30dba2eb2b7858279d78bba7d47c7e6d2a4951d2bf5ab9b686c20bcaa50054fc5768a9e65b397e9dd9f106d5aa5684b2432142710c892c61d

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.2.0 (2026-10-26)
+
+- Audiences and contacts, for API keys with Full access: `audiences.list`, `create` and `rename`; `contacts.list`, `add`, `upsert`, `upsert_batch`, `get`, `update`, `unsubscribe` and `delete`.
+- `double_opt_in` on a contact emails the person a confirmation link; they're subscribed only if they confirm. Someone who unsubscribed or reported spam can't be re-subscribed by these calls (a `Mailhive::ConflictError` with code `contact_unsubscribed`).
+- Requests can now carry query strings, and an empty response (`204`) is `nil` from `contacts.delete`.
+
+## 0.1.0 (2026-09-30)
 
 - `Mailhive::Client`, with `emails.send`, `emails.send_batch` and `emails.get`.
 - Idempotency keys reused across retries, and `Retry-After` honoured.

data/README.md

@@ -78,6 +78,25 @@ Outside Rails, use it with the [mail](https://github.com/mikel/mail) gem:
 mail.delivery_method Mailhive::ActionMailer::DeliveryMethod, api_key: "mhs_…"
 ```
 
+## Audiences and contacts
+
+With an API key that has **Full access**, keep an audience in step with your app or CRM:
+
+```ruby
+contact = client.contacts.upsert(audience_id, email: "ada@example.com", first_name: "Ada", fields: { plan: "pro" })
+```
+
+`upsert` adds the person, or updates them if they're already there, so it's safe to repeat. Other calls: `audiences.list`, `audiences.create`, `audiences.rename`, `contacts.list` (pass `email:` to find one person), `contacts.add`, `contacts.upsert_batch` (up to 100; check each result's `ok`), `contacts.get`, `contacts.update`, `contacts.unsubscribe` and `contacts.delete`.
+
+Someone who unsubscribed, or reported your email as spam, can't be subscribed again by your code: you get a `Mailhive::ConflictError` with code `contact_unsubscribed`. To bring them back, ask them to confirm:
+
+```ruby
+client.contacts.upsert(audience_id, email: "ada@example.com",
+                       double_opt_in: { from: "Acme News <news@yourcompany.com>", subject: "Confirm your subscription" })
+```
+
+They're `pending`, and never mailed by a broadcast, until they click the link. See the [contacts API reference](https://mailhive.africa/docs/api/contacts).
+
 ## Retries and idempotency
 
 Every send carries an `Idempotency-Key`. Retries reuse it, so **a retry never sends twice**.

data/lib/mailhive/audiences.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # client.audiences: the lists your broadcasts go to. Needs an API key with
+  # Full access.
+  class Audiences
+    def initialize(client)
+      @client = client
+    end
+
+    # The organization's audiences: [{id:, name:, contacts:, mailable:, …}].
+    def list
+      @client.request("GET", "/send/audiences")
+    end
+
+    def create(name, idempotency_key: nil)
+      @client.request("POST", "/send/audiences", { name: name }, idempotency_key: idempotency_key)
+    end
+
+    # Changes an audience's name. Returns {id:, name:}.
+    def rename(id, name)
+      @client.request("PATCH", "/send/audiences/#{Emails.escape(id)}", { name: name })
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end

data/lib/mailhive/client.rb

@@ -26,7 +26,7 @@ module Mailhive
     TIMEOUT_ERRORS = [Timeout::Error, Net::WriteTimeout, Errno::ETIMEDOUT].freeze
     private_constant :TIMEOUT_ERRORS
 
-    attr_reader :base_url, :timeout, :max_retries, :emails
+    attr_reader :base_url, :timeout, :max_retries, :emails, :audiences, :contacts
 
     # Options:
     # - api_key: a secret key (mhs_…); default MAILHIVE_API_KEY
@@ -52,6 +52,8 @@ module Mailhive
       @transport = transport || NetHTTPTransport.new
       @sleeper = sleeper || ->(seconds) { sleep(seconds) }
       @emails = Emails.new(self)
+      @audiences = Audiences.new(self)
+      @contacts = Contacts.new(self)
     end
 
     # Never shows the key.
@@ -61,7 +63,7 @@ module Mailhive
     alias to_s inspect
 
     # @api private Used by the resources.
-    def request(method, path, body = nil, idempotency_key: nil)
+    def request(method, path, body = nil, idempotency_key: nil, query: nil)
       headers = {
         "Authorization" => "Bearer #{@api_key}",
         "Accept" => "application/json",
@@ -74,7 +76,7 @@ module Mailhive
       end
       # One key per call, reused on every retry: a retry never sends twice.
       headers["Idempotency-Key"] = present(idempotency_key&.to_s) || SecureRandom.uuid if method == "POST"
-      url = "#{base_url}#{path}"
+      url = "#{base_url}#{path}#{query_string(query)}"
 
       attempt = 0
       loop do
@@ -112,6 +114,13 @@ module Mailhive
       value.nil? || value.empty? ? nil : value
     end
 
+    # "?email=a%2Bb%40example.com&page=2": percent-encoded, nil values left out.
+    def query_string(query)
+      pairs = (query || {}).reject { |_name, value| value.nil? }
+                           .map { |name, value| "#{name}=#{Emails.escape(value)}" }
+      pairs.empty? ? "" : "?#{pairs.join("&")}"
+    end
+
     def parse(body)
       body.nil? || body.strip.empty? ? {} : JSON.parse(body, symbolize_names: true)
     end

data/lib/mailhive/contacts.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # client.contacts: the people in an audience. Needs an API key with Full
+  # access. Keys match the API reference (symbols or strings): email,
+  # first_name, last_name, fields, status, double_opt_in.
+  #
+  # Someone who unsubscribed, or reported your email as spam, can't be made
+  # subscribed again by these calls (a Mailhive::ConflictError with code
+  # "contact_unsubscribed"). Pass double_opt_in: { from:, subject: } to email
+  # them a confirmation link instead: they're subscribed only if they click
+  # it, and until then they're "pending" and never mailed.
+  class Contacts
+    def initialize(client)
+      @client = client
+    end
+
+    # A page of contacts: {items:, page:, page_size:, total:}. Pass +email+ to
+    # find one person by exact address.
+    def list(audience_id, email: nil, q: nil, status: nil, page: nil, page_size: nil)
+      query = { email: email, q: q, status: status, page: page, page_size: page_size }
+      @client.request("GET", audience_path(audience_id), nil, query: query)
+    end
+
+    # Adds one person. A 409 "contact_exists" if they're already there: use #upsert.
+    #
+    #   client.contacts.add(audience_id, email: "ada@example.com", first_name: "Ada")
+    def add(audience_id, contact = nil, idempotency_key: nil, **fields)
+      @client.request("POST", audience_path(audience_id), self.class.encode((contact || {}).merge(fields)),
+                      idempotency_key: idempotency_key)
+    end
+
+    # Adds the person, or updates them if they're already there. Safe to repeat.
+    def upsert(audience_id, contact = nil, **fields)
+      @client.request("PUT", audience_path(audience_id), self.class.encode((contact || {}).merge(fields)))
+    end
+
+    # Adds or updates up to 100 people. A bad entry doesn't raise: check each
+    # result's +ok+. Returns {created:, updated:, failed:, results: […]}.
+    def upsert_batch(audience_id, contacts, idempotency_key: nil)
+      body = { contacts: contacts.map { |contact| self.class.encode(contact) } }
+      @client.request("POST", "#{audience_path(audience_id)}/batch", body, idempotency_key: idempotency_key)
+    end
+
+    # A contact and the latest emails sent to them (+history+).
+    def get(id)
+      @client.request("GET", contact_path(id))
+    end
+
+    # Edits names and fields (fields are replaced, not merged: use #upsert to
+    # merge), or unsubscribes with unsubscribe: true.
+    def update(id, changes = nil, **fields)
+      @client.request("PATCH", contact_path(id), self.class.encode((changes || {}).merge(fields)))
+    end
+
+    # Unsubscribes them. Only they can undo it, by confirming a double opt-in email.
+    def unsubscribe(id)
+      update(id, unsubscribe: true)
+    end
+
+    # Deleting someone who unsubscribed keeps their address suppressed. Returns nil.
+    def delete(id)
+      @client.request("DELETE", contact_path(id))
+      nil
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    # @api private The JSON body: string keys, with nil values left out (an
+    # empty string clears a name, and an empty Hash is sent as {}).
+    def self.encode(params)
+      raise ArgumentError, "A contact must be a Hash, got #{params.class}" unless params.respond_to?(:to_hash)
+
+      params.to_hash.each_with_object({}) do |(key, value), body|
+        body[key.to_s] = value.respond_to?(:to_hash) ? stringify(value.to_hash) : value unless value.nil?
+      end
+    end
+
+    # @api private
+    def self.stringify(hash)
+      hash.each_with_object({}) { |(key, value), out| out[key.to_s] = value.respond_to?(:to_hash) ? stringify(value.to_hash) : value }
+    end
+
+    private
+
+    def audience_path(id)
+      "/send/audiences/#{Emails.escape(id)}/contacts"
+    end
+
+    def contact_path(id)
+      "/send/contacts/#{Emails.escape(id)}"
+    end
+  end
+end

data/lib/mailhive/version.rb

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

data/lib/mailhive.rb

@@ -10,6 +10,8 @@ require_relative "mailhive/version"
 require_relative "mailhive/errors"
 require_relative "mailhive/transport"
 require_relative "mailhive/emails"
+require_relative "mailhive/audiences"
+require_relative "mailhive/contacts"
 require_relative "mailhive/client"
 require_relative "mailhive/webhook"
 require_relative "mailhive/action_mailer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailhive
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Naszat
@@ -21,7 +21,9 @@ files:
 - README.md
 - lib/mailhive.rb
 - lib/mailhive/action_mailer.rb
+- lib/mailhive/audiences.rb
 - lib/mailhive/client.rb
+- lib/mailhive/contacts.rb
 - lib/mailhive/emails.rb
 - lib/mailhive/errors.rb
 - lib/mailhive/railtie.rb