agdirlabs-email 0.1.0

data/lib/agdirlabs/email/models.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # Immutable response objects. All are frozen, keyword-initialized Structs
+    # (`Data` needs Ruby 3.2; this gem supports 3.1), so they support `==`, `to_h`
+    # and pattern matching (`in {status: "delivered"}`).
+    module Model
+      # Defines a frozen keyword Struct.
+      # @api private
+      def self.define(*fields, &block)
+        Struct.new(*fields, keyword_init: true) do
+          define_method(:initialize) do |**attributes|
+            super(**attributes)
+            freeze
+          end
+          class_eval(&block) if block
+        end
+      end
+    end
+
+    # Result of {Resources::Emails#send}.
+    # @!attribute [r] id
+    #   @return [String]
+    SendResult = Model.define(:id)
+
+    # Result of {Resources::Emails#send_batch}.
+    # @!attribute [r] data
+    #   @return [Array<SendResult>] accepted emails, in input order
+    # @!attribute [r] errors
+    #   @return [Array<BatchError>] only with `validation: :permissive`: emails that were not accepted
+    BatchResult = Model.define(:data, :errors)
+
+    # An email rejected by a permissive batch.
+    # @!attribute [r] index
+    #   @return [Integer] position in the input array
+    # @!attribute [r] message
+    #   @return [String]
+    BatchError = Model.define(:index, :message)
+
+    # Result of operations that only echo the object's id (cancel, verify, update, replay, delete).
+    # @!attribute [r] id
+    #   @return [String]
+    # @!attribute [r] deleted
+    #   @return [Boolean] true for delete operations
+    Result = Model.define(:id, :deleted) do
+      def deleted? = deleted == true
+    end
+
+    # An email and its delivery status, from {Resources::Emails#get}.
+    # @!attribute [r] status
+    #   @return [String] most advanced state so far: queued, scheduled, sent, delivery_delayed,
+    #     delivered, opened, clicked, bounced, failed, complained or canceled
+    # @!attribute [r] created_at
+    #   @return [Time]
+    # @!attribute [r] scheduled_at
+    #   @return [Time, nil]
+    EmailDetails = Model.define(:id, :from, :to, :cc, :bcc, :reply_to, :subject, :html, :text,
+                                :created_at, :scheduled_at, :status)
+
+    # A DNS record to publish for a domain.
+    # @!attribute [r] purpose
+    #   @return [String] what the record is for: DKIM, SPF or DMARC
+    # @!attribute [r] name
+    #   @return [String] relative to the registrable domain, e.g. `agdir._domainkey` or `send`
+    # @!attribute [r] type
+    #   @return [String] TXT, MX or CNAME
+    # @!attribute [r] priority
+    #   @return [Integer, nil] MX records only
+    DnsRecord = Model.define(:purpose, :name, :type, :value, :ttl, :priority, :status)
+
+    # A sending domain.
+    # @!attribute [r] status
+    #   @return [String] not_started, pending, verified, failed or temporary_failure
+    # @!attribute [r] records
+    #   @return [Array<DnsRecord>, nil] DNS records; nil on items of {Resources::Domains#list}
+    Domain = Model.define(:id, :name, :status, :region, :created_at, :open_tracking, :click_tracking, :records) do
+      def verified? = status == "verified"
+    end
+
+    # A webhook endpoint.
+    # @!attribute [r] status
+    #   @return [String] enabled or disabled
+    # @!attribute [r] events
+    #   @return [Array<String>] subscribed event types, e.g. `email.delivered`
+    # @!attribute [r] signing_secret
+    #   @return [String, nil] `whsec_…`; only from {Resources::Webhooks#get}
+    WebhookEndpoint = Model.define(:id, :endpoint, :status, :events, :created_at, :signing_secret) do
+      def enabled? = status == "enabled"
+    end
+
+    # A webhook id with its (new) signing secret, from webhook create and rotate.
+    WebhookSecret = Model.define(:id, :signing_secret)
+
+    # A message sent (or queued) to a webhook endpoint.
+    # @!attribute [r] status
+    #   @return [String] pending, attempting, success or failed
+    # @!attribute [r] next_attempt_at
+    #   @return [Time, nil] only from {Resources::WebhookDeliveries#get}
+    # @!attribute [r] payload
+    #   @return [Hash, nil] the exact JSON body sent; only from {Resources::WebhookDeliveries#get}
+    WebhookDelivery = Model.define(:id, :type, :status, :created_at, :next_attempt_at, :payload)
+
+    # One HTTP attempt of a webhook delivery.
+    # @!attribute [r] http_status
+    #   @return [Integer] 0 when no HTTP response was received
+    WebhookAttempt = Model.define(:id, :http_status, :response, :sent_at)
+
+    # An event received on your webhook endpoint, returned by {Webhook.verify}.
+    # @!attribute [r] type
+    #   @return [String] e.g. `email.delivered`
+    # @!attribute [r] data
+    #   @return [WebhookEventData]
+    WebhookEvent = Model.define(:type, :created_at, :data)
+
+    # The email an event is about.
+    # @!attribute [r] tags
+    #   @return [Hash{String => String}]
+    # @!attribute [r] bounce
+    #   @return [Bounce, nil] `email.bounced` only
+    # @!attribute [r] click
+    #   @return [Click, nil] `email.clicked` only
+    # @!attribute [r] failed
+    #   @return [Failure, nil] `email.failed` only
+    WebhookEventData = Model.define(:email_id, :message_id, :from, :to, :subject, :tags, :created_at,
+                                    :bounce, :click, :failed)
+
+    # Bounce details of an `email.bounced` event.
+    Bounce = Model.define(:type, :sub_type, :message)
+    # Click details of an `email.clicked` event.
+    Click = Model.define(:link, :ip_address, :user_agent, :timestamp)
+    # Failure details of an `email.failed` event.
+    Failure = Model.define(:reason)
+
+    # One page of a list endpoint. Enumerable over {#data}.
+    # @!attribute [r] data
+    #   @return [Array]
+    # @!attribute [r] has_more
+    #   @return [Boolean]
+    # @!attribute [r] next_cursor
+    #   @return [String, nil] pass as `after:` to fetch the next page; nil on the last page
+    class Page
+      include Enumerable
+
+      attr_reader :data, :has_more, :next_cursor
+
+      def initialize(data:, has_more:, next_cursor:)
+        @data = data.freeze
+        @has_more = has_more
+        @next_cursor = next_cursor
+        freeze
+      end
+
+      def has_more? = has_more
+      def each(&) = data.each(&)
+      def size = data.size
+      alias length size
+      def empty? = data.empty?
+      def to_h = { data: data, has_more: has_more, next_cursor: next_cursor }
+
+      def ==(other)
+        other.is_a?(Page) && other.to_h == to_h
+      end
+      alias eql? ==
+      def hash = to_h.hash
+
+      def deconstruct_keys(_keys) = to_h
+
+      def inspect = "#<#{self.class.name} size=#{size} has_more=#{has_more} next_cursor=#{next_cursor.inspect}>"
+    end
+  end
+end

data/lib/agdirlabs/email/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # Registers the `:agdir_email` ActionMailer delivery method, configured with
+    # `config.action_mailer.agdir_email_settings = { api_key: … }`.
+    class Railtie < ::Rails::Railtie
+      # Must run before ActionMailer copies `config.action_mailer.*` onto ActionMailer::Base,
+      # so that `agdir_email_settings=` exists by then.
+      initializer "agdirlabs_email.add_delivery_method", before: "action_mailer.set_configs" do
+        ActiveSupport.on_load(:action_mailer) do
+          add_delivery_method :agdir_email, AgdirLabs::Email::DeliveryMethod
+        end
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/resources/domains.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    module Resources
+      # `client.domains`
+      class Domains
+        # @api private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # Adds a sending domain. Publish the returned `records` in DNS, then call {#verify}.
+        # @param name [String] e.g. `"acme.com"` or `"mail.acme.com"`
+        # @param region [String, nil]
+        # @return [Domain] with `records`
+        # @raise [Error]
+        def create(name:, region: nil)
+          Wire.domain(@transport.request("POST", "/domains", body: { name: name, region: region }.compact,
+                                                             retryable: false))
+        end
+
+        # @param id [String]
+        # @return [Domain] with `records`
+        # @raise [Error]
+        def get(id)
+          Wire.domain(@transport.request("GET", "/domains/#{Resources.segment(id)}", retryable: true))
+        end
+
+        # One page of domains.
+        # @param limit [Integer, nil] 1–100
+        # @param after [String, nil] cursor: {Page#next_cursor} of the previous page
+        # @return [Page<Domain>] items without `records`
+        # @raise [Error]
+        def list(limit: nil, after: nil)
+          res = @transport.request("GET", "/domains", query: { limit: limit, after: after }, retryable: true)
+          Wire.page(res) { |d| Wire.domain(d.except("records")) }
+        end
+
+        # Every domain, fetching further pages lazily as you iterate.
+        # @return [Enumerator<Domain>]
+        def list_all(limit: nil, after: nil)
+          Resources.paginate(limit: limit, after: after) { |l, a| list(limit: l, after: a) }
+        end
+
+        # Starts a DNS check now instead of waiting for the next automatic one.
+        # @param id [String]
+        # @return [Result]
+        # @raise [Error]
+        def verify(id)
+          res = @transport.request("POST", "/domains/#{Resources.segment(id)}/verify", retryable: true)
+          Result.new(id: Wire.str(res["id"]), deleted: false)
+        end
+
+        # @param id [String]
+        # @return [Result] with `deleted: true`
+        # @raise [Error]
+        def delete(id)
+          res = @transport.request("DELETE", "/domains/#{Resources.segment(id)}", retryable: false)
+          Result.new(id: Wire.str(res["id"]), deleted: true)
+        end
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/resources/emails.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # API resources, reached through a {Client}.
+    module Resources
+      # Percent-encodes one path segment.
+      # @api private
+      def self.segment(value)
+        value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) }
+      end
+
+      # Walks every page of a list endpoint lazily.
+      # @api private
+      def self.paginate(limit:, after:)
+        Enumerator.new do |yielder|
+          cursor = after
+          loop do
+            page = yield(limit, cursor)
+            page.each { |item| yielder << item }
+            break unless page.next_cursor
+
+            cursor = page.next_cursor
+          end
+        end
+      end
+
+      # `client.emails`
+      class Emails
+        # Most emails one {#send_batch} call accepts.
+        MAX_BATCH_SIZE = 100
+
+        # @api private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # Accepts one email for delivery (or for `scheduled_at`).
+        #
+        # Note: this shadows `Object#send` on this object only; use `public_send`/`__send__` for dynamic dispatch.
+        #
+        # @param from [String] `"Name <addr@example.com>"` or a bare address
+        # @param to [String, Array<String>]
+        # @param subject [String]
+        # @param html [String, nil] at least one of `html` and `text` is required
+        # @param text [String, nil]
+        # @param cc [String, Array<String>, nil]
+        # @param bcc [String, Array<String>, nil]
+        # @param reply_to [String, Array<String>, nil]
+        # @param headers [Hash{String => String}, nil] custom headers, e.g. `{"X-Entity-Ref-ID" => "42"}`
+        # @param tags [Array<Hash>, Hash, nil] `[{name: "kind", value: "welcome"}]` or `{kind: "welcome"}`;
+        #   ASCII letters, digits, `_` and `-` only. Echoed back in webhook events.
+        # @param scheduled_at [Time, String, nil] deliver later (a Time, or ISO 8601 with offset)
+        # @param idempotency_key [String, nil] the same key with the same body returns the original result;
+        #   generated automatically when retries are enabled
+        # @return [SendResult]
+        # @raise [Error]
+        def send(idempotency_key: nil, **email)
+          key = idempotency_key(idempotency_key)
+          res = @transport.request("POST", "/emails", body: Wire.send_email_body(email),
+                                                      headers: { "Idempotency-Key" => key }, retryable: !key.nil?)
+          SendResult.new(id: Wire.str(res["id"]))
+        end
+
+        # Accepts up to 100 emails in one request.
+        #
+        # @param emails [Array<Hash>] each with the keyword arguments of {#send} (minus `idempotency_key`)
+        # @param validation [Symbol, String] `:strict` (default): one invalid email rejects the whole batch;
+        #   `:permissive`: valid emails are accepted and invalid ones are reported in {BatchResult#errors}
+        # @param idempotency_key [String, nil]
+        # @return [BatchResult]
+        # @raise [Error]
+        def send_batch(emails, validation: :strict, idempotency_key: nil)
+          mode = validation.to_s
+          raise ArgumentError, "validation must be :strict or :permissive" unless %w[strict permissive].include?(mode)
+
+          key = idempotency_key(idempotency_key)
+          res = @transport.request(
+            "POST", "/emails/batch",
+            body: emails.map { |e| Wire.send_email_body(e) },
+            headers: { "Idempotency-Key" => key, "x-batch-validation" => mode == "permissive" ? mode : nil },
+            retryable: !key.nil?
+          )
+          BatchResult.new(
+            data: (res["data"] || []).map { |d| SendResult.new(id: Wire.str(d["id"])) }.freeze,
+            errors: (res["errors"] || []).map { |e| BatchError.new(index: e["index"], message: Wire.str(e["message"])) }
+                                         .freeze
+          )
+        end
+
+        # Reads an email and its current delivery status. Requires a full-access key.
+        # @param id [String]
+        # @return [EmailDetails]
+        # @raise [Error]
+        def get(id)
+          Wire.email(@transport.request("GET", "/emails/#{Resources.segment(id)}", retryable: true))
+        end
+
+        # Cancels a scheduled email that has not been sent yet.
+        # @param id [String]
+        # @return [Result]
+        # @raise [Error]
+        def cancel(id)
+          res = @transport.request("POST", "/emails/#{Resources.segment(id)}/cancel", retryable: true)
+          Result.new(id: Wire.str(res["id"]), deleted: false)
+        end
+
+        private
+
+        def idempotency_key(given)
+          return given.to_s unless given.nil? || given.to_s.empty?
+
+          # Without a key a retried send could be delivered twice, so only generate one when we may retry.
+          @transport.max_retries.positive? ? SecureRandom.uuid : nil
+        end
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/resources/webhooks.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    module Resources
+      # `client.webhooks.deliveries`: messages sent (or queued) to one webhook endpoint, with their HTTP attempts.
+      class WebhookDeliveries
+        # @api private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        # @param webhook_id [String]
+        # @param limit [Integer, nil] 1–100
+        # @param after [String, nil]
+        # @return [Page<WebhookDelivery>]
+        # @raise [Error]
+        def list(webhook_id, limit: nil, after: nil)
+          res = @transport.request("GET", "/webhooks/#{Resources.segment(webhook_id)}/events",
+                                   query: { limit: limit, after: after }, retryable: true)
+          Wire.page(res) { |e| Wire.delivery(e) }
+        end
+
+        # @return [Enumerator<WebhookDelivery>]
+        def list_all(webhook_id, limit: nil, after: nil)
+          Resources.paginate(limit: limit, after: after) { |l, a| list(webhook_id, limit: l, after: a) }
+        end
+
+        # One delivery with its `payload` and `next_attempt_at`.
+        # @return [WebhookDelivery]
+        # @raise [Error]
+        def get(webhook_id, delivery_id)
+          Wire.delivery(@transport.request("GET", path(webhook_id, delivery_id), retryable: true))
+        end
+
+        # HTTP attempts for one delivery, newest first.
+        # @return [Page<WebhookAttempt>]
+        # @raise [Error]
+        def attempts(webhook_id, delivery_id, limit: nil, after: nil)
+          res = @transport.request("GET", "#{path(webhook_id, delivery_id)}/attempts",
+                                   query: { limit: limit, after: after }, retryable: true)
+          Wire.page(res) { |a| Wire.attempt(a) }
+        end
+
+        # Sends the identical message again, once, right now (also to disabled endpoints).
+        # @return [Result]
+        # @raise [Error]
+        def replay(webhook_id, delivery_id)
+          res = @transport.request("POST", "#{path(webhook_id, delivery_id)}/replay", retryable: false)
+          Result.new(id: Wire.str(res["id"]), deleted: false)
+        end
+
+        private
+
+        def path(webhook_id, delivery_id)
+          "/webhooks/#{Resources.segment(webhook_id)}/events/#{Resources.segment(delivery_id)}"
+        end
+      end
+
+      # `client.webhooks`
+      class Webhooks
+        # Event types a webhook can subscribe to.
+        EVENT_TYPES = %w[
+          email.sent email.scheduled email.delivered email.delivery_delayed email.complained
+          email.bounced email.opened email.clicked email.failed
+        ].freeze
+
+        # @return [WebhookDeliveries]
+        attr_reader :deliveries
+
+        # @api private
+        def initialize(transport)
+          @transport = transport
+          @deliveries = WebhookDeliveries.new(transport)
+        end
+
+        # Registers an endpoint. Keep the returned `signing_secret` to verify incoming events.
+        # @param endpoint [String] public `https://` URL
+        # @param events [Array<String>] see {EVENT_TYPES}
+        # @return [WebhookSecret]
+        # @raise [Error]
+        def create(endpoint:, events:)
+          res = @transport.request("POST", "/webhooks", body: { endpoint: endpoint, events: Array(events) },
+                                                        retryable: false)
+          WebhookSecret.new(id: Wire.str(res["id"]), signing_secret: Wire.str(res["signing_secret"]))
+        end
+
+        # @return [WebhookEndpoint] including `signing_secret`
+        # @raise [Error]
+        def get(id)
+          Wire.webhook(@transport.request("GET", "/webhooks/#{Resources.segment(id)}", retryable: true))
+        end
+
+        # @return [Page<WebhookEndpoint>]
+        # @raise [Error]
+        def list(limit: nil, after: nil)
+          res = @transport.request("GET", "/webhooks", query: { limit: limit, after: after }, retryable: true)
+          Wire.page(res) { |w| Wire.webhook(w) }
+        end
+
+        # @return [Enumerator<WebhookEndpoint>]
+        def list_all(limit: nil, after: nil)
+          Resources.paginate(limit: limit, after: after) { |l, a| list(limit: l, after: a) }
+        end
+
+        # @param endpoint [String, nil]
+        # @param events [Array<String>, nil]
+        # @param status [String, Symbol, nil] `enabled` or `disabled`
+        # @return [Result]
+        # @raise [Error]
+        def update(id, endpoint: nil, events: nil, status: nil)
+          body = { endpoint: endpoint, events: events && Array(events), status: status&.to_s }.compact
+          res = @transport.request("PATCH", "/webhooks/#{Resources.segment(id)}", body: body, retryable: true)
+          Result.new(id: Wire.str(res["id"]), deleted: false)
+        end
+
+        # @return [Result] with `deleted: true`
+        # @raise [Error]
+        def delete(id)
+          res = @transport.request("DELETE", "/webhooks/#{Resources.segment(id)}", retryable: false)
+          Result.new(id: Wire.str(res["id"]), deleted: true)
+        end
+
+        # Issues a new signing secret; the old one stops working immediately.
+        # @return [WebhookSecret]
+        # @raise [Error]
+        def rotate_secret(id)
+          res = @transport.request("POST", "/webhooks/#{Resources.segment(id)}/signing-secret/rotate",
+                                   retryable: false)
+          WebhookSecret.new(id: Wire.str(res["id"]), signing_secret: Wire.str(res["signing_secret"]))
+        end
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/transport.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # A raw HTTP response, as returned by an HTTP client.
+    # @!attribute [r] status
+    #   @return [Integer]
+    # @!attribute [r] headers
+    #   @return [Hash{String => String}] lower-case header names
+    # @!attribute [r] body
+    #   @return [String]
+    HttpResponse = Model.define(:status, :headers, :body)
+
+    # The default HTTP client: Net::HTTP, one connection per request, honouring the
+    # standard `https_proxy` / `http_proxy` / `no_proxy` environment variables.
+    #
+    # A custom client is any object with the same `call` signature (see {Client#initialize}).
+    class NetHttpClient
+      # @param method [String] GET, POST, PATCH or DELETE
+      # @param url [URI::HTTP]
+      # @param headers [Hash{String => String}]
+      # @param body [String, nil]
+      # @param timeout [Numeric] seconds, applied to connect, write and read
+      # @return [HttpResponse]
+      def call(method:, url:, headers:, body:, timeout:)
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = url.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        request = Net::HTTPGenericRequest.new(method, !body.nil?, true, url.request_uri, headers)
+        request.body = body if body
+        response = http.start { |conn| conn.request(request) }
+        HttpResponse.new(
+          status: response.code.to_i,
+          headers: response.each_header.to_h { |k, v| [k.downcase, v] },
+          body: response.body.to_s
+        )
+      end
+    end
+
+    # Sends API requests, retrying rate limits, server errors and network failures when safe.
+    # @api private
+    class Transport
+      RETRY_STATUSES = [408, 500, 502, 503, 504].freeze
+      TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, ::Timeout::Error].freeze
+      NETWORK_ERRORS = [SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError,
+                        Net::HTTPBadResponse, Net::ProtocolError].freeze
+
+      attr_reader :base_url, :max_retries, :timeout
+
+      def initialize(api_key:, base_url:, max_retries:, timeout:, http_client:)
+        @api_key = api_key
+        @base_url = base_url
+        @max_retries = max_retries
+        @timeout = timeout
+        @http_client = http_client
+      end
+
+      # @param retryable [Boolean] safe to repeat: GETs, and POSTs that carry an idempotency key
+      # @return [Hash] the parsed JSON response
+      def request(method, path, retryable:, query: nil, body: nil, headers: {})
+        url = build_url(path, query)
+        request_headers = {
+          "Authorization" => "Bearer #{@api_key}",
+          "User-Agent" => USER_AGENT,
+          "Accept" => "application/json"
+        }
+        request_headers["Content-Type"] = "application/json" unless body.nil?
+        headers.each { |k, v| request_headers[k] = v.to_s unless v.nil? }
+        payload = body.nil? ? nil : JSON.generate(body)
+
+        attempt = 0
+        loop do
+          can_retry = attempt < @max_retries
+          begin
+            response = @http_client.call(method: method, url: url, headers: request_headers, body: payload,
+                                         timeout: @timeout)
+          rescue *TIMEOUT_ERRORS, *NETWORK_ERRORS => e
+            # A timed-out POST may have been accepted: only retry it when it is idempotent.
+            if can_retry && retryable
+              pause(backoff(attempt))
+              attempt += 1
+              next
+            end
+            raise network_error(e)
+          end
+
+          return parse(response.body) if response.status.between?(200, 299)
+
+          error = to_error(response)
+          # Rate limits are refused before any work is done, so they are always safe to retry.
+          retry_it = can_retry && (error.code == "rate_limit_exceeded" ||
+                                   (retryable && RETRY_STATUSES.include?(response.status)))
+          raise error unless retry_it
+
+          pause(error.retry_after || backoff(attempt))
+          attempt += 1
+        end
+      end
+
+      private
+
+      def build_url(path, query)
+        url = URI.parse(@base_url.sub(%r{/+\z}, "") + path)
+        params = (query || {}).compact
+        url.query = URI.encode_www_form(params) unless params.empty?
+        url
+      end
+
+      def parse(body)
+        return {} if body.nil? || body.strip.empty?
+
+        JSON.parse(body)
+      end
+
+      def network_error(cause)
+        if TIMEOUT_ERRORS.any? { |k| cause.is_a?(k) }
+          TimeoutError.new("Request timed out after #{@timeout} s", code: "timeout")
+        else
+          ConnectionError.new("Could not reach the Agdir Email API (#{cause.class}: #{cause.message})",
+                              code: "network_error")
+        end
+      end
+
+      def to_error(response)
+        json = begin
+          parsed = JSON.parse(response.body.to_s)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {} # Not JSON (e.g. a proxy error page) — fall back to the status line.
+        end
+        message = json["message"].is_a?(String) ? json["message"] : "Request failed with HTTP #{response.status}"
+        code = json["name"].is_a?(String) ? json["name"] : default_code(response.status)
+        Error.build(message, code: code, status: response.status,
+                             retry_after: retry_after(response.headers["retry-after"]))
+      end
+
+      def default_code(status) = status >= 500 ? "internal_server_error" : "unknown_error"
+
+      def retry_after(raw)
+        return nil if raw.nil? || raw.strip.empty?
+
+        seconds = Float(raw, exception: false)
+        return [seconds, 0.0].max if seconds
+
+        [Time.httpdate(raw) - Time.now, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+
+      # Exponential backoff with jitter: ~0.5 s, 1 s, 2 s … capped at 8 s.
+      def backoff(attempt)
+        base = [8.0, 0.5 * (2**attempt)].min
+        (base / 2) + (rand * (base / 2))
+      end
+
+      def pause(seconds) = sleep(seconds)
+    end
+  end
+end

data/lib/agdirlabs/email/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    VERSION = "0.1.0"
+
+    # Sent as the `User-Agent` header.
+    USER_AGENT = "agdirlabs-email-ruby/#{VERSION}".freeze
+  end
+end