agentmail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 91279f5876443c121efd7dd19c26ef9dd5ca1ccd8d6b2f3401ae5a800600d1ca
+  data.tar.gz: 4a4d20ae2ded9c37bb3793370c3d3135f31903b4c4ba783a145d1363a9fc0a83
+SHA512:
+  metadata.gz: 2d902cb79eba2890efb15919f66a0644522b7c21c4f66ddc55d4132517b71a27c64b2e05ada8539c28b5c21bdbb8a1eefb3b566ac8b7a3673d5833feb340c94b
+  data.tar.gz: 25cdfd7ddd6918cdea284fe33a970bc84eb072809720be5262672077f392e285a2e0325f30d03c9cada820974e2f304bef16321764d2c5a25fe6a5fe4a722517

data/.env.example

@@ -0,0 +1,4 @@
+# Copy this file to .env and fill in your credentials for smoke testing.
+AGENTMAIL_API_KEY=your_agentmail_api_key
+# Optional recipient for manual email testing when SMOKE_TEST_SEND_EMAIL=true
+SMOKE_TEST_RECIPIENT=recipient@example.com

data/.ruby-version

@@ -0,0 +1 @@
+4.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toadstool Labs
+
+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,81 @@
+# Agentmail Ruby Client
+
+This is a lightweight Ruby wrapper for the [AgentMail](https://agentmail.to/) API inspired by the official [Python SDK](https://github.com/agentmail-to/agentmail-python). It focuses on the core HTTP plumbing and provides a small helper surface around the most common endpoints, while keeping extensibility simple via a generic request method.
+
+## Installation
+
+The gem has not been published yet, so install it straight from the repository:
+
+```ruby
+gem "agentmail", github: "agentmail-to/agentmail-ruby"
+```
+
+Run `bundle install` after updating your `Gemfile`.
+
+## Usage
+
+```ruby
+require "agentmail"
+
+client = Agentmail::Client.new(api_key: ENV.fetch("AGENTMAIL_API_KEY"))
+
+# List inboxes
+client.inboxes.list
+
+# Create an inbox
+client.inboxes.create(display_name: "Support")
+
+# Fetch a thread with filters similar to the Python SDK
+client.threads.list(limit: 25, include_spam: false)
+
+# Use the low-level request helper for endpoints that don't have a helper yet
+client.request(:post, "/v0/inboxes/inbox_123/drafts", body: { subject: "Hello" })
+```
+
+### Configuration
+
+```ruby
+client = Agentmail::Client.new(
+  api_key: -> { ENV["AGENTMAIL_API_KEY"] }, # lazily evaluated for rotations
+  environment: :eu_prod,                    # or :prod, :prod_x_402, :prod_mpp
+  timeout: 30,
+  open_timeout: 2,
+  extra_headers: { "X-Debug" => "1" }
+)
+```
+
+The `environment` option maps to the same host list used by the Python SDK. You can also override `base_url` entirely if you are testing against a mock server.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+The codebase deliberately avoids code generation so a contributor can read through the API surface. If you need an endpoint that is not wrapped yet, either open a PR or call it directly via `Client#request`.
+
+### Publishing to RubyGems
+
+1. Grab your RubyGems API key (`curl -u you https://rubygems.org/api/v1/api_key.yaml`) and add it to the repository as the `RUBYGEMS_API_KEY` secret under **Settings → Secrets and variables → Actions**.
+2. Bump `Agentmail::VERSION` in `lib/agentmail/version.rb`, update the changelog, and commit the changes.
+3. Create a version tag that matches the gem version: `git tag vX.Y.Z`.
+4. Push the tag: `git push origin vX.Y.Z`.
+
+When GitHub receives the tag, the `release.yml` workflow builds the gem, runs the test suite, and publishes the `.gem` to RubyGems using the stored API key. If the tag and gem versions do not match, or the tests fail, the workflow aborts without publishing.
+
+## Manual Smoke Test
+
+1. Copy `.env.example` to `.env` and add your `AGENTMAIL_API_KEY`. Optionally set `SMOKE_TEST_RECIPIENT` if you want to exercise outbound email delivery.
+2. Set `SMOKE_TEST_SEND_EMAIL=true` if you want the script to send a short message to `SMOKE_TEST_RECIPIENT`; otherwise the run is read-only.
+3. Run:
+
+   ```bash
+   bin/smoke_test
+   ```
+
+The script loads the `.env` file and exercises every read-only endpoint we can touch with your credentials (organization, pods, domains, lists, threads, inbox messages, etc.). If `SMOKE_TEST_SEND_EMAIL=true`, it also delivers a short email to the configured recipient so you can confirm outbound delivery end-to-end.
+
+## License
+
+MIT © [Toadstool Labs](http://toadstool.tech)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test

data/lib/agentmail/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+require_relative "error"
+require_relative "response"
+require_relative "resources/inboxes"
+require_relative "resources/threads"
+
+module Agentmail
+  class Client
+    DEFAULT_TIMEOUT = 60
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_ENVIRONMENTS = {
+      prod: "https://api.agentmail.to",
+      prod_x_402: "https://x402.api.agentmail.to",
+      prod_mpp: "https://mpp.api.agentmail.to",
+      eu_prod: "https://api.agentmail.eu"
+    }.freeze
+
+    attr_reader :base_url, :timeout, :open_timeout
+
+    def initialize(
+      api_key: ENV["AGENTMAIL_API_KEY"],
+      base_url: nil,
+      environment: :prod,
+      timeout: DEFAULT_TIMEOUT,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      adapter: Faraday.default_adapter,
+      user_agent: nil,
+      extra_headers: {},
+      logger: nil
+    )
+      @api_key = api_key
+      @base_url = (base_url || resolve_environment(environment)).to_s.sub(%r{\/+\z}, "")
+      @timeout = timeout || DEFAULT_TIMEOUT
+      @open_timeout = open_timeout || DEFAULT_OPEN_TIMEOUT
+      @user_agent = user_agent || default_user_agent
+      @extra_headers = extra_headers
+      @adapter = adapter
+      @logger = logger
+      validate_api_key!
+    end
+
+    def inboxes
+      @inboxes ||= Resources::Inboxes.new(self)
+    end
+
+    def threads
+      @threads ||= Resources::Threads.new(self)
+    end
+
+    def request(method, path, params: nil, body: nil, headers: {}, timeout: nil)
+      response = connection.run_request(
+        method.to_sym,
+        normalize_path(path),
+        encoded_body(body),
+        build_headers(body, headers)
+      ) do |req|
+        req.params.update(stringify_keys(params)) if params
+        req.options.timeout = timeout || @timeout if req.options.respond_to?(:timeout=)
+        req.options.open_timeout = @open_timeout if @open_timeout && req.options.respond_to?(:open_timeout=)
+      end
+
+      parsed_body = parse_body(response)
+      wrapped = Response.new(status: response.status, headers: response.headers.to_h, body: parsed_body)
+      return wrapped if wrapped.success?
+
+      raise Error.new(
+        "AgentMail request failed with status #{response.status}",
+        status: response.status,
+        headers: response.headers.to_h,
+        body: parsed_body
+      )
+    end
+
+    private
+
+    def validate_api_key!
+      key = api_key_value
+      raise ConfigurationError, "An AgentMail API key is required" if key.nil? || key.empty?
+    end
+
+    def api_key_value
+      value = @api_key.respond_to?(:call) ? @api_key.call : @api_key
+      value&.to_s&.strip
+    end
+
+    def build_headers(body, overrides)
+      headers = {
+        "Authorization" => "Bearer #{api_key_value}",
+        "User-Agent" => @user_agent,
+        "Accept" => "application/json"
+      }.merge(@extra_headers).merge(overrides.transform_keys(&:to_s))
+      headers["Content-Type"] = "application/json" if body && !headers.key?("Content-Type")
+      headers
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |faraday|
+        faraday.response :logger, @logger if @logger
+        faraday.adapter @adapter
+      end
+    end
+
+    def encoded_body(body)
+      return nil if body.nil?
+      return body if body.is_a?(String)
+
+      JSON.generate(body)
+    end
+
+    def parse_body(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      content_type = Array(response.headers["content-type"] || response.headers["Content-Type"]).first.to_s
+      if content_type.include?("json")
+        JSON.parse(response.body)
+      else
+        response.body
+      end
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(key, value), acc|
+        acc[key.to_s] = value
+      end
+    end
+
+    def normalize_path(path)
+      if path.to_s.start_with?("http://", "https://")
+        raise ArgumentError, "path must be a relative path, not a full URL"
+      end
+
+      path.to_s.start_with?("/") ? path.to_s : "/#{path}"
+    end
+
+    def resolve_environment(env)
+      DEFAULT_ENVIRONMENTS.fetch(env.to_sym) do
+        raise ConfigurationError, "Unknown environment #{env.inspect}"
+      end
+    end
+
+    def default_user_agent
+      "agentmail-ruby/#{Agentmail::VERSION}"
+    end
+  end
+end

data/lib/agentmail/error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Agentmail
+  # Generic error raised when the API responds with a non-success status or when
+  # the client is configured incorrectly.
+  class Error < StandardError
+    attr_reader :status, :headers, :body
+
+    def initialize(message = nil, status: nil, headers: {}, body: nil)
+      super(message || "AgentMail request failed")
+      @status = status
+      @headers = headers || {}
+      @body = body
+    end
+  end
+
+  class ConfigurationError < StandardError; end
+end

data/lib/agentmail/resources/base_resource.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Agentmail
+  module Resources
+    class BaseResource
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+
+      def request(...)
+        client.request(...)
+      end
+    end
+  end
+end

data/lib/agentmail/resources/inboxes.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base_resource"
+
+module Agentmail
+  module Resources
+    class Inboxes < BaseResource
+      def list(params = {})
+        request(:get, "/v0/inboxes", params: params).body
+      end
+
+      def retrieve(inbox_id)
+        request(:get, inbox_path(inbox_id)).body
+      end
+      alias get retrieve
+
+      def create(attributes = {})
+        request(:post, "/v0/inboxes", body: attributes).body
+      end
+
+      def update(inbox_id, attributes = {})
+        request(:patch, inbox_path(inbox_id), body: attributes).body
+      end
+
+      def delete(inbox_id)
+        request(:delete, inbox_path(inbox_id)).body
+      end
+
+      private
+
+      def inbox_path(inbox_id)
+        "/v0/inboxes/#{inbox_id}"
+      end
+    end
+  end
+end

data/lib/agentmail/resources/threads.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base_resource"
+
+module Agentmail
+  module Resources
+    class Threads < BaseResource
+      def list(params = {})
+        request(:get, "/v0/threads", params: params).body
+      end
+
+      def retrieve(thread_id)
+        request(:get, thread_path(thread_id)).body
+      end
+      alias get retrieve
+
+      def attachment(thread_id, attachment_id)
+        request(:get, "#{thread_path(thread_id)}/attachments/#{attachment_id}").body
+      end
+
+      private
+
+      def thread_path(thread_id)
+        "/v0/threads/#{thread_id}"
+      end
+    end
+  end
+end

data/lib/agentmail/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Agentmail
+  # Wraps the raw Faraday response to provide a predictable surface.
+  class Response
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers:, body:)
+      @status = status
+      @headers = headers
+      @body = body
+    end
+
+    def success?
+      status.to_i >= 200 && status.to_i < 300
+    end
+  end
+end

data/lib/agentmail/version.rb

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

data/lib/agentmail.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "agentmail/version"
+require_relative "agentmail/error"
+require_relative "agentmail/response"
+require_relative "agentmail/client"
+
+module Agentmail
+  def self.new(...)
+    Client.new(...)
+  end
+end

data/sig/agentmail.rbs

@@ -0,0 +1,4 @@
+module Agentmail
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: agentmail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Toadstool Labs
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: A small, well-tested HTTP wrapper around the AgentMail API inspired by
+  the official Python SDK.
+email:
+- hello@toadstool.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- ".ruby-version"
+- LICENSE
+- README.md
+- Rakefile
+- lib/agentmail.rb
+- lib/agentmail/client.rb
+- lib/agentmail/error.rb
+- lib/agentmail/resources/base_resource.rb
+- lib/agentmail/resources/inboxes.rb
+- lib/agentmail/resources/threads.rb
+- lib/agentmail/response.rb
+- lib/agentmail/version.rb
+- sig/agentmail.rbs
+homepage: https://github.com/agentmail-to/agentmail-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/agentmail-to/agentmail-ruby
+  source_code_uri: https://github.com/agentmail-to/agentmail-ruby
+  changelog_uri: https://github.com/agentmail-to/agentmail-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: Lightweight Ruby client for the AgentMail API.
+test_files: []