axene-mailer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 387abf842f6eb12070172e80dd6aaba7020b991931c5a0ab217232dc96599eb0
+  data.tar.gz: '09c6e130fe58403050eadf09bef07eab7984aa14e3552ed3278a24d4f51cde23'
+SHA512:
+  metadata.gz: c7d4d61ebe57213c75eaaf0a89341c61d7a743100fc59dc3bc515f035951ab1ec55ad13f1596ffd84cb9c6140510f69da150c168891d83839acc2cc0aea4c183
+  data.tar.gz: 7ba6727509a1fd7721c5fc6ac9866aa6cf2d8495848c8ecec22ff56e7ad21d89a29ee7b51b9e00779656a065f72d80b20e99ed0894a3f6f4852825a6cbbf24c4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axene Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# axene-mailer (Ruby)
+
+Ruby SDK for the [Axene Mailer](https://axene.io) API. Send email, manage
+domains, contacts, suppressions, templates, and webhooks. Zero runtime
+dependencies (standard library only). Ruby 3.0+.
+
+## Install
+
+```ruby
+# Gemfile
+gem "axene-mailer"
+```
+
+```sh
+bundle install
+# or
+gem install axene-mailer
+```
+
+## Quickstart
+
+```ruby
+require "axene/mailer"
+
+client = Axene::Mailer::Client.new(api_key: ENV.fetch("AXENE_API_KEY"))
+
+# Send a single email. A bare string is sugar for { email: ... }.
+result = client.emails.send(
+  from: "hello@yourdomain.com",
+  to: "customer@example.com",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>"
+)
+puts result[:id]
+```
+
+The client exposes six resources: `emails`, `domains`, `contacts`,
+`suppressions`, `templates`, and `webhooks`. Methods return parsed Ruby
+`Hash`/`Array` values with symbol keys.
+
+### Addresses
+
+Anywhere an address is accepted you may pass a plain string or a hash:
+
+```ruby
+client.emails.send(
+  from: { email: "hello@yourdomain.com", name: "Acme" },
+  to: ["a@example.com", { email: "b@example.com", name: "B" }],
+  subject: "Hi",
+  text: "Plain text body"
+)
+```
+
+### Batch and validation
+
+```ruby
+client.emails.send_batch([
+  { from: "hi@you.io", to: "a@example.com", subject: "1" },
+  { from: "hi@you.io", to: "b@example.com", subject: "2" }
+])
+
+check = client.emails.validate(from: "hi@you.io", to: "a@example.com", subject: "Test")
+puts check[:can_send]
+```
+
+### Contacts and CSV upload
+
+```ruby
+list = client.contacts.create_list(name: "Newsletter")
+
+# Upload accepts raw bytes or a file path.
+client.contacts.upload_csv(list[:id], "contacts.csv", filename: "contacts.csv")
+
+client.contacts.bulk_send(
+  list[:id],
+  sender_address_id: "sa_123",
+  subject: "Hello {{name}}",
+  html: "<p>Hi {{name}}</p>"
+)
+```
+
+### Suppressions, templates, webhooks
+
+```ruby
+client.suppressions.add(email: "bounce@example.com")
+page = client.suppressions.list(page: 0, limit: 50)  # envelope: items/total/page/limit
+
+client.templates.create(name: "Welcome", html: "<p>Hi</p>", text: "Hi")
+
+hook = client.webhooks.create(url: "https://you.io/hooks", events: ["email.delivered"])
+client.webhooks.update(hook[:id], is_active: false)
+```
+
+### Errors
+
+Non-2xx responses raise `Axene::Mailer::Error`:
+
+```ruby
+begin
+  client.emails.get("nope")
+rescue Axene::Mailer::Error => e
+  warn "#{e.status} #{e.code}: #{e.message}"
+end
+```
+
+A `status` of `0` indicates a transport failure (no HTTP response). Requests
+that fail with `429` or `5xx` are retried automatically with backoff, honoring
+the `Retry-After` header.
+
+### Configuration
+
+```ruby
+Axene::Mailer::Client.new(
+  api_key: "axm_k_...",
+  base_url: "https://mail.axene.io",  # default
+  max_retries: 3,                     # default
+  timeout: 30                         # seconds, default
+)
+```
+
+Pagination is zero-based (`page: 0` is the first page).
+
+## License
+
+MIT

data/lib/axene/mailer/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "resources/emails"
+require_relative "resources/domains"
+require_relative "resources/contacts"
+require_relative "resources/suppressions"
+require_relative "resources/templates"
+require_relative "resources/webhooks"
+
+module Axene
+  module Mailer
+    # Axene Mailer API client. Composes the HTTP transport with the resource
+    # groups. This is the entry point most code touches.
+    #
+    # @example
+    #   client = Axene::Mailer::Client.new(api_key: ENV.fetch("AXENE_API_KEY"))
+    #   client.emails.send(
+    #     from: "hello@yourdomain.com",
+    #     to: "customer@example.com",
+    #     subject: "Your receipt",
+    #     html: "<p>Thanks for your order.</p>"
+    #   )
+    class Client
+      # @return [Axene::Mailer::Resources::Emails] send, search, schedule, inspect emails
+      attr_reader :emails
+      # @return [Axene::Mailer::Resources::Domains] register, verify, transfer domains
+      attr_reader :domains
+      # @return [Axene::Mailer::Resources::Contacts] manage lists and bulk sends
+      attr_reader :contacts
+      # @return [Axene::Mailer::Resources::Suppressions] manage the do-not-send list
+      attr_reader :suppressions
+      # @return [Axene::Mailer::Resources::Templates] manage reusable templates
+      attr_reader :templates
+      # @return [Axene::Mailer::Resources::Webhooks] manage webhooks, inspect deliveries
+      attr_reader :webhooks
+
+      # @param api_key [String] required; starts with "axm_k_"
+      # @param base_url [String] default "https://mail.axene.io"
+      # @param max_retries [Integer] retries for 429/5xx, default 3
+      # @param timeout [Numeric] per-request timeout in seconds, default 30
+      def initialize(api_key:, base_url: Transport::DEFAULT_BASE_URL, max_retries: 3, timeout: 30)
+        transport = Transport.new(api_key: api_key, base_url: base_url, max_retries: max_retries, timeout: timeout)
+        @emails = Resources::Emails.new(transport)
+        @domains = Resources::Domains.new(transport)
+        @contacts = Resources::Contacts.new(transport)
+        @suppressions = Resources::Suppressions.new(transport)
+        @templates = Resources::Templates.new(transport)
+        @webhooks = Resources::Webhooks.new(transport)
+      end
+    end
+  end
+end

data/lib/axene/mailer/error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    # Raised for any non-2xx API response, or for a transport failure that
+    # survives all retries.
+    #
+    # Inspect {#status} and {#code} to branch on specific failures (for example
+    # a 422 with code "invalid"). A {#status} of 0 indicates a transport or
+    # network failure with no HTTP response.
+    class Error < StandardError
+      # @return [Integer] HTTP status code (0 for transport failures)
+      attr_reader :status
+
+      # @return [String, nil] machine-readable error code from the API body
+      attr_reader :code
+
+      # @return [Object, nil] the raw parsed response body, for debugging
+      attr_reader :detail
+
+      # @param status [Integer]
+      # @param message [String]
+      # @param code [String, nil]
+      # @param detail [Object, nil]
+      def initialize(status, message, code = nil, detail = nil)
+        super(message)
+        @status = status
+        @code = code
+        @detail = detail
+      end
+    end
+  end
+end

data/lib/axene/mailer/resources/contacts.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    module Resources
+      # The +contacts+ resource: manage subscriber lists, their contacts, CSV
+      # imports, and templated bulk sends. Accessed as +client.contacts+.
+      class Contacts
+        # @param transport [Axene::Mailer::Transport]
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # List all subscriber lists in the active workspace.
+        #
+        # @return [Array<Hash>]
+        def list_lists
+          @transport.request(:get, "/v1/contacts/")
+        end
+
+        # Create a subscriber list.
+        #
+        # @param name [String]
+        # @param description [String, nil]
+        # @param icon_seed [String, nil]
+        # @return [Hash]
+        def create_list(name:, description: nil, icon_seed: nil)
+          @transport.request(:post, "/v1/contacts/",
+                             body: Util.prune(name: name, description: description, icon_seed: icon_seed))
+        end
+
+        # Get a list with a page of its contacts (zero-based +page+).
+        #
+        # @param id [String]
+        # @param page [Integer] default 0
+        # @param limit [Integer] default 50
+        # @return [Hash]
+        def get_list(id, page: 0, limit: 50)
+          @transport.request(:get, "/v1/contacts/#{Util.escape(id)}", query: { page: page, limit: limit })
+        end
+
+        # Update a list's name, description, or icon (partial).
+        #
+        # @param id [String]
+        # @param name [String, nil]
+        # @param description [String, nil]
+        # @param icon_seed [String, nil]
+        # @return [Hash]
+        def update_list(id, name: nil, description: nil, icon_seed: nil)
+          @transport.request(:patch, "/v1/contacts/#{Util.escape(id)}",
+                             body: Util.prune(name: name, description: description, icon_seed: icon_seed))
+        end
+
+        # Delete a list and all of its contacts.
+        #
+        # @param id [String]
+        # @return [nil]
+        def delete_list(id)
+          @transport.request(:delete, "/v1/contacts/#{Util.escape(id)}")
+        end
+
+        # Add a single contact to a list.
+        #
+        # @param list_id [String]
+        # @param email [String]
+        # @param name [String, nil]
+        # @param metadata [Hash, nil]
+        # @return [Hash]
+        def add_contact(list_id, email:, name: nil, metadata: nil)
+          @transport.request(:post, "/v1/contacts/#{Util.escape(list_id)}/contacts",
+                             body: Util.prune(email: email, name: name, metadata: metadata))
+        end
+
+        # Remove a contact from a list.
+        #
+        # @param list_id [String]
+        # @param contact_id [String]
+        # @return [nil]
+        def remove_contact(list_id, contact_id)
+          @transport.request(:delete, "/v1/contacts/#{Util.escape(list_id)}/contacts/#{Util.escape(contact_id)}")
+        end
+
+        # Import contacts from a CSV file (header row required). The email column
+        # is auto-detected; other columns become contact metadata.
+        #
+        # +file+ may be raw bytes (a String) or a path to a readable file.
+        #
+        # @param list_id [String]
+        # @param file [String] raw CSV bytes or a file path
+        # @param filename [String]
+        # @return [Hash] { imported:, skipped:, errors: }
+        def upload_csv(list_id, file, filename: "contacts.csv")
+          bytes = read_file(file)
+          @transport.upload("/v1/contacts/#{Util.escape(list_id)}/upload", bytes, filename)
+        end
+
+        # Send a templated email to every contact in a list. The +contact_list_id+
+        # is injected automatically from +list_id+. Subject/html/text may use
+        # {{email}}, {{name}}, and {{metadata_key}} placeholders.
+        #
+        # @param list_id [String]
+        # @param sender_address_id [String]
+        # @param subject [String]
+        # @param html [String, nil]
+        # @param text [String, nil]
+        # @param tags [Array<String>, nil]
+        # @return [Hash] { queued:, skipped:, errors: }
+        def bulk_send(list_id, sender_address_id:, subject:, html: nil, text: nil, tags: nil)
+          body = Util.prune(
+            contact_list_id: list_id,
+            sender_address_id: sender_address_id,
+            subject: subject,
+            html: html,
+            text: text,
+            tags: tags
+          )
+          @transport.request(:post, "/v1/contacts/#{Util.escape(list_id)}/send", body: body)
+        end
+
+        private
+
+        # Accept either raw bytes or a filesystem path. A path is detected only
+        # when the string is short, single-line, and names an existing file.
+        def read_file(file)
+          if file.is_a?(String) && file.length < 4096 && !file.include?("\n") && File.file?(file)
+            File.binread(file)
+          else
+            file
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axene/mailer/resources/domains.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    module Resources
+      # The +domains+ resource: register, verify, inspect, and transfer sending
+      # domains. Accessed as +client.domains+.
+      class Domains
+        # @param transport [Axene::Mailer::Transport]
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # List your sending domains and their verification status.
+        #
+        # @return [Array<Hash>]
+        def list
+          @transport.request(:get, "/v1/domains/")
+        end
+
+        # Register a new sending domain. Returns the DNS records to publish.
+        #
+        # @param name [String]
+        # @return [Hash]
+        def create(name)
+          @transport.request(:post, "/v1/domains/", body: { name: name })
+        end
+
+        # Fetch a domain with its DKIM selector and DNS records.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def get(id)
+          @transport.request(:get, "/v1/domains/#{Util.escape(id)}")
+        end
+
+        # Delete a domain.
+        #
+        # @param id [String]
+        # @return [nil]
+        def delete(id)
+          @transport.request(:delete, "/v1/domains/#{Util.escape(id)}")
+        end
+
+        # Re-check DNS and verify the domain.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def verify(id)
+          @transport.request(:post, "/v1/domains/#{Util.escape(id)}/verify")
+        end
+
+        # Run live DNS health checks (DKIM, SPF, DMARC, return-path, MX).
+        #
+        # @param id [String]
+        # @return [Hash]
+        def health(id)
+          @transport.request(:get, "/v1/domains/#{Util.escape(id)}/health")
+        end
+
+        # Diagnose configuration issues and get a health score.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def diagnose(id)
+          @transport.request(:get, "/v1/domains/#{Util.escape(id)}/diagnose")
+        end
+
+        # Current MX status for inbound/forwarding (shape varies by provider).
+        #
+        # @param id [String]
+        # @return [Hash]
+        def mx_status(id)
+          @transport.request(:get, "/v1/domains/#{Util.escape(id)}/mx-status")
+        end
+
+        # The values currently published in DNS for each of the domain's records.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def published_records(id)
+          @transport.request(:get, "/v1/domains/#{Util.escape(id)}/published-records")
+        end
+
+        # Rotate the domain's DKIM key, returning the new record to publish.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def rotate_dkim(id)
+          @transport.request(:post, "/v1/domains/#{Util.escape(id)}/rotate-dkim")
+        end
+
+        # Initiate a transfer of this domain to another Axene account.
+        #
+        # @param id [String]
+        # @param target_email [String]
+        # @param note [String, nil]
+        # @return [Hash]
+        def transfer(id, target_email:, note: nil)
+          @transport.request(:post, "/v1/domains/#{Util.escape(id)}/transfer",
+                             body: { target_email: target_email, note: note })
+        end
+
+        # Check whether a domain name is available to add (checks public DNS).
+        #
+        # @param name [String]
+        # @return [Hash]
+        def check_availability(name)
+          @transport.request(:get, "/v1/domains/check-availability", query: { name: name })
+        end
+
+        # Check whether a domain name already exists in your account.
+        #
+        # @param name [String]
+        # @return [Hash]
+        def check(name)
+          @transport.request(:get, "/v1/domains/check/#{Util.escape(name)}")
+        end
+      end
+    end
+  end
+end

data/lib/axene/mailer/resources/emails.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    module Resources
+      # The +emails+ resource: send, look up, search, schedule, and inspect
+      # messages. Accessed as +client.emails+.
+      class Emails
+        # @param transport [Axene::Mailer::Transport]
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # Send a single email.
+        #
+        # Accepts keyword arguments or a Hash. The +from+ field is exposed
+        # cleanly and mapped to the wire name +from_+. A bare String is accepted
+        # anywhere an address is expected and becomes +{ email: ... }+.
+        #
+        # @param message [Hash] send parameters (:from, :to, :subject, :html, ...)
+        # @return [Hash] { id:, status:, message_id:, rejection_reason: }
+        def send(message = {}, **kwargs)
+          body = serialize_send(message.empty? ? kwargs : message)
+          @transport.request(:post, "/v1/emails/", body: body)
+        end
+
+        # Send up to your plan's batch limit in one call. The API accepts a bare
+        # array of messages and returns a per-message result set.
+        #
+        # @param messages [Array<Hash>]
+        # @return [Hash] { total:, sent:, failed:, results: [...] }
+        def send_batch(messages)
+          @transport.request(:post, "/v1/emails/batch", body: messages.map { |m| serialize_send(m) })
+        end
+
+        # Dry-run a send: check whether +message+ would be accepted without
+        # actually sending it. Uses the full send body.
+        #
+        # @param message [Hash]
+        # @return [Hash] { valid:, can_send:, issues:, plan:, usage: }
+        def validate(message = {}, **kwargs)
+          body = serialize_send(message.empty? ? kwargs : message)
+          @transport.request(:post, "/v1/emails/validate", body: body)
+        end
+
+        # List recent emails, newest first.
+        #
+        # @param status [String, nil]
+        # @param page [Integer] zero-based, default 0
+        # @param limit [Integer] default 20
+        # @return [Array<Hash>]
+        def list(status: nil, page: 0, limit: 20)
+          @transport.request(:get, "/v1/emails/", query: { status: status, page: page, limit: limit })
+        end
+
+        # Fetch a single email with its bodies and events.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def get(id)
+          @transport.request(:get, "/v1/emails/#{escape(id)}")
+        end
+
+        # List delivery / open / click / bounce events for an email.
+        #
+        # @param id [String]
+        # @return [Array<Hash>]
+        def events(id)
+          @transport.request(:get, "/v1/emails/#{escape(id)}/events")
+        end
+
+        # Re-send a bounced, rejected, or failed email as a new message.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def retry(id)
+          @transport.request(:post, "/v1/emails/#{escape(id)}/retry")
+        end
+
+        # Search emails. +q+ supports inline tokens (to:, from:, status:,
+        # domain:, tag:); leftover words are matched as free text.
+        #
+        # @param q [String, nil]
+        # @param status [String, nil]
+        # @param tag [String, nil]
+        # @param page [Integer] zero-based, default 0
+        # @param limit [Integer] default 20
+        # @return [Array<Hash>]
+        def search(q: nil, status: nil, tag: nil, page: 0, limit: 20)
+          @transport.request(:get, "/v1/emails/search",
+                             query: { q: q, status: status, tag: tag, page: page, limit: limit })
+        end
+
+        # List emails scheduled for future delivery, soonest first.
+        #
+        # @return [Array<Hash>]
+        def list_scheduled
+          @transport.request(:get, "/v1/emails/scheduled")
+        end
+
+        # Cancel a scheduled email.
+        #
+        # @param id [String]
+        # @return [Hash] { id:, status: }
+        def cancel_scheduled(id)
+          @transport.request(:delete, "/v1/emails/scheduled/#{escape(id)}")
+        end
+
+        # Send a scheduled email immediately instead of waiting.
+        #
+        # @param id [String]
+        # @return [Hash] { id:, status: }
+        def send_scheduled_now(id)
+          @transport.request(:post, "/v1/emails/scheduled/#{escape(id)}/send-now")
+        end
+
+        # Poll for emails whose status changed at or after +since+ (ISO 8601
+        # string or a Time). Capped at 50 rows.
+        #
+        # @param since [String, Time]
+        # @return [Array<Hash>]
+        def updates(since)
+          iso = since.respond_to?(:iso8601) ? since.iso8601 : since
+          @transport.request(:get, "/v1/emails/updates", query: { since: iso })
+        end
+
+        # Get the caller's saved searches.
+        #
+        # @return [Array<Hash>]
+        def get_saved_searches
+          @transport.request(:get, "/v1/emails/saved-searches")[:searches]
+        end
+
+        # Replace the caller's saved searches (max 50).
+        #
+        # @param searches [Array<Hash>]
+        # @return [Array<Hash>]
+        def set_saved_searches(searches)
+          @transport.request(:put, "/v1/emails/saved-searches", body: { searches: searches })[:searches]
+        end
+
+        private
+
+        def escape(value)
+          Util.escape(value)
+        end
+
+        # Build the JSON body for a send request. The API names the sender field
+        # +from_+ on the wire; this is the single place that mapping happens.
+        def serialize_send(params)
+          p = Util.symbolize(params)
+          send_at = p[:send_at] || p[:sendAt]
+          send_at = send_at.iso8601 if send_at.respond_to?(:iso8601)
+          reply_to = p[:reply_to] || p[:replyTo]
+          Util.prune(
+            from_: Util.address(p[:from]),
+            to: Util.address_list(p[:to]),
+            subject: p[:subject],
+            html: p[:html],
+            text: p[:text],
+            cc: Util.address_list(p[:cc]),
+            bcc: Util.address_list(p[:bcc]),
+            reply_to: reply_to.nil? ? nil : Util.address(reply_to),
+            headers: p[:headers],
+            tags: p[:tags],
+            send_at: send_at,
+            attachments: p[:attachments]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/axene/mailer/resources/suppressions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    module Resources
+      # The +suppressions+ resource: manage the do-not-send list. Accessed as
+      # +client.suppressions+.
+      class Suppressions
+        # @param transport [Axene::Mailer::Transport]
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # List suppressed addresses (paginated envelope; zero-based +page+).
+        #
+        # @param page [Integer] default 0
+        # @param limit [Integer] default 50
+        # @param search [String, nil]
+        # @return [Hash] { items:, total:, page:, limit: }
+        def list(page: 0, limit: 50, search: nil)
+          @transport.request(:get, "/v1/suppressions", query: { page: page, limit: limit, search: search })
+        end
+
+        # Suppress a single address. The +email+ argument maps to the wire field
+        # +email_address+.
+        #
+        # @param email [String]
+        # @param reason [String] default "manual"
+        # @return [Hash]
+        def add(email:, reason: "manual")
+          @transport.request(:post, "/v1/suppressions", body: { email_address: email, reason: reason })
+        end
+
+        # Bulk-import suppressions from a file (one email per line). +file+ may be
+        # raw bytes (a String) or a path to a readable file.
+        #
+        # @param file [String] raw bytes or a file path
+        # @param filename [String]
+        # @return [Hash] { added:, skipped:, total_processed: }
+        def bulk_upload(file, filename: "suppressions.txt")
+          bytes = read_file(file)
+          @transport.upload("/v1/suppressions/bulk", bytes, filename)
+        end
+
+        # Remove an address from the suppression list.
+        #
+        # @param id [String]
+        # @return [nil]
+        def remove(id)
+          @transport.request(:delete, "/v1/suppressions/#{Util.escape(id)}")
+        end
+
+        private
+
+        def read_file(file)
+          if file.is_a?(String) && file.length < 4096 && !file.include?("\n") && File.file?(file)
+            File.binread(file)
+          else
+            file
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axene/mailer/resources/templates.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    module Resources
+      # The +templates+ resource: reusable email templates (Starter plan and up).
+      # Accessed as +client.templates+.
+      #
+      # Note the wire mapping for this resource: +html+ maps to +html_body+ and
+      # +text+ maps to +text_body+ (the emails resource keeps +html+/+text+).
+      class Templates
+        # @param transport [Axene::Mailer::Transport]
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # List all templates, most recently updated first.
+        #
+        # @return [Array<Hash>]
+        def list
+          @transport.request(:get, "/v1/templates/")
+        end
+
+        # Create a template. +variables+ are derived server-side from {{name}}
+        # placeholders in the bodies, so you do not pass them.
+        #
+        # @param name [String]
+        # @param subject [String, nil]
+        # @param html [String, nil] maps to html_body
+        # @param text [String, nil] maps to text_body
+        # @param blocks_json [Hash, nil]
+        # @return [Hash]
+        def create(name:, subject: nil, html: nil, text: nil, blocks_json: nil)
+          @transport.request(:post, "/v1/templates/", body: serialize(name, subject, html, text, blocks_json))
+        end
+
+        # Fetch a single template.
+        #
+        # @param id [String]
+        # @return [Hash]
+        def get(id)
+          @transport.request(:get, "/v1/templates/#{Util.escape(id)}")
+        end
+
+        # Update a template (partial).
+        #
+        # @param id [String]
+        # @param name [String, nil]
+        # @param subject [String, nil]
+        # @param html [String, nil] maps to html_body
+        # @param text [String, nil] maps to text_body
+        # @param blocks_json [Hash, nil]
+        # @return [Hash]
+        def update(id, name: nil, subject: nil, html: nil, text: nil, blocks_json: nil)
+          @transport.request(:patch, "/v1/templates/#{Util.escape(id)}",
+                             body: serialize(name, subject, html, text, blocks_json))
+        end
+
+        # Delete a template.
+        #
+        # @param id [String]
+        # @return [nil]
+        def delete(id)
+          @transport.request(:delete, "/v1/templates/#{Util.escape(id)}")
+        end
+
+        # Duplicate a template (the copy's +blocks_json+ is not carried over).
+        #
+        # @param id [String]
+        # @return [Hash]
+        def duplicate(id)
+          @transport.request(:post, "/v1/templates/#{Util.escape(id)}/duplicate")
+        end
+
+        private
+
+        def serialize(name, subject, html, text, blocks_json)
+          Util.prune(
+            name: name,
+            subject: subject,
+            html_body: html,
+            text_body: text,
+            blocks_json: blocks_json
+          )
+        end
+      end
+    end
+  end
+end

data/lib/axene/mailer/resources/webhooks.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    module Resources
+      # The +webhooks+ resource: manage event subscriptions and inspect
+      # deliveries. Accessed as +client.webhooks+.
+      class Webhooks
+        # @param transport [Axene::Mailer::Transport]
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # List your active webhooks.
+        #
+        # @return [Array<Hash>]
+        def list
+          @transport.request(:get, "/v1/webhooks/")
+        end
+
+        # Create a webhook. The signing +secret+ is generated and returned.
+        #
+        # @param url [String]
+        # @param events [Array<String>]
+        # @return [Hash]
+        def create(url:, events:)
+          @transport.request(:post, "/v1/webhooks/", body: { url: url, events: events })
+        end
+
+        # Update a webhook's url, events, or active state (partial). The
+        # +is_active+ argument maps to the wire field +is_active+.
+        #
+        # @param id [String]
+        # @param url [String, nil]
+        # @param events [Array<String>, nil]
+        # @param is_active [Boolean, nil]
+        # @return [Hash]
+        def update(id, url: nil, events: nil, is_active: nil)
+          @transport.request(:patch, "/v1/webhooks/#{Util.escape(id)}",
+                             body: Util.prune(url: url, events: events, is_active: is_active))
+        end
+
+        # Delete a webhook.
+        #
+        # @param id [String]
+        # @return [nil]
+        def delete(id)
+          @transport.request(:delete, "/v1/webhooks/#{Util.escape(id)}")
+        end
+
+        # Queue a sample email.delivered delivery to test the endpoint.
+        #
+        # @param id [String]
+        # @return [Hash] { queued:, url: }
+        def test(id)
+          @transport.request(:post, "/v1/webhooks/#{Util.escape(id)}/test")
+        end
+
+        # List delivery attempts for a webhook (paginated envelope).
+        #
+        # @param id [String]
+        # @param page [Integer] default 0
+        # @param limit [Integer] default 20
+        # @param status [String, nil]
+        # @return [Hash] { items:, total:, page:, limit: }
+        def list_deliveries(id, page: 0, limit: 20, status: nil)
+          @transport.request(:get, "/v1/webhooks/#{Util.escape(id)}/deliveries",
+                             query: { page: page, limit: limit, status: status })
+        end
+
+        # Fetch one delivery with its full payload and the endpoint's response.
+        #
+        # @param id [String]
+        # @param delivery_id [String]
+        # @return [Hash]
+        def get_delivery(id, delivery_id)
+          @transport.request(:get, "/v1/webhooks/#{Util.escape(id)}/deliveries/#{Util.escape(delivery_id)}")
+        end
+      end
+    end
+  end
+end

data/lib/axene/mailer/transport.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "securerandom"
+require "uri"
+
+require_relative "error"
+
+module Axene
+  module Mailer
+    # HTTP transport: the single place that talks to the network. Owns bearer
+    # authentication, JSON encode/decode, timeouts, retries with backoff, and
+    # turning non-2xx responses into {Axene::Mailer::Error}. Resources depend on
+    # this, not on Net::HTTP directly.
+    class Transport
+      DEFAULT_BASE_URL = "https://mail.axene.io"
+      USER_AGENT = "axene-mailer-ruby/#{VERSION}"
+
+      # @param api_key [String] required; starts with "axm_k_"
+      # @param base_url [String] default "https://mail.axene.io"
+      # @param max_retries [Integer] retry attempts for 429/5xx, default 3
+      # @param timeout [Numeric] per-request timeout in seconds, default 30
+      def initialize(api_key:, base_url: DEFAULT_BASE_URL, max_retries: 3, timeout: 30)
+        raise ArgumentError, "Axene::Mailer: `api_key` is required." if api_key.nil? || api_key.empty?
+
+        @api_key = api_key
+        @base_url = base_url.sub(%r{/+\z}, "")
+        @max_retries = max_retries
+        @timeout = timeout
+      end
+
+      # Perform a JSON request and return the parsed body (symbolized keys).
+      #
+      # Retries 429 and 5xx with exponential backoff, honoring Retry-After when
+      # present. Raises {Axene::Mailer::Error} on a final non-2xx or a transport
+      # failure that survives every attempt.
+      #
+      # @param method [Symbol] :get, :post, :patch, :put, :delete
+      # @param path [String] path beginning with "/"
+      # @param body [Object, nil] request body, JSON-encoded when present
+      # @param query [Hash, nil] query parameters (nil values dropped)
+      # @return [Hash, Array, nil]
+      def request(method, path, body: nil, query: nil)
+        uri = build_uri(path, query)
+        last_error = nil
+
+        (1..@max_retries).each do |attempt|
+          req = build_request(method, uri)
+          unless body.nil?
+            req["Content-Type"] = "application/json"
+            req.body = JSON.generate(body)
+          end
+
+          begin
+            res = http(uri).request(req)
+          rescue StandardError => e
+            last_error = e
+            sleep(backoff_seconds(nil, attempt)) if attempt < @max_retries
+            next
+          end
+
+          status = res.code.to_i
+          if retryable?(status) && attempt < @max_retries
+            sleep(backoff_seconds(res, attempt))
+            next
+          end
+
+          payload = parse_body(res)
+          raise to_error(status, payload) unless status.between?(200, 299)
+
+          return payload
+        end
+
+        raise Error.new(0, "Axene::Mailer request failed: #{last_error}")
+      end
+
+      # Upload a single file as multipart/form-data under the field name "file".
+      # Used by the CSV/suppression import endpoints. Not retried (uploads are
+      # not idempotent).
+      #
+      # @param path [String]
+      # @param file_bytes [String] raw file contents
+      # @param filename [String]
+      # @return [Hash, Array, nil]
+      def upload(path, file_bytes, filename)
+        uri = build_uri(path, nil)
+        boundary = "AxeneBoundary#{SecureRandom.hex(16)}"
+        req = build_request(:post, uri)
+        req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        req.body = multipart_body(boundary, file_bytes, filename)
+
+        res = http(uri).request(req)
+        status = res.code.to_i
+        payload = parse_body(res)
+        raise to_error(status, payload) unless status.between?(200, 299)
+
+        payload
+      end
+
+      private
+
+      def build_uri(path, query)
+        uri = URI.parse("#{@base_url}#{path}")
+        if query && !query.empty?
+          pairs = query.reject { |_, v| v.nil? }.map { |k, v| [k.to_s, v.to_s] }
+          uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+        end
+        uri
+      end
+
+      def build_request(method, uri)
+        klass = {
+          get: Net::HTTP::Get,
+          post: Net::HTTP::Post,
+          patch: Net::HTTP::Patch,
+          put: Net::HTTP::Put,
+          delete: Net::HTTP::Delete
+        }.fetch(method)
+        req = klass.new(uri)
+        req["Authorization"] = "Bearer #{@api_key}"
+        req["Accept"] = "application/json"
+        req["User-Agent"] = USER_AGENT
+        req
+      end
+
+      def http(uri)
+        h = Net::HTTP.new(uri.host, uri.port)
+        h.use_ssl = uri.scheme == "https"
+        h.open_timeout = @timeout
+        h.read_timeout = @timeout
+        h
+      end
+
+      def multipart_body(boundary, file_bytes, filename)
+        safe_name = filename.to_s.gsub('"', "")
+        [
+          "--#{boundary}\r\n",
+          %(Content-Disposition: form-data; name="file"; filename="#{safe_name}"\r\n),
+          "Content-Type: application/octet-stream\r\n\r\n",
+          file_bytes.dup.force_encoding(Encoding::ASCII_8BIT),
+          "\r\n--#{boundary}--\r\n"
+        ].join
+      end
+
+      def retryable?(status)
+        status == 429 || status >= 500
+      end
+
+      def backoff_seconds(res, attempt)
+        if res
+          retry_after = res["retry-after"].to_f
+          return retry_after if retry_after.positive?
+        end
+        0.25 * (2**(attempt - 1))
+      end
+
+      def parse_body(res)
+        ctype = res["content-type"].to_s
+        return nil unless ctype.include?("application/json")
+
+        raw = res.body
+        return nil if raw.nil? || raw.empty?
+
+        JSON.parse(raw, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Map the API's { detail: { code, message } } (or a string detail) into an
+      # {Axene::Mailer::Error}.
+      def to_error(status, payload)
+        detail = payload.is_a?(Hash) ? payload[:detail] : nil
+        code = detail.is_a?(Hash) ? detail[:code] : nil
+        message =
+          if detail.is_a?(Hash)
+            detail[:message]
+          elsif detail.is_a?(String)
+            detail
+          end
+        message ||= "Axene::Mailer request failed (#{status})"
+        Error.new(status, message, code, payload)
+      end
+    end
+  end
+end

data/lib/axene/mailer/util.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Axene
+  module Mailer
+    # Internal helpers that translate the SDK's ergonomic inputs into the exact
+    # JSON shape the API expects. Not part of the public API.
+    module Util
+      module_function
+
+      # Drop keys whose value is nil so they are omitted from the JSON body.
+      #
+      # @param hash [Hash]
+      # @return [Hash]
+      def prune(hash)
+        hash.reject { |_, v| v.nil? }
+      end
+
+      # Normalize a single address. A bare String becomes { email: ... }.
+      #
+      # @param addr [String, Hash, nil]
+      # @return [Hash, nil]
+      def address(addr)
+        return nil if addr.nil?
+        return { email: addr } if addr.is_a?(String)
+
+        symbolize(addr)
+      end
+
+      # Normalize one-or-many addresses into an array, or nil if absent.
+      #
+      # @param addr [String, Hash, Array, nil]
+      # @return [Array<Hash>, nil]
+      def address_list(addr)
+        return nil if addr.nil?
+
+        list = addr.is_a?(Array) ? addr : [addr]
+        list.map { |a| address(a) }
+      end
+
+      # Shallow-symbolize the keys of a Hash so callers may pass either string
+      # or symbol keys.
+      #
+      # @param hash [Hash]
+      # @return [Hash]
+      def symbolize(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      # URL-escape a path segment.
+      #
+      # @param value [#to_s]
+      # @return [String]
+      def escape(value)
+        URI.encode_www_form_component(value.to_s)
+      end
+    end
+  end
+end

data/lib/axene/mailer/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Axene
+  module Mailer
+    # The gem version. Bumped on release; tags use the `ruby-v*` prefix.
+    VERSION = "0.1.0"
+  end
+end

data/lib/axene/mailer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "mailer/version"
+require_relative "mailer/error"
+require_relative "mailer/util"
+require_relative "mailer/transport"
+require_relative "mailer/client"
+
+# Axene Solutions namespace.
+module Axene
+  # Ruby SDK for the Axene Mailer API (https://mail.axene.io).
+  #
+  # @example
+  #   require "axene/mailer"
+  #   client = Axene::Mailer::Client.new(api_key: ENV.fetch("AXENE_API_KEY"))
+  #   client.emails.send(from: "hi@you.io", to: "x@example.com", subject: "Hi")
+  module Mailer
+  end
+end

data/lib/axene-mailer.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Convenience entry point matching the gem name `axene-mailer`.
+require_relative "axene/mailer"

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: axene-mailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Axene Solutions
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !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'
+description: Send email, manage domains, contacts, suppressions, templates, and webhooks
+  through the Axene Mailer API. Zero runtime dependencies.
+email:
+- engineering@axene.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/axene-mailer.rb
+- lib/axene/mailer.rb
+- lib/axene/mailer/client.rb
+- lib/axene/mailer/error.rb
+- lib/axene/mailer/resources/contacts.rb
+- lib/axene/mailer/resources/domains.rb
+- lib/axene/mailer/resources/emails.rb
+- lib/axene/mailer/resources/suppressions.rb
+- lib/axene/mailer/resources/templates.rb
+- lib/axene/mailer/resources/webhooks.rb
+- lib/axene/mailer/transport.rb
+- lib/axene/mailer/util.rb
+- lib/axene/mailer/version.rb
+homepage: https://axene.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://axene.io
+  source_code_uri: https://github.com/axene-io/axene-sdks
+  documentation_uri: https://docs.axene.io
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the Axene Mailer API.
+test_files: []