mailtea 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b4a24f347aac9fc071ff85740ed202b8469d388c41d088fe5a63deab3295d52c
+  data.tar.gz: 11722976c96f5b69ee607f50f33658fe95ba262d0675942fd9d914f01772fc66
+SHA512:
+  metadata.gz: 664a1e7747c2e1ce0d2f25b84c54a485f8ac58246cfb2c8cff8cfe60b32e2c31ee32ca19373d73599a3e1d8eb65fa13207c009406dbffdb510fd3e16899e34b3
+  data.tar.gz: 60f69633ac8f6c5fc8ec8e7d8f7f6e494c9a366820f0ea6408936c32631dd4f0d1a46cc1913288b8d85e8a248e498335e95f4b43d87b9bd6306008b5e8656b5d

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to the `mailtea` Ruby gem are documented here.
+
+## Unreleased
+
+- Added: `mailtea.domains.update(id, tracking_subdomain: nil)` removes a
+  tracking subdomain. The domain's links go back to being served from the
+  Mailtea host. Links in mail you have already sent point at the old hostname
+  and stop resolving — there is no way to reinstate them. Only the query string
+  drops nils, so the removal travels in the body as an explicit null; leaving
+  the key out and passing nil are different requests. An empty string is
+  neither: it is refused with `tracking_subdomain_invalid`.
+- Changed: the `MX` row in `records` now reports what the last verify found,
+  instead of reading `pending` on every request but the verify itself. A domain
+  nobody has verified reads `not_started`.
+
+## 0.2.0 (2026-09-03)
+
+- Added: the domain claims resource — `mailtea.domains.claims.create`, `.get`,
+  `.verify` and `.cancel`. When adding a domain is refused because the host is
+  connected to another publication, publish one TXT record to prove you control
+  its DNS and the domain moves to you.
+- Documented: domains take `region` (fixed at creation), `tls` and
+  `tracking_subdomain` on create, and the list filters on `region` and `status`.
+  This SDK forwards whatever parameters you pass, so these worked already — this
+  release is where they are stated and covered by tests.
+
+## 0.1.0 (2026-08-27)
+
+First release. A thin, zero-dependency wrapper over the
+[Mailtea REST API](https://docs.mailtea.app/docs/api-reference), built on
+`net/http` and `json` from the standard library. Ruby 3.0+.
+
+### Added
+
+- **`Mailtea::Client`** — reads `MAILTEA_API_KEY` and the optional
+  `MAILTEA_API_BASE_URL`, or takes both explicitly. The HTTP transport is
+  injectable, so tests need no network and an app can route requests through its
+  own instrumented stack.
+
+- **Transactional email.** `emails.send`, `batch`, `get`, `list`, `analytics`,
+  `update`, `reschedule` and `cancel` — plus `emails.inbound` for received mail
+  (`list`, `get`, `reply`, and `attachments.list` / `attachments.get`).
+  `emails.get` adds a `status` alias of the wire's `last_event`. The API caps a
+  message at 50 recipients combined across `to`, `cc` and `bcc`.
+
+- **Audience.** `contacts` (`create`/`upsert`, `list`, `get`, `update`,
+  `delete`), `segments`, `topics`, `senders`, `suppressions` (including
+  `export`, which returns raw CSV text), and `contact_properties`.
+
+- **Content.** `posts` (`create`, `send`, `send_test`, `list`, `get`, `update`,
+  `delete`), `templates` (including `render`, `publish`/`unpublish`, `versions`,
+  `restore_version` and `duplicate`), and `assets` for the publication's image
+  library — raw bytes are base64-encoded for you.
+
+- **Platform.** `domains` (+ `domains.tracking`), `webhooks`, `api_keys`,
+  `automations`, `automation_runs`, `events` and `event_definitions`.
+
+- **`Mailtea.verify_webhook_signature` / `Mailtea.sign_webhook`** — Standard
+  Webhooks verification with replay protection and a constant-time compare,
+  checked in the test suite against signatures produced by the platform's own
+  TypeScript signer.
+
+- **`Mailtea::Error`** on every failure, carrying `status` (0 for a client-side
+  fault such as an unreachable API), `message`, `code`, `details` and
+  `request_id`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailtea
+
+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,234 @@
+# mailtea-ruby
+
+The official Ruby SDK for [Mailtea](https://mailtea.app) — a thin, typed wrapper
+over the [REST API](https://docs.mailtea.app/docs/api-reference). Ruby 3.0+, no
+runtime dependencies.
+
+## Install
+
+```bash
+gem install mailtea
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "mailtea", "~> 0.1"
+```
+
+## Usage
+
+```ruby
+require "mailtea"
+
+mailtea = Mailtea::Client.new # reads MAILTEA_API_KEY
+
+sent = mailtea.emails.send(
+  from: "you@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Hello from Mailtea",
+  html: "<p>Your first email, sent with <strong>Mailtea</strong>.</p>"
+)
+puts sent["id"]
+
+email = mailtea.emails.get(sent["id"])
+puts email["status"] # "queued" right after a send; delivery is asynchronous
+```
+
+Responses are the wire JSON as a Hash that also takes Symbol keys, so
+`email["id"]` and `email[:id]` are the same lookup. Keys are never renamed: what
+the API reference documents is what you index.
+
+The documented fields of a request are named keyword arguments; anything else
+the API accepts can be passed as an extra keyword, or as a leading wire-format
+Hash, and both styles can be mixed:
+
+```ruby
+mailtea.emails.send({ "from" => "you@yourdomain.com", "subject" => "Hello" },
+                    to: "recipient@example.com",
+                    html: "<p>Hi</p>")
+```
+
+Named keywords cover `emails.send` / `batch` / `update`, `contacts.create` /
+`update`, `posts.create` / `send` / `send_test`, `topics.create` and
+`emails.inbound.reply`. Every other method takes the Hash-or-keywords form for
+the whole payload — the API reference is the field list.
+
+A keyword you do not pass is left out of the request; one you pass as `nil` is
+sent as JSON `null`, which is how the API clears a nullable field:
+
+```ruby
+mailtea.segments.update(id, publication_id: pub)                      # leaves the filter alone
+mailtea.segments.update(id, publication_id: pub, status_filter: nil)  # clears it
+```
+
+`emails.send` also takes `tags`, custom `headers`, `attachments` and
+`scheduled_at`. Attachments carry base64 `content`; set a `content_id` (plus
+`content_type`) to embed an inline image referenced by `cid:` in the HTML:
+
+```ruby
+mailtea.emails.send(
+  from: "you@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Your receipt",
+  html: '<p>Thanks!</p><img src="cid:logo" />',
+  tags: [{ name: "category", value: "receipt" }],
+  attachments: [
+    { filename: "receipt.pdf", content: pdf_base64 },
+    { filename: "logo.png", content: logo_base64,
+      content_type: "image/png", content_id: "logo" } # inline
+  ]
+)
+```
+
+`to`, `cc`, `bcc` and `reply_to` each take a single address or an Array. The API
+caps a message at **50 recipients combined** across `to` + `cc` + `bcc`.
+
+## Configuration
+
+| What | How |
+|---|---|
+| API key | `Mailtea::Client.new("mt_pat_…")`, or the `MAILTEA_API_KEY` environment variable |
+| Base URL | `Mailtea::Client.new(key, base_url: "…")`, or `MAILTEA_API_BASE_URL`. Defaults to `https://api.mailtea.app` |
+| HTTP transport | `Mailtea::Client.new(key, transport: my_transport)` |
+
+```bash
+export MAILTEA_API_KEY="mt_pat_xxxxxxxx"
+export MAILTEA_API_BASE_URL="http://127.0.0.1:7787"  # self-hosted or local only
+```
+
+A transport is anything that responds to
+`call(method, url, headers, body) -> Mailtea::HttpResponse`. Pass one to record
+requests in tests, route through a proxy, or reuse a connection pool —
+everything above the wire stays the same:
+
+```ruby
+recorder = lambda do |method, url, headers, body|
+  puts "#{method} #{url}"
+  Mailtea::Transport.call(method, url, headers, body)
+end
+
+mailtea = Mailtea::Client.new(ENV["MAILTEA_API_KEY"], transport: recorder)
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `emails.send(params)` | Send a transactional email → `{ "id" => … }` |
+| `emails.batch(emails)` | Send up to 100 emails → `{ "data" => [{ "id" => … }] }` |
+| `emails.get(id)` | Retrieve an email and its delivery status |
+| `emails.list(params = nil)` | List emails → `{ "data", "total", "limit", "offset", "has_more" }` |
+| `emails.update(id, params)` | Reschedule a scheduled email |
+| `emails.reschedule(id, scheduled_at)` | Convenience wrapper over `update` |
+| `emails.cancel(id)` | Cancel a scheduled email (`POST /v1/emails/:id/cancel`) |
+| `emails.analytics(params = nil)` | Aggregate transactional metrics over an optional date window |
+| `emails.inbound.list(params = nil)` | List received emails in a publication (cursor-paginated) |
+| `emails.inbound.get(id)` | Retrieve a received email with body, headers and attachments |
+| `emails.inbound.reply(id, params)` | Reply to a received email (threads by construction) |
+| `emails.inbound.attachments.list(id)` | List a received email's attachments (signed download URLs) |
+| `emails.inbound.attachments.get(id, attachment_id)` | Retrieve one inbound attachment |
+| `contacts.create / upsert / list / get / update / delete` | Manage audience contacts (`upsert` = `create`; the endpoint upserts) |
+| `posts.create(params)` | Create a newsletter post (draft, or `send: true`) → `{ "id" => … }` |
+| `posts.send(id, params = nil)` | Send a draft post to the audience, now or at `scheduled_at` |
+| `posts.send_test(id, params)` | Send a `[TEST]` copy of a post → `{ "sent_to", "failed_to" }` |
+| `posts.list / get / update / delete` | Manage posts (offset-paginated list) |
+| `segments.create / list / get / update / delete` | Manage audience segments |
+| `topics.create / list / get / update / delete` | Manage topic definitions (`visibility: "public"` → shown on the reader preference page) |
+| `senders.create / list / get / update / delete` | Manage named From identities (`email` immutable) |
+| `templates.create / list / get / update / publish / unpublish / duplicate / delete` | Manage reusable email templates |
+| `templates.render(params)` | Render a spec to HTML without saving → `{ "html", "text" }` |
+| `templates.versions(id, params = nil)` | List a template's design history, newest first (metadata only) |
+| `templates.restore_version(id, version, params = nil)` | Put an older design back — a content write, so the template returns to **draft** |
+| `assets.upload / list / delete` | The publication's image library (raw bytes are base64-encoded for you) |
+| `suppressions.list / add / remove` | Manage the team-wide do-not-send list |
+| `suppressions.export` | Export the whole suppression list as CSV (raw text) |
+| `domains.create / list / get / verify / update / delete` | Manage sending domains (add, read DNS records, verify) |
+| `domains.tracking.create / list / verify / delete` | Manage CNAME tracking sub-domains under a domain |
+| `webhooks.create / list / get / update / delete` | Manage outbound event subscriptions |
+| `contact_properties.create / list / update / delete` | Manage custom contact fields (team-scoped) |
+| `api_keys.create / list / revoke` | Manage API keys (`settings:write`) |
+| `automations.create / list / get / update / delete` | Manage automation graphs (`steps` + optional `connections`) |
+| `automations.validate(params)` | Dry-run a graph → `{ "valid", "issues" }` (no automation needed) |
+| `automations.activate / pause / archive` | Lifecycle (`cancel_runs` defaults **false** on pause, **true** on archive) |
+| `automations.versions(id, …)` / `automations.version(id, version, …)` | List stored versions; retrieve one with its graph |
+| `automations.metrics(id, params = nil)` | Per-step funnel counts and branch splits (test runs excluded) |
+| `automations.test(id, params)` | One test run against a real contact — **sends real, billed email** |
+| `automation_runs.list / get / cancel` | Inspect and cancel runs (a run pins the version it started on) |
+| `events.send(params)` | Record a custom event → `{ "enrolled_automations", "resumed_runs" }` |
+| `events.list(params)` | List recorded events (cursor-paginated) |
+| `event_definitions.create / list / get / update / delete` | Manage the event catalog (`name` immutable) |
+
+Audience, content and platform resources are scoped to a publication — pass
+`publication_id`. `suppressions` and `contact_properties` are team-scoped and
+take none.
+
+`emails.send`, `posts.send` and `events.send` deliberately shadow `Object#send`
+on their resource object, because the API's verb is "send". Ruby's `__send__`
+is untouched, so metaprogramming still works.
+
+## Webhooks
+
+Mailtea signs every outbound webhook with
+[Standard Webhooks](https://www.standardwebhooks.com/).
+`Mailtea.verify_webhook_signature` checks the signature and rejects replays.
+Pass the **raw** request body (not re-serialized JSON) and the endpoint's
+`whsec_…` signing secret:
+
+```ruby
+ok = Mailtea.verify_webhook_signature(
+  signing_secret,                        # whsec_… from webhooks.create
+  request.headers["webhook-id"],
+  request.headers["webhook-timestamp"],
+  request.raw_post,                      # exact bytes received
+  request.headers["webhook-signature"]
+)
+head :unauthorized unless ok
+```
+
+The timestamp window defaults to 5 minutes each way and both it and the clock
+are injectable: `tolerance_seconds:` and `now:`.
+`Mailtea.sign_webhook(secret, msg_id, timestamp, payload)` produces the same
+header, which is how you fake a delivery in your own tests.
+
+## Errors
+
+Every failure raises `Mailtea::Error` — an API error and a dropped connection
+alike, so one `rescue` covers the send path:
+
+```ruby
+begin
+  mailtea.emails.send(from: from, to: to, subject: "Hi", html: "<p>Hi</p>")
+rescue Mailtea::Error => e
+  warn e.message   # the API's own message, e.g. "Domain not verified"
+  e.status         # 422 — or 0 when the request never left the process
+  e.code           # machine-readable code, when the API sends one
+  e.details        # validation issues, when the API sends them
+  e.request_id     # the x-request-id header; quote it in support tickets
+end
+```
+
+`status` is `0` for a client-side fault: a missing API key, an unreachable host,
+a timeout. Branch on `code` rather than the message — copy changes, codes do not.
+
+## Local development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+The tests run against a bundled mock API on an ephemeral port
+(`test/mock_mailtea.rb`), so they need no credentials and make no network calls.
+
+To run against a local Mailtea instead:
+
+```bash
+export MAILTEA_API_KEY="mt_pat_…"
+export MAILTEA_API_BASE_URL="http://127.0.0.1:7787"
+ruby -Ilib -e 'require "mailtea"; p Mailtea::Client.new.emails.list(limit: 1)'
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mailtea/api_keys.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +api_keys+ resource. Reach it at <tt>mailtea.api_keys</tt>.
+  #
+  # Requires a token with +settings:write+. A key can never be granted scopes the
+  # calling token does not already hold.
+  class ApiKeys < Resource
+    # Create an API key. The +token+ is returned ONCE — store it securely.
+    #
+    # Takes +name+, optional +permission+ ("full_access" or "sending_access"),
+    # and optional +domain_id+.
+    def create(params = nil, **fields)
+      request("POST", "/v1/api-keys", payload(params, fields))
+    end
+
+    # List API keys (token values are never returned).
+    def list
+      request("GET", "/v1/api-keys")
+    end
+
+    # Revoke (delete) an API key by id.
+    def revoke(id)
+      request("DELETE", "/v1/api-keys/" + escape(id))
+    end
+  end
+end

data/lib/mailtea/assets.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +assets+ resource (a publication's image library). Reach it at
+  # <tt>mailtea.assets</tt>.
+  #
+  # An email or site image needs an absolute URL, so this is how a picture that
+  # is not already in the library gets into one. Pointing an image at a host you
+  # do not control breaks the day that host moves the file.
+  #
+  # PNG, JPEG, GIF, WebP or SVG, 5 MB per image. The bytes are checked against
+  # the declared +content_type+, so a mislabelled file is rejected rather than
+  # stored. SVG is served with <tt>Content-Security-Policy: sandbox</tt>, which
+  # is what makes hosting one from the publication's own domain safe.
+  #
+  #   asset = mailtea.assets.upload(
+  #     publication_id: "pub_123",
+  #     content: File.binread("hero.png"),   # base64-encoded for you
+  #     content_type: "image/png",
+  #     filename: "hero.png"
+  #   )
+  #   asset["url"]  # -> use as an image block's src
+  class Assets < Resource
+    # Upload an image. Takes +publication_id+, +content+, +content_type+ and
+    # +filename+.
+    #
+    # +content+ takes raw bytes — read the file with File.binread — and is
+    # base64-encoded for you, or a String you already encoded, which is sent
+    # untouched.
+    def upload(params = nil, **fields)
+      body = payload(params, fields)
+      content = body["content"]
+      body["content"] = [content].pack("m0") if content.is_a?(String) && raw_bytes?(content)
+      request("POST", "/v1/assets", body)
+    end
+
+    # List the library, newest first. Filters: +publication_id+ (required),
+    # +search+ (file name), +limit+ (1-200, default 100).
+    def list(params = nil, **filters)
+      request("GET", "/v1/assets" + query(payload(params, filters)))
+    end
+
+    # Retire an asset.
+    #
+    # The stored file is KEPT and its URL keeps resolving, so images inside
+    # already-sent emails do not break. This hides the asset from the library —
+    # it does not remove it from any email, template or page referencing it.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/assets/" + escape(id) + query(payload(params, filters)))
+    end
+
+    private
+
+    # Ruby has no separate bytes type, so image bytes and an already-encoded
+    # string are both Strings, and the encoding is what tells them apart:
+    # File.binread returns ASCII-8BIT, a base64 string is ordinary text.
+    #
+    # This reads the label rather than sniffing the contents. Sniffing cannot
+    # settle it — an SVG read as text is valid UTF-8 and is not base64, so any
+    # rule loose enough to catch it also catches short base64 and encodes it
+    # twice, uploading gibberish of exactly the right content type. Reading
+    # image files with File.binread keeps both cases unambiguous.
+    def raw_bytes?(content)
+      content.encoding == Encoding::BINARY || !content.valid_encoding?
+    end
+  end
+end

data/lib/mailtea/automation_runs.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +automation_runs+ resource (one contact's journey through one
+  # automation). Reach it at <tt>mailtea.automation_runs</tt>.
+  #
+  # Runs are nested under an automation and scoped to a publication — pass
+  # +automation_id+ and +publication_id+. A run PINS the automation version it
+  # started on, so #get returns the graph the run is actually executing, not the
+  # live one.
+  class AutomationRuns < Resource
+    # List an automation's runs (cursor-paginated). Filters: +publication_id+
+    # (required), +status+ (one or more run statuses — pass an Array and it is
+    # joined for you), +contact_id+, +is_test+, +limit+, +after+. List items omit
+    # the pinned graph and the step runs; use #get for those.
+    def list(automation_id, params = nil, **filters)
+      merged = payload(params, filters)
+      status = merged["status"]
+      merged["status"] = status.join(",") if status.is_a?(Array)
+      request("GET", "/v1/automations/" + escape(automation_id) + "/runs" + query(merged))
+    end
+
+    # Retrieve one run in full. Requires +publication_id+. Returns the PINNED
+    # +steps+/+connections+, the per-step +step_runs+, and +waiting+
+    # (+resume_at+ / +waiting_event_name+) — read this rather than an event
+    # ingest's +resumed_runs+ counter to tell whether an event actually advanced
+    # the run.
+    def get(automation_id, run_id, params = nil, **filters)
+      request(
+        "GET",
+        "/v1/automations/" + escape(automation_id) + "/runs/" + escape(run_id) +
+          query(payload(params, filters))
+      )
+    end
+
+    # Cancel one in-flight run. Requires +publication_id+. A cancelled run cannot
+    # be resumed. Returns the run in full detail.
+    def cancel(automation_id, run_id, params = nil, **filters)
+      request(
+        "POST",
+        "/v1/automations/" + escape(automation_id) + "/runs/" + escape(run_id) + "/cancel" +
+          query(payload(params, filters))
+      )
+    end
+  end
+end

data/lib/mailtea/automations.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +automations+ resource (multi-step contact journeys). Reach it at
+  # <tt>mailtea.automations</tt>.
+  #
+  # Automations are scoped to a publication — pass +publication_id+. An
+  # automation is a graph: +steps+ (each <tt>{ key:, type:, label:, config: }</tt>)
+  # plus optional +connections+ (each <tt>{ from:, to:, branch: }</tt>).
+  #
+  # +connections+ is optional: omit it and the server links the steps in array
+  # order with <tt>branch: "next"</tt>, rooted at the trigger. A graph containing
+  # a +condition+ or +wait_for_event+ step cannot be inferred that way and is
+  # rejected with +connections_required_for_branching+ — send its connections
+  # explicitly.
+  #
+  # Failures come back as coded +issues+ rather than schema errors, and for a
+  # draft/paused/archived automation they ride along informationally instead of
+  # blocking the save.
+  class Automations < Resource
+    # Dry-run a graph without creating anything. Takes +publication_id+ and
+    # +steps+, plus optional +connections+. Returns
+    # <tt>{ "object" => "automation_validation", "valid" => ..., "issues" => [...] }</tt>.
+    def validate(params = nil, **fields)
+      request("POST", "/v1/automations/validate", payload(params, fields))
+    end
+
+    # Create an automation. Takes +publication_id+, +name+ and +steps+, plus
+    # optional +description+, +connections+, +reentry_policy+
+    # ("once"/"once_per_window"/"always" — "once_per_window" requires
+    # +reentry_window_seconds+), +on_step_failure+ and +validate_only+. With
+    # <tt>validate_only: true</tt> nothing is written and an
+    # +automation_validation+ is returned instead. New automations start as
+    # +draft+ — #activate starts them.
+    def create(params = nil, **fields)
+      request("POST", "/v1/automations", payload(params, fields))
+    end
+
+    # List automations (cursor-paginated). Filters: +publication_id+ (required),
+    # +status+ ("draft"/"active"/"paused"/"archived"), +limit+, +after+. List
+    # items omit +steps+, +connections+, +valid+ and +issues+ — use #get for the
+    # full graph.
+    def list(params = nil, **filters)
+      request("GET", "/v1/automations" + query(payload(params, filters)))
+    end
+
+    # Retrieve one automation with its live graph and current +issues+.
+    # Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/automations/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update an automation's +name+, +description+, +steps+, +connections+,
+    # +reentry_policy+, +reentry_window_seconds+ or +on_step_failure+.
+    # +publication_id+ is required and goes in the query string. The graph is
+    # replaced wholesale and cuts a new version.
+    #
+    # <tt>validate_only: true</tt> returns an +automation_validation+ and writes
+    # nothing. A graph change that carries errors saves anyway while the
+    # automation is draft/paused/archived; on an +active+ one it is a 422 —
+    # pause, save, then start again.
+    def update(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields), keep_in_body: false)
+      request("PATCH", "/v1/automations/" + escape(id) + scope, body)
+    end
+
+    # Delete an automation. Requires +publication_id+. Deleting an +active+
+    # automation is a 409 +automation_active+ — pause or archive it first so its
+    # in-flight runs are not dropped silently.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/automations/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Start the automation so new contacts enroll. Requires +publication_id+. A
+    # graph with errors is refused with 422 +automation_invalid+ and the
+    # blocking +issues+.
+    def activate(id, params = nil, **filters)
+      request("POST", "/v1/automations/" + escape(id) + "/activate" + query(payload(params, filters)))
+    end
+
+    # Stop new enrollments. Requires +publication_id+ (query). Optional
+    # +cancel_runs+ — it *defaults to false* here, so in-flight runs keep going;
+    # pass <tt>cancel_runs: true</tt> to exit them. Returns the automation plus
+    # +canceled_runs+.
+    def pause(id, params = nil, **fields)
+      lifecycle(id, "/pause", payload(params, fields))
+    end
+
+    # Archive the automation. Requires +publication_id+ (query). Optional
+    # +cancel_runs+ — it *defaults to true* here (the opposite of #pause), so
+    # in-flight runs exit with +automation_archived+. Returns the automation plus
+    # +canceled_runs+.
+    def archive(id, params = nil, **fields)
+      lifecycle(id, "/archive", payload(params, fields))
+    end
+
+    # List an automation's versions (cursor-paginated). Filters:
+    # +publication_id+ (required), +limit+, +after+. List items carry no
+    # +steps+/+connections+ — use #version for a stored graph.
+    def versions(id, params = nil, **filters)
+      request("GET", "/v1/automations/" + escape(id) + "/versions" + query(payload(params, filters)))
+    end
+
+    # Retrieve one stored version, including its +steps+ and +connections+.
+    # Requires +publication_id+. This is the graph a run of that version is
+    # pinned to — editing the automation never rewrites it.
+    def version(id, version, params = nil, **filters)
+      request(
+        "GET",
+        "/v1/automations/" + escape(id) + "/versions/" + escape(version) +
+          query(payload(params, filters))
+      )
+    end
+
+    # Per-step funnel counts for an automation. Filters: +publication_id+
+    # (required), +version+ (omit to aggregate across ALL versions), +since+,
+    # +until+ (ISO 8601). Test runs are always excluded
+    # (<tt>excludes_test_runs: true</tt>). Condition steps report
+    # <tt>branches: { condition_met, condition_not_met }</tt>, +wait_for_event+
+    # steps <tt>{ event_received, timeout }</tt>.
+    def metrics(id, params = nil, **filters)
+      request("GET", "/v1/automations/" + escape(id) + "/metrics" + query(payload(params, filters)))
+    end
+
+    # Run the automation once against a real contact. +publication_id+ is
+    # required and goes in the query string; the body takes one of +contact_id+
+    # or +email+, plus optional +event_properties+ to seed the run's +event.*+
+    # namespace.
+    #
+    # A test run *sends real, billed email* to that inbox — it does not bypass
+    # any send gate. It is flagged +is_test+ and excluded from #metrics. Returns
+    # 202 with the queued run.
+    def test(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields), keep_in_body: false)
+      request("POST", "/v1/automations/" + escape(id) + "/test" + scope, body)
+    end
+
+    private
+
+    # +publication_id+ goes in the query but +cancel_runs+ is read from the body,
+    # so the two are split here. No body is sent when the caller omitted
+    # +cancel_runs+ — or passed it as +nil+, which the server's schema would
+    # reject — so the per-verb default applies in both cases.
+    def lifecycle(id, suffix, merged)
+      cancel_runs = merged["cancel_runs"]
+      body = cancel_runs.nil? ? nil : { "cancel_runs" => cancel_runs }
+      request(
+        "POST",
+        "/v1/automations/" + escape(id) + suffix +
+          query({ "publication_id" => merged["publication_id"] }),
+        body
+      )
+    end
+  end
+end