agdirlabs-email 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e90d39e665d132cba468bcb1cf9a87de5e19832933825e954f812c3991d16593
+  data.tar.gz: '02390d75130537e82db815bd5636258d931e419a168ce4484a4adf9ffdc0b697'
+SHA512:
+  metadata.gz: 87bd23713224b953ab8e78039363967631996e2f7d358be91cf608da1f9f698f0bfee3324d71c6b548877d74bd5cca05077be8994caa2fdfdd910a6a4ad2e479
+  data.tar.gz: eda7c94113ad820da4087fc5552986687e22bbb0e8bf732a61a96ca31f05f177968bb98f242bfc80f8b3e9334ecec22f1d9630bbd5bd013828b8cfa905039842

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog — agdirlabs-email (Ruby)
+
+All notable changes to this gem are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the gem uses [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-10-30
+
+### Added
+
+- `AgdirLabs::Email::Client` for the Agdir Email API, with no runtime dependencies (Ruby 3.1+).
+- `emails`: `send`, `send_batch` (strict or permissive validation), `get`, `cancel`.
+- `domains`: `create`, `get`, `list`, `list_all`, `verify`, `delete`.
+- `webhooks`: `create`, `get`, `list`, `list_all`, `update`, `delete`, `rotate_secret`, and `deliveries` (`list`, `list_all`, `get`, `attempts`, `replay`).
+- Frozen response objects with `Time` timestamps; `list_all` returns a lazily paging `Enumerator`.
+- `AgdirLabs::Email::Webhook.verify` for signed webhook requests (Standard Webhooks).
+- `AgdirLabs::Email::Error` with `code`, `status` and `retry_after`, and subclasses per error family.
+- Automatic retries for rate limits, server errors and network failures, with generated idempotency keys for sends.
+- `:agdir_email` ActionMailer delivery method (Railtie) and `AgdirLabs::Email::DeliveryMethod` for the `mail` gem.
+- RBS signatures.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agdir AS
+
+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,284 @@
+# agdirlabs-email
+
+[![Gem](https://img.shields.io/gem/v/agdirlabs-email.svg)](https://rubygems.org/gems/agdirlabs-email)
+[![CI](https://github.com/AgdirAS/agdirlabs-sdks/actions/workflows/ruby.yml/badge.svg)](https://github.com/AgdirAS/agdirlabs-sdks/actions/workflows/ruby.yml)
+
+The official Ruby SDK for [Agdir Email](https://agdir.email) — programmatic SMTP for developers, hosted in the EU. Built by [Agdir Labs](https://agdirlabs.com) at [Agdir](https://agdir.no).
+
+- No runtime dependencies (Net::HTTP, JSON, OpenSSL from the standard library)
+- Ruby 3.1+, thread-safe client, RBS signatures and YARD docs
+- Rails ActionMailer delivery method (`:agdir_email`), also usable with the `mail` gem
+- Safe automatic retries with idempotency keys
+- Lazy cursor pagination with `Enumerator`
+- Webhook signature verification built in
+
+## Install
+
+```ruby
+# Gemfile
+gem "agdirlabs-email"
+```
+
+or `gem install agdirlabs-email`.
+
+## Quick start
+
+Create an API key at [app.agdir.email](https://app.agdir.email) and verify a sending domain, then:
+
+```ruby
+require "agdirlabs/email"
+
+client = AgdirLabs::Email::Client.new(api_key: ENV["AGDIR_EMAIL_API_KEY"])
+
+result = client.emails.send(
+  from: "Acme <hello@acme.com>",
+  to: "user@example.com",
+  subject: "Welcome to Acme",
+  html: "<p>Thanks for signing up!</p>"
+)
+result.id # => "4ef9a417-…"
+```
+
+`AgdirLabs::Email::Client.new` with no arguments reads `AGDIR_EMAIL_API_KEY` from the environment. Create one client and share it; it is thread-safe.
+
+## Emails
+
+```ruby
+# Plain text, several recipients, reply-to, tags, custom headers
+client.emails.send(
+  from: "Acme <billing@acme.com>",
+  to: ["ana@example.com", "ben@example.com"],
+  cc: "finance@acme.com",
+  reply_to: "support@acme.com",
+  subject: "Your invoice",
+  text: "Invoice #1042 is ready in your dashboard.",
+  tags: { kind: "invoice" },                    # or [{ name: "kind", value: "invoice" }]
+  headers: { "X-Entity-Ref-ID" => "inv-1042" }
+)
+
+# Schedule for later, then cancel if plans change
+sent = client.emails.send(**email, scheduled_at: Time.now + 3600)
+client.emails.cancel(sent.id)
+
+# Delivery status
+email = client.emails.get(sent.id)
+email.status     # => "queued" | "scheduled" | "sent" | "delivered" | "bounced" | "complained" | …
+email.created_at # => Time
+
+# Up to 100 emails per request (all-or-nothing by default)
+batch = client.emails.send_batch([email1, email2])
+batch.data.map(&:id)
+
+# Accept the valid ones, report the rest
+batch = client.emails.send_batch(emails, validation: :permissive)
+batch.errors.each { |e| warn "email #{e.index}: #{e.message}" }
+```
+
+Responses are frozen, keyword-initialized structs (`SendResult`, `EmailDetails`, `Domain`, …) with `Time` timestamps; they support `to_h`, `==` and pattern matching:
+
+```ruby
+case client.emails.get(id)
+in { status: "bounced" | "complained" } then suppress!(id)
+in { status: "delivered" } then nil
+end
+```
+
+## Domains
+
+```ruby
+domain = client.domains.create(name: "acme.com")
+domain.records.each { |r| puts "#{r.type} #{r.name} #{r.value}" } # add these to your DNS (r.purpose: DKIM/SPF/DMARC)
+
+client.domains.verify(domain.id)          # check DNS now instead of waiting
+client.domains.get(domain.id).status      # "pending" → "verified"
+
+page = client.domains.list(limit: 20)     # one page: page.data, page.has_more?, page.next_cursor
+client.domains.list(after: page.next_cursor) if page.has_more?
+
+client.domains.list_all.each { |d| puts "#{d.name} #{d.status}" } # every domain, fetched lazily page by page
+client.domains.list_all.lazy.select(&:verified?).first(5)
+
+client.domains.delete(domain.id)
+```
+
+## Webhooks
+
+```ruby
+hook = client.webhooks.create(
+  endpoint: "https://acme.com/webhooks/email",
+  events: %w[email.delivered email.bounced email.complained]
+)
+hook.signing_secret # => "whsec_…" — store it to verify incoming events
+
+client.webhooks.update(hook.id, status: :disabled)
+client.webhooks.rotate_secret(hook.id)
+
+# What was sent to your endpoint, and each HTTP attempt
+deliveries = client.webhooks.deliveries.list(hook.id)
+attempts = client.webhooks.deliveries.attempts(hook.id, deliveries.first.id)
+client.webhooks.deliveries.replay(hook.id, deliveries.first.id)
+```
+
+### Verifying incoming events
+
+Every request to your endpoint is signed ([Standard Webhooks](https://www.standardwebhooks.com)). Verify it against the **raw** body before trusting it:
+
+```ruby
+# Rails
+class EmailWebhooksController < ActionController::API
+  def create
+    event = AgdirLabs::Email::Webhook.verify(
+      payload: request.raw_post,
+      headers: request.headers,
+      secret: ENV.fetch("AGDIR_EMAIL_WEBHOOK_SECRET")
+    )
+    mark_bounced(event.data.to, event.data.bounce) if event.type == "email.bounced"
+    head :no_content
+  rescue AgdirLabs::Email::WebhookVerificationError
+    head :bad_request
+  end
+end
+
+# Sinatra / Rack
+post "/webhooks/email" do
+  event = AgdirLabs::Email::Webhook.verify(payload: request.body.read, headers: request.env, secret: SECRET)
+  # …
+  204
+end
+```
+
+`headers:` accepts a Hash (any key case, Rack `HTTP_*` keys work too) or anything with a `[]` reader, like Rails' `request.headers`. Messages older than 5 minutes are rejected (`tolerance:` to change). Failed deliveries are retried for about 18 hours; use `event.data.email_id` to deduplicate.
+
+## Rails (ActionMailer)
+
+Requiring the gem in a Rails app registers the `:agdir_email` delivery method:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :agdir_email
+config.action_mailer.agdir_email_settings = {
+  api_key: Rails.application.credentials.agdir_email_api_key # default: ENV["AGDIR_EMAIL_API_KEY"]
+  # base_url:, max_retries:, timeout: — see Configuration
+}
+```
+
+Your mailers stay as they are. From, To, Cc, Bcc, Reply-To, Subject, the HTML and text parts, and every `X-…` header are sent. A few headers control the API and are not sent:
+
+| Header | Effect |
+| --- | --- |
+| `X-Agdir-Tags: kind=welcome, plan=pro` | tags (echoed back in webhook events) |
+| `X-Agdir-Scheduled-At: 2026-11-01T09:00:00+01:00` | deliver later |
+| `X-Agdir-Idempotency-Key: welcome/42` | idempotency key (one is generated otherwise) |
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome(user)
+    headers["X-Agdir-Tags"] = "kind=welcome"
+    headers["X-Agdir-Idempotency-Key"] = "welcome/#{user.id}"
+    mail(to: user.email, subject: "Welcome!")
+  end
+end
+
+message = UserMailer.welcome(user).deliver_now
+message["X-Agdir-Email-Id"].value # the Agdir Email id, for client.emails.get
+```
+
+Attachments are not supported by the API yet: a message with attachments raises `AgdirLabs::Email::UnsupportedMessageError` (link to the file instead). API errors raise `AgdirLabs::Email::Error` subclasses, so `raise_delivery_errors` and `deliver_later` retries work as usual.
+
+Without Rails, use it with the [`mail`](https://github.com/mikel/mail) gem:
+
+```ruby
+Mail.defaults { delivery_method AgdirLabs::Email::DeliveryMethod, api_key: ENV["AGDIR_EMAIL_API_KEY"] }
+```
+
+## Errors
+
+Every failed call raises an `AgdirLabs::Email::Error`:
+
+```ruby
+begin
+  client.emails.send(**email)
+rescue AgdirLabs::Email::QuotaExceededError => e
+  # daily_quota_exceeded / monthly_quota_exceeded — never retried
+rescue AgdirLabs::Email::Error => e
+  e.code        # "validation_error" | "rate_limit_exceeded" | "network_error" | "timeout" | …
+  e.status      # HTTP status, 0 if no response
+  e.message     # human-readable explanation
+  e.retry_after # seconds from retry-after, if any
+end
+```
+
+| Class | Codes |
+| --- | --- |
+| `AuthenticationError` | `missing_api_key`, `invalid_api_key`, `restricted_api_key` |
+| `ValidationError` | `validation_error` (422; 403 for an unverified domain, paused team or domain limit) |
+| `NotFoundError` | `not_found` |
+| `IdempotencyError` | `invalid_idempotent_request`, `concurrent_idempotent_requests` |
+| `RateLimitError` | `rate_limit_exceeded` (after retries) |
+| `QuotaExceededError` | `daily_quota_exceeded`, `monthly_quota_exceeded` |
+| `ServerError` | 5xx |
+| `ConnectionError` / `TimeoutError` | `network_error` / `timeout` (no response) |
+
+A missing API key raises `AgdirLabs::Email::ConfigurationError` when the client is created.
+
+## Retries and idempotency
+
+Rate limits (`429 rate_limit_exceeded`), server errors (408/500/502/503/504) and network failures are retried up to `max_retries` times (default 2) with exponential backoff, honouring `retry-after`. Sends are only retried with an idempotency key, so a retry can never deliver an email twice: the SDK generates one per call, or you can pass your own to make sends safe across process restarts too:
+
+```ruby
+client.emails.send(**email, idempotency_key: "welcome/#{user.id}")
+```
+
+Quota errors are not retried.
+
+## Configuration
+
+```ruby
+AgdirLabs::Email::Client.new(
+  api_key: "re_…",                       # default: ENV["AGDIR_EMAIL_API_KEY"]
+  base_url: "https://api.agdir.email",   # default: ENV["AGDIR_EMAIL_BASE_URL"], else this
+  max_retries: 2,
+  timeout: 30,                           # seconds, per attempt
+  http_client: nil                       # custom transport (see below)
+)
+```
+
+Requests use Net::HTTP and honour the standard `https_proxy` / `no_proxy` environment variables. To use another HTTP library, pass any object with `call(method:, url:, headers:, body:, timeout:)` returning an `AgdirLabs::Email::HttpResponse` (`status`, `headers`, `body`). To cancel a long-running call, run it in a thread or use `timeout:`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake          # tests, RuboCop, RBS validation
+bundle exec rake test
+```
+
+Live tests run against a real API only when configured (never against production):
+
+```bash
+AGDIR_EMAIL_LIVE_BASE_URL=http://localhost:8080/api \
+AGDIR_EMAIL_LIVE_API_KEY=re_… \
+AGDIR_EMAIL_LIVE_FROM=hi@your-verified-domain.example \
+bundle exec ruby -Ilib -Itest test/live_test.rb
+```
+
+## Releasing
+
+Releases are published from GitHub Actions with [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC): no API key is stored anywhere.
+
+1. Bump `AgdirLabs::Email::VERSION` in `lib/agdirlabs/email/version.rb` and add a `CHANGELOG.md` entry; merge to `main`.
+2. Push a tag `ruby/v<version>`, e.g. `git tag ruby/v0.1.0 && git push origin ruby/v0.1.0`.
+3. `.github/workflows/ruby-release.yml` checks the tag against `VERSION`, runs the tests and publishes with `rubygems/release-gem` (`rake release` from `ruby/`; the Rakefile disables its own `v*` git tag push).
+
+One-time setup on rubygems.org (by a maintainer of the AgdirAS organisation account):
+
+- **Before the first release** (the gem does not exist yet): rubygems.org → your profile → *Trusted publishers* → *Create pending trusted publisher*: gem name `agdirlabs-email`, repository owner `AgdirAS`, repository name `agdirlabs-sdks`, workflow filename `ruby-release.yml`, environment empty.
+- **After the first release**: the pending publisher becomes the gem's trusted publisher (gem page → *Trusted publishers*). Add the other maintainers as gem owners.
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](../CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE) © [Agdir AS](https://agdir.no)

data/lib/agdirlabs/email/client.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # Default API base URL.
+    DEFAULT_BASE_URL = "https://api.agdir.email"
+
+    # Agdir Email API client. Thread-safe: share one instance.
+    #
+    #   client = AgdirLabs::Email::Client.new(api_key: "re_…")
+    #   client.emails.send(from: "Acme <hi@acme.com>", to: "ana@example.com", subject: "Hi", html: "<p>Hi</p>")
+    class Client
+      # @return [Resources::Emails]
+      attr_reader :emails
+      # @return [Resources::Domains]
+      attr_reader :domains
+      # @return [Resources::Webhooks]
+      attr_reader :webhooks
+      # @return [String]
+      attr_reader :base_url
+      # @return [Integer]
+      attr_reader :max_retries
+      # @return [Numeric]
+      attr_reader :timeout
+
+      # @param api_key [String, nil] defaults to `ENV["AGDIR_EMAIL_API_KEY"]`
+      # @param base_url [String, nil] defaults to `ENV["AGDIR_EMAIL_BASE_URL"]`, else https://api.agdir.email
+      # @param max_retries [Integer] retries for rate limits, server errors and network failures; 0 disables
+      # @param timeout [Numeric] seconds per attempt
+      # @param http_client [#call, nil] custom HTTP client:
+      #   `call(method:, url:, headers:, body:, timeout:)` returning an {HttpResponse}. Defaults to {NetHttpClient}.
+      # @raise [ConfigurationError] when no API key is available
+      def initialize(api_key: nil, base_url: nil, max_retries: 2, timeout: 30, http_client: nil)
+        api_key = present(api_key) || present(ENV.fetch("AGDIR_EMAIL_API_KEY", nil))
+        unless api_key
+          raise ConfigurationError,
+                "Missing API key: pass api_key: or set AGDIR_EMAIL_API_KEY. Create one at https://app.agdir.email."
+        end
+        unless max_retries.is_a?(Integer) && !max_retries.negative?
+          raise ConfigurationError, "max_retries must be a non-negative Integer"
+        end
+        raise ConfigurationError, "timeout must be a positive number" unless timeout.is_a?(Numeric) && timeout.positive?
+
+        @base_url = (present(base_url) || present(ENV.fetch("AGDIR_EMAIL_BASE_URL", nil)) || DEFAULT_BASE_URL).freeze
+        @max_retries = max_retries
+        @timeout = timeout
+        transport = Transport.new(api_key: api_key, base_url: @base_url, max_retries: max_retries, timeout: timeout,
+                                  http_client: http_client || NetHttpClient.new)
+        @emails = Resources::Emails.new(transport)
+        @domains = Resources::Domains.new(transport)
+        @webhooks = Resources::Webhooks.new(transport)
+      end
+
+      # Keeps the API key out of logs and consoles.
+      def inspect = "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+
+      private
+
+      # Empty values (e.g. `AGDIR_EMAIL_BASE_URL=` in a .env file) count as unset.
+      def present(value)
+        value.nil? || value.to_s.empty? ? nil : value.to_s
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/delivery_method.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # A delivery method for the `mail` gem and Rails ActionMailer that sends through the Agdir Email API.
+    #
+    # Rails (registered by the Railtie):
+    #
+    #   config.action_mailer.delivery_method = :agdir_email
+    #   config.action_mailer.agdir_email_settings = { api_key: ENV["AGDIR_EMAIL_API_KEY"] }
+    #
+    # Plain `mail` gem:
+    #
+    #   Mail.defaults { delivery_method AgdirLabs::Email::DeliveryMethod, api_key: "re_…" }
+    #
+    # Mapped: From, To, Cc, Bcc, Reply-To, Subject, the HTML and text parts, and every `X-…` header.
+    # Special headers (removed before sending):
+    #
+    # - `X-Agdir-Tags: kind=welcome, plan=pro` → `tags`
+    # - `X-Agdir-Scheduled-At: 2026-11-01T09:00:00+01:00` → `scheduled_at`
+    # - `X-Agdir-Idempotency-Key: welcome/42` → idempotency key
+    #
+    # After sending, the email id is stored in the message's `X-Agdir-Email-Id` header and returned
+    # (Mail returns it from `deliver!` when `return_response: true` is set).
+    class DeliveryMethod
+      TAGS_HEADER = "X-Agdir-Tags"
+      SCHEDULED_AT_HEADER = "X-Agdir-Scheduled-At"
+      IDEMPOTENCY_KEY_HEADER = "X-Agdir-Idempotency-Key"
+      EMAIL_ID_HEADER = "X-Agdir-Email-Id"
+      CONTROL_HEADERS = [TAGS_HEADER, SCHEDULED_AT_HEADER, IDEMPOTENCY_KEY_HEADER, EMAIL_ID_HEADER]
+                        .map(&:downcase).freeze
+      CLIENT_OPTIONS = %i[api_key base_url max_retries timeout http_client].freeze
+
+      # @return [Hash] the settings this delivery method was created with
+      attr_accessor :settings
+
+      # @param settings [Hash] `api_key:`, `base_url:`, `max_retries:`, `timeout:`, `http_client:`
+      #   (see {Client#initialize}) or a ready `client:`. Missing values fall back to the environment.
+      def initialize(settings = {})
+        @settings = (settings || {}).to_h.transform_keys(&:to_sym)
+      end
+
+      # Sends a Mail::Message.
+      # @param mail [Mail::Message]
+      # @return [SendResult]
+      # @raise [UnsupportedMessageError] for messages with attachments
+      # @raise [Error] when the API rejects the email
+      def deliver!(mail)
+        params, key = self.class.to_params(mail)
+        result = client.emails.send(idempotency_key: key, **params)
+        mail[EMAIL_ID_HEADER] = result.id
+        result
+      end
+
+      # The {Client} used to send (built lazily from {#settings}).
+      # @return [Client]
+      def client
+        @client ||= settings[:client] || Client.new(**settings.slice(*CLIENT_OPTIONS))
+      end
+
+      class << self
+        # Maps a Mail::Message to keyword arguments for {Resources::Emails#send}.
+        # @return [Array(Hash, String)] the email params and the idempotency key (or nil)
+        def to_params(mail)
+          if mail.has_attachments?
+            raise UnsupportedMessageError,
+                  "Attachments are not supported by the Agdir Email API yet; remove them or link to the files instead"
+          end
+
+          params = {
+            from: addresses(mail, :from).first,
+            to: addresses(mail, :to),
+            cc: addresses(mail, :cc),
+            bcc: addresses(mail, :bcc),
+            reply_to: addresses(mail, :reply_to),
+            subject: mail.subject.to_s,
+            html: body(mail, "text/html"),
+            text: body(mail, "text/plain"),
+            headers: custom_headers(mail),
+            tags: tags(mail),
+            scheduled_at: header(mail, SCHEDULED_AT_HEADER)
+          }
+          optional = %i[cc bcc reply_to headers tags]
+          params.reject! { |k, v| v.nil? || (optional.include?(k) && v.empty?) }
+          [params, header(mail, IDEMPOTENCY_KEY_HEADER)]
+        end
+
+        private
+
+        def addresses(mail, field)
+          value = mail[field]
+          return [] if value.nil?
+
+          formatted = value.respond_to?(:formatted) ? value.formatted : Array(value.to_s)
+          formatted.map { |a| utf8(a) }
+        end
+
+        def body(mail, mime_type)
+          part = if mail.multipart?
+                   mime_type == "text/html" ? mail.html_part : mail.text_part
+                 elsif (mail.mime_type || "text/plain") == mime_type
+                   mail
+                 end
+          return nil if part.nil?
+
+          text = utf8(part.decoded)
+          text.empty? ? nil : text
+        end
+
+        def custom_headers(mail)
+          mail.header.fields.each_with_object({}) do |field, out|
+            name = field.name.to_s
+            next unless name.downcase.start_with?("x-") && !CONTROL_HEADERS.include?(name.downcase)
+
+            out[name] = out.key?(name) ? "#{out[name]}, #{utf8(field.value)}" : utf8(field.value)
+          end
+        end
+
+        def tags(mail)
+          values = mail.header.fields.select { |f| f.name.to_s.casecmp?(TAGS_HEADER) }.map { |f| f.value.to_s }
+          values.flat_map { |v| v.split(",") }.filter_map do |pair|
+            name, value = pair.split("=", 2).map(&:strip)
+            next if name.nil? || name.empty?
+
+            { name: name, value: value.to_s }
+          end
+        end
+
+        def header(mail, name)
+          field = mail.header.fields.find { |f| f.name.to_s.casecmp?(name) }
+          value = field&.value.to_s.strip
+          value.nil? || value.empty? ? nil : value
+        end
+
+        def utf8(value)
+          string = value.to_s
+          string = string.dup.force_encoding(Encoding::UTF_8) if string.encoding == Encoding::BINARY
+          string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/errors.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # Raised by every client method when a request fails.
+    #
+    # Rescue this class for everything, or one of its subclasses for a family of errors.
+    # {#code} is the API's machine-readable error name (e.g. `"validation_error"`), or
+    # `"network_error"` / `"timeout"` when no response was received.
+    class Error < StandardError
+      # @return [String] machine-readable code, e.g. `"validation_error"` or `"rate_limit_exceeded"`
+      attr_reader :code
+      # @return [Integer] HTTP status, or 0 when no response was received
+      attr_reader :status
+      # @return [Float, nil] seconds the API asked us to wait (from `retry-after`), if any
+      attr_reader :retry_after
+
+      # @param message [String]
+      # @param code [String]
+      # @param status [Integer]
+      # @param retry_after [Float, nil]
+      def initialize(message = nil, code: "unknown_error", status: 0, retry_after: nil)
+        super(message)
+        @code = code
+        @status = status
+        @retry_after = retry_after
+      end
+
+      # Builds the most specific subclass for an API error code / HTTP status.
+      # @return [Error]
+      def self.build(message, code:, status:, retry_after: nil)
+        klass = CODES.fetch(code) do
+          if status >= 500 then ServerError
+          elsif status == 409 then IdempotencyError
+          else Error
+          end
+        end
+        klass.new(message, code: code, status: status, retry_after: retry_after)
+      end
+    end
+
+    # `missing_api_key`, `invalid_api_key`, `restricted_api_key`.
+    class AuthenticationError < Error; end
+    # `validation_error` (422; 403 for an unverified domain, paused team or domain limit).
+    class ValidationError < Error; end
+    # `not_found`.
+    class NotFoundError < Error; end
+    # `invalid_idempotent_request`, `concurrent_idempotent_requests`.
+    class IdempotencyError < Error; end
+    # `rate_limit_exceeded`: retried automatically; raised once retries are exhausted.
+    class RateLimitError < Error; end
+    # `daily_quota_exceeded`, `monthly_quota_exceeded`: never retried.
+    class QuotaExceededError < Error; end
+    # 5xx responses.
+    class ServerError < Error; end
+    # The API could not be reached (`network_error`).
+    class ConnectionError < Error; end
+    # An attempt took longer than the configured timeout (`timeout`).
+    class TimeoutError < ConnectionError; end
+
+    class Error
+      CODES = {
+        "missing_api_key" => AuthenticationError,
+        "invalid_api_key" => AuthenticationError,
+        "restricted_api_key" => AuthenticationError,
+        "validation_error" => ValidationError,
+        "not_found" => NotFoundError,
+        "invalid_idempotent_request" => IdempotencyError,
+        "concurrent_idempotent_requests" => IdempotencyError,
+        "rate_limit_exceeded" => RateLimitError,
+        "daily_quota_exceeded" => QuotaExceededError,
+        "monthly_quota_exceeded" => QuotaExceededError,
+        "internal_server_error" => ServerError,
+        "network_error" => ConnectionError,
+        "timeout" => TimeoutError
+      }.freeze
+    end
+
+    # Raised when the client is misconfigured, e.g. no API key is available.
+    class ConfigurationError < ArgumentError; end
+
+    # Raised by {Webhook.verify} when a payload's signature or timestamp is invalid.
+    class WebhookVerificationError < StandardError; end
+
+    # Raised by {DeliveryMethod} for a message the API cannot send (e.g. one with attachments).
+    class UnsupportedMessageError < ArgumentError; end
+  end
+end