postmark_ruby_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d157f97b4114e08d81c6c5a7cba8d0e5862c86ecce6cbc520b91764271a8c88
+  data.tar.gz: 248c8666681e1f6baf961c0778eae8bb976b8343c5d78a06012e1ab75bdb6cbf
+SHA512:
+  metadata.gz: 7c128a5537f655491133f0a5f0c58e037549234a61feeb340e802a296dca3102d17696e387af9b17269277161cf1bae598163afb0ab68b198f0bd7e951cb65cd
+  data.tar.gz: 44fcd733e4e2e2935e33d5fb86f3ee6947d37294b6369942a613aa670e77d5d4b362fc83610b31a431873958d7468c07c90516d3148b6607ce9463fa5afc4221

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-15
+
+### Added
+
+- Initial release
+- Email API support for sending single emails
+- Email API support for batch sending (up to 500 emails)
+- Email model with full Postmark API field support
+- Attachment support with auto Base64 encoding
+- File attachment helper method
+- Inline attachment support for HTML emails
+- Custom header support
+- Metadata support
+- Link and open tracking configuration
+- Global configuration via initializer
+- Per-request API token override
+- Comprehensive error handling (ValidationError, ApiError, ConnectionError)
+- Full RSpec test suite
+- YARD documentation

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alvaro Delgado
+
+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,278 @@
+# postmark_ruby_client
+
+A clean, extensible Ruby client for the [Postmark](https://postmarkapp.com) transactional email API. Built with Faraday and designed for Rails 8+ applications.
+
+## Features
+
+- **Simple API**: Intuitive Ruby interface for sending emails
+- **Extensible Design**: Base client class makes it easy to add new API endpoints
+- **Full Email Support**: HTML/text bodies, attachments, custom headers, metadata, tracking
+- **Batch Sending**: Send up to 500 emails in a single API call
+- **Type Safety**: Validation before API calls to catch errors early
+- **Configurable**: Global configuration with per-request overrides
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'postmark_ruby_client'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install postmark_ruby_client
+```
+
+## Configuration
+
+Configure the gem with your Postmark server API token. In a Rails application, create an initializer:
+
+```ruby
+# config/initializers/postmark_ruby_client.rb
+PostmarkClient.configure do |config|
+  config.api_token = ENV["POSTMARK_API_TOKEN"]
+
+  # Optional settings with defaults
+  config.default_message_stream = "outbound"  # Default message stream
+  config.timeout = 30                          # Request timeout in seconds
+  config.open_timeout = 10                     # Connection timeout in seconds
+  config.track_opens = false                   # Default open tracking
+  config.track_links = "None"                  # Default link tracking
+end
+```
+
+The API token can also be set via the `POSTMARK_API_TOKEN` environment variable.
+
+## Usage
+
+### Sending a Simple Email
+
+```ruby
+# Using the convenience method
+response = PostmarkClient.deliver(
+  from: "sender@example.com",
+  to: "recipient@example.com",
+  subject: "Hello!",
+  text_body: "Hello, World!"
+)
+
+if response.success?
+  puts "Email sent! Message ID: #{response.message_id}"
+else
+  puts "Error: #{response.message}"
+end
+```
+
+### Using the Email Model
+
+```ruby
+email = PostmarkClient::Email.new(
+  from: "John Doe <john@example.com>",
+  to: ["alice@example.com", "bob@example.com"],
+  cc: "manager@example.com",
+  bcc: "archive@example.com",
+  subject: "Monthly Report",
+  html_body: "<h1>Report</h1><p>See attached.</p>",
+  text_body: "Report - See attached.",
+  reply_to: "support@example.com",
+  tag: "monthly-report",
+  track_opens: true,
+  track_links: "HtmlAndText",
+  metadata: { "client_id" => "12345" }
+)
+
+client = PostmarkClient::Resources::Emails.new
+response = client.send(email)
+```
+
+### Adding Attachments
+
+```ruby
+email = PostmarkClient::Email.new(
+  from: "sender@example.com",
+  to: "recipient@example.com",
+  subject: "Files attached",
+  text_body: "Please see the attached files."
+)
+
+# Add attachment from parameters
+email.add_attachment(
+  name: "document.pdf",
+  content: File.binread("path/to/document.pdf"),
+  content_type: "application/pdf"
+)
+
+# Or attach directly from a file path
+email.attach_file("path/to/image.png")
+
+# Inline attachments for HTML emails
+email.html_body = '<p>Logo: <img src="cid:logo.png"/></p>'
+email.add_attachment(
+  name: "logo.png",
+  content: File.binread("logo.png"),
+  content_type: "image/png",
+  content_id: "cid:logo.png"
+)
+```
+
+### Custom Headers
+
+```ruby
+email = PostmarkClient::Email.new(
+  from: "sender@example.com",
+  to: "recipient@example.com",
+  subject: "Custom headers",
+  text_body: "Hello"
+)
+
+email.add_header(name: "X-Custom-Header", value: "custom-value")
+email.add_header(name: "X-Priority", value: "1")
+```
+
+### Batch Sending
+
+Send up to 500 emails in a single API call:
+
+```ruby
+emails = users.map do |user|
+  {
+    from: "notifications@example.com",
+    to: user.email,
+    subject: "Your weekly digest",
+    text_body: "Here's what you missed..."
+  }
+end
+
+client = PostmarkClient::Resources::Emails.new
+responses = client.send_batch(emails)
+
+responses.each do |response|
+  if response.success?
+    puts "Sent to #{response.to}"
+  else
+    puts "Failed: #{response.message}"
+  end
+end
+```
+
+### Using a Custom API Token
+
+Override the global configuration for specific requests:
+
+```ruby
+# For a different Postmark server
+client = PostmarkClient::Resources::Emails.new(api_token: "different-token")
+response = client.send(email)
+
+# Or with the convenience method
+client = PostmarkClient.emails(api_token: "different-token")
+response = client.send_email(
+  from: "sender@example.com",
+  to: "recipient@example.com",
+  subject: "Hello",
+  text_body: "World"
+)
+```
+
+### Error Handling
+
+```ruby
+begin
+  response = PostmarkClient.deliver(email)
+rescue PostmarkClient::ValidationError => e
+  # Email failed local validation before sending
+  puts "Validation error: #{e.message}"
+rescue PostmarkClient::ApiError => e
+  # Postmark API returned an error
+  puts "API error #{e.error_code}: #{e.message}"
+  puts "Full response: #{e.response}"
+rescue PostmarkClient::ConnectionError => e
+  # Network connectivity issues
+  puts "Connection error: #{e.message}"
+rescue PostmarkClient::ConfigurationError => e
+  # Missing or invalid configuration
+  puts "Configuration error: #{e.message}"
+end
+```
+
+## API Reference
+
+### PostmarkClient::Email
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `from` | String | Sender email (required) |
+| `to` | String/Array | Recipient email(s) (required) |
+| `cc` | String/Array | CC recipient(s) |
+| `bcc` | String/Array | BCC recipient(s) |
+| `subject` | String | Email subject |
+| `html_body` | String | HTML email body |
+| `text_body` | String | Plain text body |
+| `reply_to` | String | Reply-to address |
+| `tag` | String | Email tag for categorization |
+| `headers` | Array | Custom email headers |
+| `track_opens` | Boolean | Enable open tracking |
+| `track_links` | String | Link tracking ("None", "HtmlAndText", "HtmlOnly", "TextOnly") |
+| `attachments` | Array | Email attachments |
+| `metadata` | Hash | Custom metadata key-value pairs |
+| `message_stream` | String | Message stream identifier |
+
+### PostmarkClient::EmailResponse
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `success?` | Boolean | True if email was sent successfully |
+| `error?` | Boolean | True if there was an error |
+| `message_id` | String | Unique message identifier |
+| `to` | String | Recipient address |
+| `submitted_at` | Time | Timestamp when email was submitted |
+| `error_code` | Integer | Postmark error code (0 = success) |
+| `message` | String | Response message |
+| `raw_response` | Hash | Full API response |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Generate documentation
+bundle exec yard doc
+```
+
+# View documentation in browser
+bundle exec yard server
+# Then open http://localhost:8808
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/postmark_ruby_client.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Related Resources
+
+- [Postmark API Documentation](https://postmarkapp.com/developer)
+- [Postmark Email API Reference](https://postmarkapp.com/developer/api/email-api)

data/Rakefile

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]
+
+namespace :doc do
+  desc "Generate YARD documentation"
+  task :yard do
+    sh "yard doc --output-dir doc/yard"
+  end
+end
+
+desc "Open an IRB console with the gem loaded"
+task :console do
+  require "irb"
+  require_relative "lib/postmark_client"
+
+  ARGV.clear
+  IRB.start
+end

data/lib/postmark_client/client/base.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module PostmarkClient
+  module Client
+    # Base client class for all Postmark API interactions.
+    # Provides common HTTP functionality using Faraday.
+    #
+    # @example Creating a custom resource client
+    #   class MyResource < PostmarkClient::Client::Base
+    #     def fetch(id)
+    #       get("/my-resource/#{id}")
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement specific API resource methods
+    class Base
+      # Postmark API base URL
+      API_BASE_URL = "https://api.postmarkapp.com"
+
+      # @return [String] the API token for authentication
+      attr_reader :api_token
+
+      # @return [Hash] additional options passed to the client
+      attr_reader :options
+
+      # Initialize a new API client
+      #
+      # @param api_token [String, nil] the Postmark server API token.
+      #   Falls back to PostmarkClient.configuration.api_token if not provided.
+      # @param options [Hash] additional configuration options
+      # @option options [Integer] :timeout request timeout in seconds (default: 30)
+      # @option options [Integer] :open_timeout connection open timeout in seconds (default: 10)
+      # @option options [String] :base_url override the default API base URL
+      #
+      # @raise [PostmarkClient::ConfigurationError] if no API token is available
+      def initialize(api_token: nil, **options)
+        @api_token = api_token || PostmarkClient.configuration.api_token
+        @options = options
+
+        raise ConfigurationError, "API token is required" if @api_token.nil? || @api_token.empty?
+      end
+
+      protected
+
+      # Perform a GET request to the Postmark API
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash] query parameters
+      # @return [Hash] parsed JSON response
+      def get(path, params = {})
+        request(:get, path, params)
+      end
+
+      # Perform a POST request to the Postmark API
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash] request body
+      # @return [Hash] parsed JSON response
+      def post(path, body = {})
+        request(:post, path, body)
+      end
+
+      # Perform a PUT request to the Postmark API
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash] request body
+      # @return [Hash] parsed JSON response
+      def put(path, body = {})
+        request(:put, path, body)
+      end
+
+      # Perform a DELETE request to the Postmark API
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash] query parameters
+      # @return [Hash] parsed JSON response
+      def delete(path, params = {})
+        request(:delete, path, params)
+      end
+
+      private
+
+      # Build and return a configured Faraday connection
+      #
+      # @return [Faraday::Connection] configured connection instance
+      def connection
+        @connection ||= Faraday.new(url: base_url) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          conn.response :raise_error
+
+          conn.headers["Accept"] = "application/json"
+          conn.headers["Content-Type"] = "application/json"
+          conn.headers["X-Postmark-Server-Token"] = api_token
+
+          conn.options.timeout = options.fetch(:timeout, 30)
+          conn.options.open_timeout = options.fetch(:open_timeout, 10)
+
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # Get the base URL for API requests
+      #
+      # @return [String] the API base URL
+      def base_url
+        options.fetch(:base_url, API_BASE_URL)
+      end
+
+      # Perform an HTTP request and handle the response
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param path [String] the API endpoint path
+      # @param payload [Hash] request body or query parameters
+      # @return [Hash] parsed JSON response
+      #
+      # @raise [PostmarkClient::ApiError] on API error responses
+      # @raise [PostmarkClient::ConnectionError] on network errors
+      def request(method, path, payload = {})
+        response = case method
+                   when :get, :delete
+                     connection.public_send(method, path, payload)
+                   when :post, :put
+                     connection.public_send(method, path, payload)
+                   end
+
+        response.body
+      rescue Faraday::ClientError => e
+        handle_client_error(e)
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+        raise ConnectionError, "Connection failed: #{e.message}"
+      end
+
+      # Handle Faraday client errors and raise appropriate exceptions
+      #
+      # @param error [Faraday::ClientError] the caught error
+      # @raise [PostmarkClient::ApiError] with details from the response
+      def handle_client_error(error)
+        body = parse_error_body(error.response&.dig(:body))
+        error_code = body["ErrorCode"] || error.response&.dig(:status)
+        message = body["Message"] || error.message
+
+        raise ApiError.new(message, error_code: error_code, response: body)
+      end
+
+      # Parse error body which may be a string or hash
+      #
+      # @param body [String, Hash, nil] the response body
+      # @return [Hash] parsed body
+      def parse_error_body(body)
+        return {} if body.nil?
+        return body if body.is_a?(Hash)
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/postmark_client/configuration.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module PostmarkClient
+  # Configuration class for PostmarkClient gem.
+  # Stores global settings that apply to all API clients.
+  #
+  # @example Configuring the gem in a Rails initializer
+  #   # config/initializers/postmark_ruby_client.rb
+  #   PostmarkClient.configure do |config|
+  #     config.api_token = ENV["POSTMARK_API_TOKEN"]
+  #     config.default_message_stream = "outbound"
+  #     config.timeout = 60
+  #   end
+  #
+  # @example Accessing configuration
+  #   PostmarkClient.configuration.api_token
+  class Configuration
+    # @return [String, nil] the Postmark server API token
+    attr_accessor :api_token
+
+    # @return [String] the default message stream for emails (default: "outbound")
+    attr_accessor :default_message_stream
+
+    # @return [Integer] request timeout in seconds (default: 30)
+    attr_accessor :timeout
+
+    # @return [Integer] connection open timeout in seconds (default: 10)
+    attr_accessor :open_timeout
+
+    # @return [Boolean] whether to track email opens by default (default: false)
+    attr_accessor :track_opens
+
+    # @return [String] default link tracking setting (default: "None")
+    #   Valid values: "None", "HtmlAndText", "HtmlOnly", "TextOnly"
+    attr_accessor :track_links
+
+    # Initialize configuration with default values
+    def initialize
+      @api_token = ENV.fetch("POSTMARK_API_TOKEN", nil)
+      @default_message_stream = "outbound"
+      @timeout = 30
+      @open_timeout = 10
+      @track_opens = false
+      @track_links = "None"
+    end
+  end
+
+  class << self
+    # @return [Configuration] the global configuration instance
+    attr_writer :configuration
+
+    # Get the current configuration, initializing if necessary
+    #
+    # @return [Configuration] the global configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem using a block
+    #
+    # @yield [Configuration] the configuration instance
+    # @return [void]
+    #
+    # @example
+    #   PostmarkClient.configure do |config|
+    #     config.api_token = "your-token"
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Reset the configuration to defaults
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/postmark_client/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PostmarkClient
+  # Base error class for all PostmarkClient errors
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing
+  #
+  # @example
+  #   raise ConfigurationError, "API token is required"
+  class ConfigurationError < Error; end
+
+  # Raised when there are network connectivity issues
+  #
+  # @example
+  #   raise ConnectionError, "Connection timeout"
+  class ConnectionError < Error; end
+
+  # Raised when the Postmark API returns an error response
+  #
+  # @example Handling API errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue PostmarkClient::ApiError => e
+  #     puts "Error #{e.error_code}: #{e.message}"
+  #     puts "Response: #{e.response}"
+  #   end
+  class ApiError < Error
+    # @return [Integer, String, nil] the Postmark error code
+    attr_reader :error_code
+
+    # @return [Hash, nil] the full error response body
+    attr_reader :response
+
+    # Initialize a new API error
+    #
+    # @param message [String] the error message
+    # @param error_code [Integer, String, nil] the Postmark error code
+    # @param response [Hash, nil] the full response body
+    def initialize(message, error_code: nil, response: nil)
+      @error_code = error_code
+      @response = response
+      super(message)
+    end
+  end
+
+  # Raised when email validation fails before sending
+  #
+  # @example
+  #   raise ValidationError, "From address is required"
+  class ValidationError < Error; end
+end