millionsend 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7ba9ebe734ecd28255800fe99c06057c9eb51813801476000d730faf4a12791
-  data.tar.gz: 80b148cd3a5c73af573710ef4ceeb24f16e722f12b2ebe749661954916cbbf95
+  metadata.gz: da6448e6cf8b24c1c2badb8bb4c4d4904d873882ede341fefdbcb6949561753e
+  data.tar.gz: e68c0e3c988f18fee505aa780fbfc1974593da463f1aba01162eff0e50d4a0b4
 SHA512:
-  metadata.gz: 92f383b23f1c403b0cdb74d8325c7674e8e75ae82aa896cac1dded64a1eccc77e1e30d605096d3b186aa0c88c672c4cfd50ef947961c0dac98113d44acb701fc
-  data.tar.gz: 2274331c2c7bae47e1b7e8d574037367eb098d7b4876463966e61124c0a4f0ce5a4b9156bab3e88b1e0f50ab5f84ea415f37ba7e5d93fc5f2b1e969b538b8e77
+  metadata.gz: dc6a03a18b27ff92b46203c37df82eed46687420b14ac010e7b671ca6506f4f4c008e9177728c4640bb8aff3019f67fd7dbf23b9636a64a75b48cbfc658e2007
+  data.tar.gz: f5988d2662081f5bb34323cf482c10fc3762051b0b44e307a391cb867214d6dd6306664b052ed5f59e6ea5e2ef0e9187f6dba582c1c1b9c5ca4341ecdc076c4d

data/README.md

@@ -1,7 +1,182 @@
 # millionsend
 
-Official Ruby SDK for [MillionSend](https://github.com/MillionSend) — the open-source,
-self-hostable email platform.
+Official Ruby SDK for [MillionSend](https://github.com/MillionSend/millionsend) — a
+self-hostable, Resend-compatible email API on AWS SES.
 
-**Status: under active development.** This release reserves the gem name; the first working
-SDK will land here.
+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.
+
+## Install
+
+```bash
+gem install millionsend
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "millionsend"
+```
+
+Requires Ruby 3.0+. Only the standard library is used at runtime (`net/http`, `json`).
+
+## Quickstart
+
+```ruby
+require "millionsend"
+
+Millionsend.api_key  = "ms_123"
+Millionsend.base_url = "https://mail.acme.dev"
+
+email = Millionsend::Emails.send(
+  from: "Acme <onboarding@acme.dev>",
+  to: "delivered@resend.dev",
+  subject: "Hello from MillionSend",
+  html: "<strong>It works!</strong>"
+)
+
+puts email[:id]
+```
+
+Every call returns a symbol-keyed `Hash` on success and raises a `Millionsend::Error`
+on any non-2xx response (see [Error handling](#error-handling)).
+
+## Configuration
+
+```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
+```
+
+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`, `audience_id`).
+
+## 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
+```
+
+`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
+
+```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)
+
+# 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.
+
+### Topics
+
+```ruby
+Millionsend::Topics.create(name: "Product updates", default_subscription: "opt_in")
+Millionsend::Topics.get(id)
+Millionsend::Topics.list    # bare { data: [...] } — topics are unpaginated
+Millionsend::Topics.remove(id)
+```
+
+### Broadcasts
+
+```ruby
+broadcast = Millionsend::Broadcasts.create(
+  audience_id: audience[:id],
+  from: "Acme <news@acme.dev>",
+  subject: "Launch",
+  html: "<p>Hi {{{FIRST_NAME|there}}}</p>"
+)
+Millionsend::Broadcasts.list
+Millionsend::Broadcasts.get(broadcast[:id])
+Millionsend::Broadcasts.update(broadcast[:id], subject: "Launch 🚀") # draft only
+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
+```
+
+### Segments (MillionSend extension)
+
+Dynamic segments are a saved filter over an audience's contacts — a MillionSend superset with
+no Resend equivalent, served under `/segments2`.
+
+```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
+Millionsend::Segments.list
+Millionsend::Segments.update(segment[:id], name: "Pro tier")
+Millionsend::Segments.remove(segment[:id])
+```
+
+## Error handling
+
+No `{ data, error }` tuple — a non-2xx response raises. The base class is `Millionsend::Error`,
+which carries `#status_code`, `#name` (the stable snake_case discriminant), and `#message`.
+Subclasses are keyed on `name`, so you can rescue a specific failure:
+
+```ruby
+begin
+  Millionsend::Emails.get(id)
+rescue Millionsend::NotFoundError => e
+  warn "no such email: #{e.message}"
+rescue Millionsend::Error => e
+  warn "#{e.name} (#{e.status_code || 'transport'}): #{e.message}"
+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`.
+
+## Migrating from Resend
+
+```diff
+- require "resend"
+- Resend.api_key = "re_123"
+- 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::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).
+- `Millionsend::Segments` is the distinct dynamic-filter feature (`/segments2`), not Resend's
+  audiences alias. Use `Millionsend::Audiences` for a straight port.
+
+## License
+
+MIT

data/lib/millionsend/audiences.rb

@@ -0,0 +1,30 @@
+# 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

data/lib/millionsend/batch.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+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).
+      def send(list, options = {})
+        Millionsend::Request.new(
+          method: :post, path: "/emails/batch", body: list, idempotency_key: options[:idempotency_key]
+        ).perform
+      end
+      alias_method :create, :send
+    end
+  end
+end

data/lib/millionsend/broadcasts.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Broadcasts — one email sent to a whole audience or segment.
+  module Broadcasts
+    class << self
+      # POST /broadcasts
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/broadcasts", body: params).perform
+      end
+
+      # GET /broadcasts/:id
+      def get(id)
+        Millionsend::Request.new(method: :get, path: "/broadcasts/#{Millionsend::Util.encode(id)}").perform
+      end
+
+      # GET /broadcasts — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(
+          method: :get, path: "/broadcasts", query: Millionsend::Util.list_query(options)
+        ).perform
+      end
+
+      # PATCH /broadcasts/:id — draft only.
+      def update(id, params)
+        Millionsend::Request.new(method: :patch, path: "/broadcasts/#{Millionsend::Util.encode(id)}", body: params).perform
+      end
+
+      # DELETE /broadcasts/:id — draft only.
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: "/broadcasts/#{Millionsend::Util.encode(id)}").perform
+      end
+
+      # POST /broadcasts/:id/send — pass scheduled_at: to schedule, omit to send now.
+      def send(id, params = {})
+        Millionsend::Request.new(method: :post, path: "/broadcasts/#{Millionsend::Util.encode(id)}/send", body: params).perform
+      end
+
+      # POST /broadcasts/:id/cancel — scheduled only.
+      def cancel(id)
+        Millionsend::Request.new(method: :post, path: "/broadcasts/#{Millionsend::Util.encode(id)}/cancel").perform
+      end
+    end
+  end
+end

data/lib/millionsend/contacts.rb

@@ -0,0 +1,60 @@
+# 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).
+  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.
+      def create(params)
+        body = params.reject { |k, _| k == :audience_id }
+        Millionsend::Request.new(method: :post, path: collection_path(params[:audience_id]), body: body).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
+      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.
+      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
+      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
+      end
+
+      # GET a list of contacts; pass audience_id: to scope it, plus limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(
+          method: :get, path: collection_path(options[:audience_id]), 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
+      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}"
+      end
+    end
+  end
+end

data/lib/millionsend/emails.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Transactional email: send one, look it up, cancel a scheduled one.
+  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.
+      def send(params = {}, options = {})
+        Millionsend::Request.new(
+          method: :post, path: "/emails", body: params, idempotency_key: options[:idempotency_key]
+        ).perform
+      end
+      alias_method :create, :send
+
+      # GET /emails/:id
+      def get(id)
+        Millionsend::Request.new(method: :get, path: "/emails/#{Millionsend::Util.encode(id)}").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
+      end
+    end
+  end
+end

data/lib/millionsend/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Base class for everything this SDK raises. Mirrors the API's wire error body
+  # { statusCode, name, message }; #status_code is nil for client-side and
+  # transport failures that never reached the API.
+  class Error < StandardError
+    attr_reader :status_code, :name
+
+    def initialize(message, status_code = nil, name = nil)
+      super(message)
+      @status_code = status_code
+      @name = name
+    end
+
+    # Build the right subclass from a non-2xx response, keyed on the stable
+    # `name` discriminant. Falls back to ApplicationError for unknown names or a
+    # body that is not the canonical error shape.
+    def self.from_response(status, body)
+      if body.is_a?(Hash)
+        name = body[:name].is_a?(String) ? body[:name] : "application_error"
+        message = body[:message].is_a?(String) ? body[:message] : "Request failed with status #{status}"
+        code = body[:statusCode].is_a?(Integer) ? body[:statusCode] : status
+      else
+        name = "application_error"
+        message = "Request failed with status #{status}"
+        code = status
+      end
+      (ERROR_TYPES[name] || ApplicationError).new(message, code, name)
+    end
+  end
+
+  class ValidationError < Error; end
+  class NotFoundError < Error; end
+  class RestrictedApiKeyError < Error; end
+  class SendingPausedError < Error; end
+  class InvalidIdempotentRequestError < Error; end
+  class ApplicationError < Error; end
+
+  ERROR_TYPES = {
+    "validation_error" => ValidationError,
+    "not_found" => NotFoundError,
+    "restricted_api_key" => RestrictedApiKeyError,
+    "sending_paused" => SendingPausedError,
+    "invalid_idempotent_request" => InvalidIdempotentRequestError,
+    "application_error" => ApplicationError,
+  }.freeze
+end

data/lib/millionsend/request.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "timeout"
+require "openssl"
+
+module Millionsend
+  # Internal: builds and performs one HTTP call over net/http, then returns the
+  # parsed (symbol-keyed) body or raises a Millionsend::Error. The resource
+  # modules are thin wrappers over this.
+  class Request
+    VERBS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete,
+    }.freeze
+
+    # Transport-level failures that never produced an HTTP response -> the
+    # raised error carries status_code nil. Kept narrow so a mis-stubbed test
+    # (WebMock::NetConnectNotAllowedError) is not swallowed as a transport error.
+    TRANSPORT_ERRORS = [
+      Timeout::Error, SocketError, SystemCallError, IOError,
+      Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+    ].freeze
+
+    def initialize(method:, path:, body: nil, query: nil, idempotency_key: nil)
+      @method = method
+      @path = path
+      @body = body
+      @query = query
+      @idempotency_key = idempotency_key
+    end
+
+    def perform
+      api_key = Millionsend.api_key
+      if api_key.nil? || api_key.to_s.empty?
+        # Client-side failure: same class and stable name as a transport error,
+        # so rescue Millionsend::ApplicationError / branching on e.name works.
+        raise Millionsend::ApplicationError.new(
+          "Missing API key. Set Millionsend.api_key or the MILLIONSEND_API_KEY environment variable.",
+          nil, "application_error"
+        )
+      end
+
+      uri = build_uri
+      request = build_request(uri, api_key)
+
+      response =
+        begin
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+            http.request(request)
+          end
+        rescue *TRANSPORT_ERRORS => e
+          raise Millionsend::ApplicationError.new(e.message, nil, "application_error")
+        end
+
+      handle(response)
+    end
+
+    private
+
+    def build_uri
+      base = Millionsend.base_url.to_s.sub(%r{/+\z}, "")
+      uri = URI.parse("#{base}#{@path}")
+      query = (@query || {}).reject { |_, v| v.nil? }
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    def build_request(uri, api_key)
+      request = VERBS.fetch(@method).new(uri.request_uri)
+      request["Authorization"] = "Bearer #{api_key}"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = Millionsend::USER_AGENT
+      unless @body.nil?
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(@body)
+      end
+      # Idempotency is POST-only on the wire; ignored on other verbs.
+      request["Idempotency-Key"] = @idempotency_key if @idempotency_key && @method == :post
+      request
+    end
+
+    def handle(response)
+      status = response.code.to_i
+      body = parse(response.body)
+      raise Millionsend::Error.from_response(status, body) unless (200..299).cover?(status)
+
+      body
+    end
+
+    def parse(text)
+      return nil if text.nil? || text.empty?
+
+      JSON.parse(text, symbolize_names: true)
+    rescue JSON::ParserError
+      text
+    end
+  end
+end

data/lib/millionsend/segments.rb

@@ -0,0 +1,36 @@
+# 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.
+  module Segments
+    class << self
+      # POST /segments2
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/segments2", body: params).perform
+      end
+
+      # GET /segments2/:id — also returns a live contact_count.
+      def get(id)
+        Millionsend::Request.new(method: :get, path: "/segments2/#{Millionsend::Util.encode(id)}").perform
+      end
+
+      # GET /segments2 — accepts limit:/after:/before:.
+      def list(options = {})
+        Millionsend::Request.new(
+          method: :get, path: "/segments2", query: Millionsend::Util.list_query(options)
+        ).perform
+      end
+
+      # PATCH /segments2/:id
+      def update(id, params)
+        Millionsend::Request.new(method: :patch, path: "/segments2/#{Millionsend::Util.encode(id)}", body: params).perform
+      end
+
+      # DELETE /segments2/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: "/segments2/#{Millionsend::Util.encode(id)}").perform
+      end
+    end
+  end
+end

data/lib/millionsend/topics.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Millionsend
+  # Subscription topics — granular unsubscribe categories.
+  module Topics
+    class << self
+      # POST /topics
+      def create(params)
+        Millionsend::Request.new(method: :post, path: "/topics", body: params).perform
+      end
+
+      # GET /topics/:id
+      def get(id)
+        Millionsend::Request.new(method: :get, path: "/topics/#{Millionsend::Util.encode(id)}").perform
+      end
+
+      # GET /topics — a bare { data: [...] } (topics are unpaginated).
+      def list
+        Millionsend::Request.new(method: :get, path: "/topics").perform
+      end
+
+      # DELETE /topics/:id
+      def remove(id)
+        Millionsend::Request.new(method: :delete, path: "/topics/#{Millionsend::Util.encode(id)}").perform
+      end
+    end
+  end
+end

data/lib/millionsend/util.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Millionsend
+  # Small shared helpers used across the resource modules.
+  module Util
+    module_function
+
+    # Percent-encode a single URL path segment (contact ids and emails, which
+    # can contain "@" and "+"). encode_www_form_component is form encoding, so
+    # it maps space to "+" — wrong inside a path segment, where servers decode
+    # "+" literally. It already turned real plus signs into %2B, so every
+    # remaining "+" is a space and can safely become %20.
+    def encode(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    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
+  end
+end

data/lib/millionsend/version.rb

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

data/lib/millionsend.rb

@@ -1,6 +1,42 @@
-# MillionSend Ruby SDK — under active development.
-# This placeholder release reserves the gem name.
-# Follow https://github.com/MillionSend for the first working release.
-module MillionSend
-  VERSION = "0.0.1"
+# frozen_string_literal: true
+
+require "millionsend/version"
+require "millionsend/util"
+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"
+
+# Ruby client for the MillionSend HTTP API. Configure once, then call the
+# resource modules:
+#
+#   Millionsend.api_key  = "ms_..."
+#   Millionsend.base_url = "https://mail.acme.dev"
+#   Millionsend::Emails.send(from: "onboarding@acme.dev", to: "you@example.com",
+#                            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). 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
+
+    def api_key
+      @api_key || ENV["MILLIONSEND_API_KEY"]
+    end
+
+    def base_url
+      @base_url || ENV["MILLIONSEND_BASE_URL"] || DEFAULT_BASE_URL
+    end
+  end
 end

metadata

@@ -1,19 +1,62 @@
 --- !ruby/object:Gem::Specification
 name: millionsend
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - MillionSend
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
-dependencies: []
-description: Official Ruby SDK for MillionSend, the open-source, self-hostable email
-  platform. This placeholder release reserves the gem name; follow https://github.com/MillionSend
-  for the first working release.
-email: 
+date: 2026-08-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.'
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -21,12 +64,24 @@ 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/emails.rb
+- lib/millionsend/error.rb
+- lib/millionsend/request.rb
+- lib/millionsend/segments.rb
+- lib/millionsend/topics.rb
+- lib/millionsend/util.rb
+- lib/millionsend/version.rb
 homepage: https://github.com/MillionSend/millionsend-ruby
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/MillionSend/millionsend-ruby
-post_install_message: 
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -41,9 +96,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: Official Ruby SDK for MillionSend — the open-source email platform. Under
-  active development.
+summary: Official Ruby SDK for MillionSend — a self-hostable, Resend-compatible email
+  API.
 test_files: []