anypost 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65b858025a9f3fda8fb8a21e6c704503e49eaad8f0fcac5913c4a7808524acb5
+  data.tar.gz: 82615f81815ca2da06ae99b3e3a07c8e76eef059ec229c21a1324d5326f75030
+SHA512:
+  metadata.gz: dd83c2564df58e7dcc5c1819833578cd60040e1d25f0b0a2a8542c06968870b3b6615287dacddf95a7e058337a823e66f4394662a4fd26ba3ef20faf90219c7d
+  data.tar.gz: ce4d157c91e82055a0bd191f6ce3cd6bb8505bd8be8dac779f67e3b592f96855b79c9caf82c8250a93eab85b278e862d36eea2b2d23aca98287d83837f4f2f58

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unMTA LLC
+
+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,352 @@
+# Anypost Ruby SDK
+
+The official Ruby gem for the [Anypost](https://anypost.com) email API.
+
+Requires Ruby 3.2+. Built on [Faraday](https://github.com/lostisland/faraday).
+
+## Install
+
+```bash
+gem install anypost
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "anypost"
+```
+
+## Quickstart
+
+```ruby
+require "anypost"
+
+client = Anypost::Client.new("ap_your_api_key")
+
+email = client.email.send(
+  from: "Acme <you@yourdomain.com>",
+  to: ["someone@example.com"],
+  subject: "Hello from Anypost",
+  html: "<p>It worked.</p>"
+)
+
+puts email.id
+```
+
+The constructor also reads `ANYPOST_API_KEY` from the environment:
+
+```ruby
+client = Anypost::Client.new
+```
+
+Keep the key server-side. It is a bearer credential; never ship it to a browser or mobile app.
+
+Request bodies are plain hashes with symbol keys that match the API one-to-one. Responses come back as `Anypost::Response` objects: read fields with either method or bracket syntax (`email.id` or `email[:id]`), and nested objects are themselves responses. Call `email.to_h` for the raw decoded hash.
+
+## Sending
+
+One of `text`, `html`, or `template_id` is required. All recipients in `to`, `cc`, and `bcc` share one envelope and count against a combined limit of 50.
+
+```ruby
+client.email.send(
+  from: "Acme <you@yourdomain.com>",
+  to: ["a@example.com", "b@example.com"],
+  cc: ["team@example.com"],
+  reply_to: "support@yourdomain.com",
+  subject: "Receipt #4823",
+  html: "<p>Thanks for your order.</p>",
+  text: "Thanks for your order.",
+  tags: ["receipt"]
+)
+```
+
+Attachment `content` is the raw file bytes — pass what `File.binread` returns and the SDK base64-encodes it. Do not pre-encode it. The request body is capped at 5 MB.
+
+```ruby
+client.email.send(
+  from: "you@yourdomain.com",
+  to: ["someone@example.com"],
+  subject: "Your report",
+  text: "Attached.",
+  attachments: [
+    {filename: "report.pdf", content: File.binread("report.pdf")}
+  ]
+)
+```
+
+Send with a published template and per-recipient variables:
+
+```ruby
+client.email.send(
+  from: "you@yourdomain.com",
+  to: ["someone@example.com"],
+  template_id: "template_018f2c5e-3a40-7a91-9c25-3a0b1d5e6f78",
+  variables: {name: "Ada", plan: "pro"}
+)
+```
+
+## Batch
+
+Send 1 to 100 independent messages in one request. `defaults` fills any field an entry omits.
+
+```ruby
+result = client.email.send_batch(
+  defaults: {from: "you@yourdomain.com"},
+  emails: [
+    {to: ["a@example.com"], subject: "Hi A", text: "..."},
+    {to: ["b@example.com"], subject: "Hi B", text: "..."}
+  ]
+)
+```
+
+A batch with mixed outcomes returns HTTP `207` and resolves normally. Inspect each entry rather than rescuing an error:
+
+```ruby
+result.summary # { total:, queued:, failed: }
+
+result.data.each do |entry|
+  if entry.status == "queued"
+    puts "#{entry.index} #{entry.id}"
+  else
+    puts "#{entry.index} #{entry.error.type} #{entry.error.message}"
+  end
+end
+```
+
+## Domains
+
+Manage sending domains under `client.domains`. Add a domain, publish the CNAMEs it returns, then verify.
+
+```ruby
+domain = client.domains.create(name: "example.com")
+
+domain.dns_records.each do |record|
+  puts "#{record.type} #{record.name} -> #{record.value}"
+end
+```
+
+`verify` always returns the current domain — a still-`pending` domain does not raise. Read `status` and `verification_failure`, and poll while DNS propagates.
+
+```ruby
+checked = client.domains.verify(domain.id)
+puts checked.verification_failure.code unless checked.status == "verified"
+```
+
+`get`, `update` (tracking config only), and `delete` round out the resource:
+
+```ruby
+client.domains.update(domain.id, tracking: {opens_enabled: true, clicks_enabled: true, subdomain: "track"})
+client.domains.delete(domain.id)
+```
+
+## API keys
+
+Manage keys under `client.api_keys`. The plaintext secret comes back only once, on `create`, as `key`:
+
+```ruby
+created = client.api_keys.create(
+  name: "Production server",
+  permissions: "send_only",
+  allowed_domains: ["example.com"]
+)
+puts created.key # store now; never retrievable again
+
+client.api_keys.update(created.id, name: "Production server", permissions: "full")
+client.api_keys.delete(created.id)
+```
+
+`get` returns metadata only — `key_prefix`, never the secret. Permission and restriction changes take up to 5 minutes to propagate through the gateway cache.
+
+## Templates
+
+Templates use a draft/published model: edits land in a draft, and `publish` promotes it. A template can't be used for sending until it's published.
+
+```ruby
+template = client.templates.create(
+  name: "Welcome email",
+  kind: "html",
+  html: "<h1>Welcome, {{ name }}</h1>"
+)
+
+client.templates.update_draft(template.id, subject: "Welcome to Acme", html: "<h1>Welcome, {{ name }}</h1>")
+client.templates.publish(template.id)
+```
+
+`kind` is `html` or `markdown` and is immutable once set. The plain-text body is always derived server-side. `get_draft`, `delete_draft`, `duplicate`, `get`, `update` (name only), and `delete` round out the resource. Send with a published template via `template_id` (see [Sending](#sending)).
+
+## Suppressions
+
+A suppression blocks sends to an address, scoped to a `topic`. The wildcard `*` blocks every topic; a specific topic (e.g. `marketing`) leaves transactional traffic untouched. Bounces and complaints write `*` automatically.
+
+```ruby
+client.suppressions.create(email: "alice@example.com", topic: "marketing", note: "Customer requested removal")
+
+row = client.suppressions.get("alice@example.com", "*")
+client.suppressions.delete("alice@example.com", "marketing")
+```
+
+`list` accepts `email_contains`, `topic`, `reason`, and `origin` filters. `list_for_email` returns every row for an address across all topics; `delete_for_email` removes them all.
+
+```ruby
+client.suppressions.list(reason: "complaint").each do |s|
+  puts "#{s.email} #{s.topic} #{s.suppressed_at}"
+end
+```
+
+## Webhooks
+
+Manage webhook subscriptions under `client.webhooks`. The `signing_secret` comes back only once, on `create`; later reads return only `signing_secret_prefix`.
+
+```ruby
+webhook = client.webhooks.create(
+  name: "Production events",
+  url: "https://hooks.example.com/anypost",
+  events: ["email.delivered", "email.bounced", "email.complained"]
+)
+puts webhook.signing_secret # store now; never retrievable again
+```
+
+`update` sets the name, URL, events, and `status` together — set `status` to `"disabled"` to pause delivery, `"active"` to resume. `test` sends one synthetic `webhook.test` event and returns the outcome even when the endpoint fails. `rotate_secret` issues a new secret and keeps the previous one valid for a 24-hour grace window; `get`, `list`, and `delete` round out the resource.
+
+```ruby
+result = client.webhooks.test(webhook.id)
+puts "#{result.status_code} #{result.error}" unless result.delivered
+
+rotated = client.webhooks.rotate_secret(webhook.id)
+```
+
+### Verifying deliveries
+
+`Anypost::WebhookSignature.verify` is a module method — it needs the signing secret, not an API key, so call it in your handler without a client. Pass the **raw** request body (the exact bytes, before JSON parsing), the `Anypost-Signature` header, and the secret. It returns on success and raises `Anypost::WebhookVerificationError` otherwise. `Anypost::WebhookSignature.unwrap` does the same and returns the parsed delivery as a `Response`.
+
+```ruby
+begin
+  delivery = Anypost::WebhookSignature.unwrap(raw_body, signature_header, secret)
+  delivery.events.each do |event|
+    # event.type, event.data.email_id, ...
+  end
+rescue Anypost::WebhookVerificationError => e
+  # e.reason: :no_match | :timestamp_out_of_tolerance | ...
+  halt 400
+end
+```
+
+Reach for `verify` when something else has already parsed the body. Keep the raw bytes for the verify step, then use your parsed object once it passes — a Rack-style handler:
+
+```ruby
+post "/anypost" do
+  raw = request.body.read
+  begin
+    Anypost::WebhookSignature.verify(raw, request.env["HTTP_ANYPOST_SIGNATURE"], secret)
+  rescue Anypost::WebhookVerificationError
+    halt 400
+  end
+
+  JSON.parse(raw)["events"].each { |event| handle(event) }
+  status 204
+end
+```
+
+Deliveries older than five minutes are rejected by default to bound replay; pass `tolerance_seconds:` to widen, narrow, or disable (`0`) that check. During a secret rotation the header carries a `v1=` component per active secret, and a match on any one passes — so deliveries keep verifying while you redeploy.
+
+## Events
+
+`client.events.list` pages the team's event stream, newest-first. The window defaults to the last 24 hours and is clamped to your plan's retention. Events are read-only and not addressable by id — there is no `get`.
+
+```ruby
+client.events.list(event_type: "email.bounced").each do |event|
+  puts "#{event.occurred_at} #{event.recipient} #{event.bounce_classification}"
+end
+```
+
+Filter by `start`, `end`, `event_type`, `recipient`, `email_id`, `message_id`, `domain`, `topic`, `campaign`, `template_id`, and `tags`. All filters are exact-match, except `tags`, which takes an array and matches an event carrying *any* of the given tags. A filter value that matches no row returns an empty page. This is also how you backfill the gap after a webhook endpoint was disabled — page the events that occurred during the outage once it's healthy.
+
+```ruby
+# Events tagged "onboarding" OR "welcome", that also bounced.
+page = client.events.list(tags: ["onboarding", "welcome"], event_type: "email.bounced")
+```
+
+## Pagination
+
+List endpoints return a `Page`. Read one page directly, or iterate it to walk every page — the client fetches each one as needed.
+
+```ruby
+page = client.domains.list(limit: 50)
+page.data        # this page's items
+page.has_more    # whether another page exists
+page.next_cursor # pass as :after to fetch it yourself
+
+client.domains.list.each do |domain|
+  puts domain.name # every domain, across all pages
+end
+```
+
+A `Page` is `Enumerable`, so `map`, `select`, `find`, and friends all walk every page.
+
+## Errors
+
+A failed request raises an `Anypost::Error` subclass. Branch on `error.type`, the stable machine-readable code, not on the HTTP status.
+
+```ruby
+begin
+  client.email.send(message)
+rescue Anypost::ValidationError => e
+  e.errors # {"from" => ["The from field is required."]}
+rescue Anypost::RateLimitError => e
+  e.retry_after # seconds, or nil
+rescue Anypost::Error => e
+  "#{e.type} #{e.status} #{e.message}"
+end
+```
+
+| Class | `type` | Status |
+|---|---|---|
+| `ValidationError` | `validation_error` | `400`, `422` |
+| `AuthenticationError` | `authentication_error` | `401` |
+| `PermissionError` | `permission_error` | `403` |
+| `NotFoundError` | `not_found` | `404` |
+| `ConflictError` | `idempotency_concurrent`, `webhook_rotation_in_progress` | `409` |
+| `IdempotencyMismatchError` | `idempotency_mismatch` | `422` |
+| `RateLimitError` | `rate_limit_exceeded` | `429` |
+| `PayloadTooLargeError` | `payload_too_large` | `413` |
+| `APIError` | `internal_error`, `provisioning_error` | `5xx` |
+| `APIConnectionError` | `connection_error` | none |
+
+Every error carries `type`, `status`, `message`, `request_id`, and the parsed `raw` body.
+
+## Retries and idempotency
+
+The client retries `429`, `502`, `503`, and network failures up to `max_retries` times (default 2), with exponential backoff and full jitter. It honors `Retry-After`.
+
+Sends are made safe to retry automatically: when retries are enabled and you do not pass an idempotency key, the client generates one and reuses it across attempts, so a retried send cannot deliver twice. Pass your own key (the second argument) to dedupe across process restarts:
+
+```ruby
+client.email.send(message, order_id)
+client.email.send_batch(batch, idempotency_key)
+```
+
+## Configuration
+
+```ruby
+Anypost::Client.new(
+  "ap_your_api_key",
+  base_url: "https://api.anypost.com/v1",
+  timeout: 30,
+  max_retries: 2,
+  default_headers: {"X-My-Header" => "value"}
+)
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `base_url` | `https://api.anypost.com/v1` | API base URL. |
+| `timeout` | `30` | Per-request timeout, in seconds. |
+| `max_retries` | `2` | Automatic retries for transient failures. |
+| `default_headers` | `{}` | Extra headers sent on every request. |
+| `connection` | a new one | Bring your own Faraday connection. |
+
+The first argument is the API key (`ap_...`); omit it to read `ANYPOST_API_KEY`. `send` and `send_batch` accept a per-call idempotency key as their second argument.
+
+## License
+
+MIT

data/lib/anypost/client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Anypost
+  # Client for the Anypost email API.
+  #
+  #   require "anypost"
+  #
+  #   client = Anypost::Client.new("ap_your_api_key") # or Anypost::Client.new to read ANYPOST_API_KEY
+  #   email = client.email.send(
+  #     from: "Acme <you@yourdomain.com>",
+  #     to: ["someone@example.com"],
+  #     subject: "Hello",
+  #     html: "<p>It worked.</p>"
+  #   )
+  #   email.id
+  class Client
+    DEFAULT_BASE_URL = "https://api.anypost.com/v1"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+
+    # @return [Resources::Email] send operations (`/email`, `/email/batch`)
+    attr_reader :email
+    # @return [Resources::Domains] sending-domain operations (`/domains`)
+    attr_reader :domains
+    # @return [Resources::ApiKeys] API-key operations (`/api-keys`)
+    attr_reader :api_keys
+    # @return [Resources::Templates] template operations, including draft/publish
+    attr_reader :templates
+    # @return [Resources::Suppressions] suppression-list operations (`/suppressions`)
+    attr_reader :suppressions
+    # @return [Resources::Webhooks] webhook operations, including test and rotation
+    attr_reader :webhooks
+    # @return [Resources::Events] read access to the event stream (`/events`)
+    attr_reader :events
+
+    # @param api_key [String, nil] defaults to the ANYPOST_API_KEY environment variable
+    def initialize(api_key = nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES, default_headers: {}, connection: nil, sleeper: nil, jitter: nil)
+      key = api_key
+      key = ENV["ANYPOST_API_KEY"] if key.nil? || key.empty?
+      if key.nil? || key.empty?
+        raise ArgumentError,
+          "An Anypost API key is required. Pass it to the constructor or set ANYPOST_API_KEY."
+      end
+
+      http = HttpClient.new(
+        api_key: key,
+        base_url: base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        default_headers: default_headers,
+        connection: connection,
+        sleeper: sleeper,
+        jitter: jitter
+      )
+
+      @email = Resources::Email.new(http)
+      @domains = Resources::Domains.new(http)
+      @api_keys = Resources::ApiKeys.new(http)
+      @templates = Resources::Templates.new(http)
+      @suppressions = Resources::Suppressions.new(http)
+      @webhooks = Resources::Webhooks.new(http)
+      @events = Resources::Events.new(http)
+      @identity = Resources::Identity.new(http)
+    end
+
+    # Identify the team and permission level behind the current API key.
+    def whoami
+      @identity.whoami
+    end
+  end
+end

data/lib/anypost/errors.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Anypost
+  # Base class for every error raised by the SDK.
+  #
+  # Branch on {#type} (the stable, machine-readable code) rather than on the
+  # HTTP status or the message text.
+  class Error < StandardError
+    # @return [String] stable, machine-readable error type
+    attr_reader :type
+    # @return [Integer, nil] HTTP status, or nil when no response was received
+    attr_reader :status
+    # @return [String, nil] request id from the response, when present
+    attr_reader :request_id
+    # @return [Object] the parsed response body, or the underlying cause
+    attr_reader :raw
+
+    def initialize(message, type:, status: nil, request_id: nil, raw: nil)
+      super(message)
+      @type = type
+      @status = status
+      @request_id = request_id
+      @raw = raw
+    end
+  end
+
+  # 400/422 — the request body or query failed validation.
+  class ValidationError < Error
+    # @return [Hash{String => Array<String>}] field path -> list of problems
+    attr_reader :errors
+
+    def initialize(message, errors: {}, **kwargs)
+      super(message, **kwargs)
+      @errors = errors || {}
+    end
+  end
+
+  # 401 — the API key is missing or invalid.
+  class AuthenticationError < Error; end
+
+  # 403 — the key may not perform this action.
+  class PermissionError < Error; end
+
+  # 404 — no such resource for this team.
+  class NotFoundError < Error; end
+
+  # 409 — conflict, idempotency_concurrent, or webhook_rotation_in_progress.
+  class ConflictError < Error; end
+
+  # 422 idempotency_mismatch — a key was reused with a different body.
+  class IdempotencyMismatchError < Error; end
+
+  # 429 — a rate limit was exceeded.
+  class RateLimitError < Error
+    # @return [Float, nil] parsed Retry-After, in seconds, when the server sent one
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  # 413 — the request body exceeded the 5 MB gateway limit.
+  class PayloadTooLargeError < Error; end
+
+  # A server error (5xx), including internal_error and provisioning_error.
+  class APIError < Error; end
+
+  # No HTTP response was received (network failure, timeout, or abort).
+  class APIConnectionError < Error
+    def initialize(message, cause: nil)
+      super(message, type: "connection_error", raw: cause)
+    end
+  end
+
+  # Maps an HTTP response into the right {Error} subclass. Keys primarily on the
+  # canonical `error.type`, falling back to the HTTP status.
+  #
+  # @api private
+  module Errors
+    REQUEST_ID_HEADERS = ["anypost-request-id", "x-anypost-request-id", "x-request-id"].freeze
+
+    module_function
+
+    def from_response(status, body, headers)
+      request_id = read_request_id(headers)
+      envelope = body.is_a?(Hash) ? body : {}
+      error = envelope["error"]
+
+      errors = {}
+      case error
+      when Hash
+        # Canonical envelope: { error: { type, message, errors? } }.
+        type = error["type"] || type_from_status(status)
+        message = error["message"] || default_message(status)
+        errors = error["errors"] if error["errors"].is_a?(Hash)
+      when String
+        # Flat envelope: { error: "<code>", message? }.
+        type = error
+        message = envelope["message"] || error.tr("_", " ")
+      else
+        type = type_from_status(status)
+        message = default_message(status)
+      end
+
+      build(status, type, message, errors || {}, request_id, body, headers)
+    end
+
+    # Parse a Retry-After header (delta-seconds or HTTP-date) into seconds.
+    def retry_after_seconds(headers)
+      value = header(headers, "retry-after")
+      return nil if value.nil? || value.empty?
+      return [value.to_f, 0.0].max if /\A\s*\d+(\.\d+)?\s*\z/.match?(value)
+
+      begin
+        target = Time.httpdate(value)
+      rescue ArgumentError
+        return nil
+      end
+      [target.to_f - Time.now.to_f, 0.0].max
+    end
+
+    def build(status, type, message, errors, request_id, raw, headers)
+      common = {status: status, request_id: request_id, raw: raw}
+      case type
+      when "validation_error"
+        ValidationError.new(message, errors: errors, type: type, **common)
+      when "authentication_error"
+        AuthenticationError.new(message, type: type, **common)
+      when "permission_error"
+        PermissionError.new(message, type: type, **common)
+      when "not_found"
+        NotFoundError.new(message, type: type, **common)
+      when "conflict", "idempotency_concurrent", "webhook_rotation_in_progress"
+        ConflictError.new(message, type: type, **common)
+      when "idempotency_mismatch"
+        IdempotencyMismatchError.new(message, type: type, **common)
+      when "rate_limit_exceeded"
+        RateLimitError.new(message, retry_after: retry_after_seconds(headers), type: type, **common)
+      when "payload_too_large"
+        PayloadTooLargeError.new(message, type: type, **common)
+      when "provisioning_error", "internal_error"
+        APIError.new(message, type: type, **common)
+      else
+        by_status(status, type, message, errors, headers, common)
+      end
+    end
+
+    def by_status(status, type, message, errors, headers, common)
+      case status
+      when 401 then AuthenticationError.new(message, type: type, **common)
+      when 403 then PermissionError.new(message, type: type, **common)
+      when 404 then NotFoundError.new(message, type: type, **common)
+      when 409 then ConflictError.new(message, type: type, **common)
+      when 413 then PayloadTooLargeError.new(message, type: type, **common)
+      when 429 then RateLimitError.new(message, retry_after: retry_after_seconds(headers), type: type, **common)
+      when 400, 422 then ValidationError.new(message, errors: errors, type: type, **common)
+      else
+        (status >= 500) ? APIError.new(message, type: type, **common) : Error.new(message, type: type, **common)
+      end
+    end
+
+    def type_from_status(status)
+      case status
+      when 400, 422 then "validation_error"
+      when 401 then "authentication_error"
+      when 403 then "permission_error"
+      when 404 then "not_found"
+      when 409 then "conflict"
+      when 413 then "payload_too_large"
+      when 429 then "rate_limit_exceeded"
+      else
+        (status >= 500) ? "internal_error" : "api_error"
+      end
+    end
+
+    def default_message(status)
+      "Anypost request failed with status #{status}."
+    end
+
+    def read_request_id(headers)
+      REQUEST_ID_HEADERS.each do |name|
+        value = header(headers, name)
+        return value if value && !value.empty?
+      end
+      nil
+    end
+
+    # Case-insensitive single-value header lookup over a Hash or Faraday headers.
+    def header(headers, name)
+      return nil if headers.nil?
+
+      name = name.downcase
+      headers.each do |key, value|
+        return value if key.to_s.downcase == name
+      end
+      nil
+    end
+  end
+end