mailtea 0.2.0

data/lib/mailtea/client.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "api_keys"
+require_relative "assets"
+require_relative "automation_runs"
+require_relative "automations"
+require_relative "contact_properties"
+require_relative "contacts"
+require_relative "domains"
+require_relative "emails"
+require_relative "error"
+require_relative "events"
+require_relative "posts"
+require_relative "response"
+require_relative "segments"
+require_relative "senders"
+require_relative "suppressions"
+require_relative "templates"
+require_relative "topics"
+require_relative "transport"
+require_relative "version"
+require_relative "webhooks"
+
+module Mailtea
+  DEFAULT_BASE_URL = "https://api.mailtea.app"
+
+  # The Mailtea client.
+  #
+  #   require "mailtea"
+  #
+  #   mailtea = Mailtea::Client.new            # reads MAILTEA_API_KEY
+  #   sent = mailtea.emails.send(
+  #     from: "you@yourdomain.com",
+  #     to: "recipient@example.com",
+  #     subject: "Hello",
+  #     html: "<p>Sent with Mailtea.</p>"
+  #   )
+  #   sent["id"]
+  #
+  # The API key may be passed explicitly or read from +MAILTEA_API_KEY+.
+  # Self-hosting or local dev: pass +base_url+ or set +MAILTEA_API_BASE_URL+.
+  class Client
+    # Transactional email: send, batch, status, scheduling, inbound.
+    attr_reader :emails
+    # Audience contacts.
+    attr_reader :contacts
+    # Newsletter posts/issues.
+    attr_reader :posts
+    # Audience segments.
+    attr_reader :segments
+    # Named From identities.
+    attr_reader :senders
+    # The publication's image library.
+    attr_reader :assets
+    # The team-wide do-not-send list.
+    attr_reader :suppressions
+    # Topic definitions.
+    attr_reader :topics
+    # Reusable server-side email templates.
+    attr_reader :templates
+    # Sending domains, their tracking sub-domains, and claims on domains held by other teams.
+    attr_reader :domains
+    # Outbound event subscriptions.
+    attr_reader :webhooks
+    # Custom contact fields (team-scoped).
+    attr_reader :contact_properties
+    # API keys.
+    attr_reader :api_keys
+    # Multi-step contact journeys.
+    attr_reader :automations
+    # One contact's journey through one automation.
+    attr_reader :automation_runs
+    # Custom product events.
+    attr_reader :events
+    # The catalog of event names a publication expects.
+    attr_reader :event_definitions
+
+    # The base URL every request is built on, with any trailing slash removed.
+    attr_reader :base_url
+
+    def initialize(api_key = nil, base_url: nil, transport: nil)
+      key = api_key || ENV["MAILTEA_API_KEY"]
+      if key.nil? || key.empty?
+        raise Error.new(
+          "Missing Mailtea API key. Pass it to Mailtea::Client.new(api_key) or set " \
+          "the MAILTEA_API_KEY environment variable.",
+          code: "missing_api_key"
+        )
+      end
+
+      @api_key = key
+      configured = base_url || ENV["MAILTEA_API_BASE_URL"]
+      configured = nil if configured.nil? || configured.empty?
+      @base_url = (configured || DEFAULT_BASE_URL).chomp("/")
+      @transport = transport || Transport
+
+      requester = method(:perform)
+      @emails = Emails.new(requester)
+      @contacts = Contacts.new(requester)
+      @posts = Posts.new(requester)
+      @segments = Segments.new(requester)
+      @senders = Senders.new(requester)
+      @assets = Assets.new(requester)
+      @suppressions = Suppressions.new(requester)
+      @topics = Topics.new(requester)
+      @templates = Templates.new(requester)
+      @domains = Domains.new(requester)
+      @webhooks = Webhooks.new(requester)
+      @contact_properties = ContactProperties.new(requester)
+      @api_keys = ApiKeys.new(requester)
+      @automations = Automations.new(requester)
+      @automation_runs = AutomationRuns.new(requester)
+      @events = Events.new(requester)
+      @event_definitions = EventDefinitions.new(requester)
+    end
+
+    # Keeps the key out of `p client` and out of any exception report that
+    # inspects the object.
+    def inspect
+      "#<Mailtea::Client base_url=#{@base_url.inspect}>"
+    end
+
+    private
+
+    def perform(method, path, body = nil, raw: false)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "mailtea-ruby/#{VERSION}"
+      }
+      encoded = nil
+      unless body.nil?
+        headers["Content-Type"] = "application/json"
+        encoded = JSON.generate(body)
+      end
+
+      response = @transport.call(method, @base_url + path, headers, encoded)
+      request_id = response.headers["x-request-id"]
+
+      raise error_from(response, request_id) if response.status >= 400
+
+      return nil if response.status == 204 || response.body.to_s.empty?
+      # A few endpoints (suppressions export) answer with something other than
+      # JSON — hand back the body untouched instead of parsing it.
+      return response.body if raw
+
+      parse(response.body)
+    end
+
+    def error_from(response, request_id)
+      message = "HTTP #{response.status}"
+      code = nil
+      details = nil
+
+      parsed = begin
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        nil # non-JSON body — keep the status-line message
+      end
+
+      if parsed.is_a?(Hash)
+        message = parsed["error"] if parsed["error"].is_a?(String) && !parsed["error"].empty?
+        details = parsed["details"]
+        # Machine-readable code from the API, when it sends one (e.g.
+        # "marketing_plan_required" on 402). Branching on code survives a copy
+        # change to the message.
+        code = parsed["code"] if parsed["code"].is_a?(String)
+      end
+
+      Error.new(message, status: response.status, code: code, details: details,
+                         request_id: request_id)
+    end
+
+    def parse(text)
+      JSON.parse(text, object_class: Response)
+    rescue JSON::ParserError => e
+      raise Error.new("Could not parse the Mailtea API response as JSON: #{e.message}",
+                      code: "invalid_response")
+    end
+  end
+end

data/lib/mailtea/contact_properties.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +contact_properties+ resource (custom contact fields). Reach it at
+  # <tt>mailtea.contact_properties</tt>.
+  #
+  # Definitions are team-scoped — there is no +publication_id+. #create takes
+  # +key+ and +type+ ("string" or "number").
+  class ContactProperties < Resource
+    def create(params = nil, **fields)
+      request("POST", "/v1/contact-properties", payload(params, fields))
+    end
+
+    def list(params = nil, **filters)
+      request("GET", "/v1/contact-properties" + query(payload(params, filters)))
+    end
+
+    # Update a definition's +description+ or +fallback_value+ (+nil+ clears the
+    # fallback). The +key+ and +type+ are immutable.
+    def update(id, params = nil, **fields)
+      request("PATCH", "/v1/contact-properties/" + escape(id), payload(params, fields))
+    end
+
+    def delete(id)
+      request("DELETE", "/v1/contact-properties/" + escape(id))
+    end
+  end
+end

data/lib/mailtea/contacts.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +contacts+ resource. Reach it at <tt>mailtea.contacts</tt>.
+  #
+  # Audience resources are scoped to a publication — pass +publication_id+.
+  class Contacts < Resource
+    # Create a contact — or update it if the email already exists in the
+    # publication (the endpoint upserts). #upsert is the same call.
+    #
+    # Takes +publication_id+ and +email+, plus optional +status+
+    # ("active"/"unsubscribed"/"suppressed").
+    def create(params = nil, publication_id: UNSET, email: UNSET, status: UNSET, **rest)
+      body = payload(
+        params,
+        { publication_id: publication_id, email: email, status: status },
+        rest
+      )
+      request("POST", "/v1/contacts", body)
+    end
+
+    # Create the contact or update it in place — an alias of #create, named for
+    # what <tt>POST /v1/contacts</tt> actually does.
+    def upsert(params = nil, **fields)
+      create(params, **fields)
+    end
+
+    # List contacts (cursor-paginated). Filters: +publication_id+ (required),
+    # +status+ ("active"/"unsubscribed"/"suppressed"), +search+ (matches the
+    # email address), +limit+, +after+ (cursor from a previous +next_cursor+).
+    def list(params = nil, **filters)
+      request("GET", "/v1/contacts" + query(payload(params, filters)))
+    end
+
+    # Retrieve a contact by id or by email address. Requires +publication_id+.
+    def get(id_or_email, params = nil, **filters)
+      request("GET", "/v1/contacts/" + escape(id_or_email) + query(payload(params, filters)))
+    end
+
+    # Update a contact by id or email — currently its +status+.
+    # +publication_id+ is required and goes in the query string.
+    def update(id_or_email, params = nil, publication_id: UNSET, status: UNSET, **rest)
+      merged = payload(params, { publication_id: publication_id, status: status }, rest)
+      scope, body = Util.split_publication(merged)
+      request("PATCH", "/v1/contacts/" + escape(id_or_email) + scope, body)
+    end
+
+    # Delete a contact by id or email. Requires +publication_id+.
+    def delete(id_or_email, params = nil, **filters)
+      request("DELETE", "/v1/contacts/" + escape(id_or_email) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea/domains.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # Tracking sub-domains (CNAME) under a domain — used to serve open-pixel and
+  # click-tracking links from your own domain. Reach it at
+  # <tt>mailtea.domains.tracking</tt>.
+  class TrackingDomains < Resource
+    # Add a tracking sub-domain. Takes +publication_id+ and +subdomain+. The
+    # response +records+ lists the CNAME to add.
+    def create(domain_id, params = nil, **fields)
+      merged = payload(params, fields)
+      request(
+        "POST",
+        "/v1/domains/" + escape(domain_id) + "/tracking-domains" +
+          query({ "publication_id" => merged["publication_id"] }),
+        { "subdomain" => merged["subdomain"] }
+      )
+    end
+
+    # List a domain's tracking sub-domains. Requires +publication_id+.
+    def list(domain_id, params = nil, **filters)
+      request(
+        "GET",
+        "/v1/domains/" + escape(domain_id) + "/tracking-domains" + query(payload(params, filters))
+      )
+    end
+
+    # Verify a tracking sub-domain's CNAME. Requires +publication_id+.
+    def verify(domain_id, tracking_domain_id, params = nil, **filters)
+      request(
+        "POST",
+        "/v1/domains/" + escape(domain_id) + "/tracking-domains/" +
+          escape(tracking_domain_id) + "/verify" + query(payload(params, filters))
+      )
+    end
+
+    # Delete a tracking sub-domain. Requires +publication_id+.
+    def delete(domain_id, tracking_domain_id, params = nil, **filters)
+      request(
+        "DELETE",
+        "/v1/domains/" + escape(domain_id) + "/tracking-domains/" +
+          escape(tracking_domain_id) + query(payload(params, filters))
+      )
+    end
+  end
+
+  # Domain claims — take a domain back from the team that currently holds it.
+  # Reach it at <tt>mailtea.domains.claims</tt>.
+  #
+  # Use this when adding a domain is refused because the host is connected to
+  # another publication: open a claim, publish the TXT record the response
+  # lists to prove you control the DNS, then #verify it. On success the other
+  # team's domain is released and a fresh one is created for you.
+  class DomainClaims < Resource
+    # Open a claim. Takes +publication_id+, +name+ and an optional +region+.
+    # The response +records+ lists the TXT record to publish.
+    def create(params = nil, **fields)
+      request("POST", "/v1/domains/claim", payload(params, fields))
+    end
+
+    # Poll a claim. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/domains/claims/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Check the TXT record and complete the claim if it is there.
+    #
+    # Safe to call repeatedly: a record that has not propagated yet leaves the
+    # claim pending with the same record, so nothing has to be republished. A
+    # completed claim answers with the fresh +domain+ beside the claim.
+    def verify(id, params = nil, **filters)
+      request("POST",
+              "/v1/domains/claims/" + escape(id) + "/verify" + query(payload(params, filters)))
+    end
+
+    # Withdraw a pending claim. Requires +publication_id+.
+    def cancel(id, params = nil, **filters)
+      request("DELETE", "/v1/domains/claims/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+
+  # The +domains+ resource (email/site sending domains). Reach it at
+  # <tt>mailtea.domains</tt>.
+  #
+  # Scoped to a publication — pass +publication_id+. Register a domain, add the
+  # returned DNS +records+, then #verify it before sending from it.
+  #
+  # #create takes +region+ (fixed at creation), +tls+ and +tracking_subdomain+;
+  # #list filters on +region+ and +status+.
+  #
+  # <tt>update(id, tracking_subdomain: nil)</tt> removes a tracking subdomain:
+  # the domain's links go back to being served from the Mailtea host, and links
+  # in mail already sent point at the old hostname and stop resolving. The +nil+
+  # reaches the wire as an explicit +null+, so omitting the key (leave the
+  # subdomain alone) and passing +nil+ (remove it) are different requests. An
+  # empty string is neither; it is refused with +tracking_subdomain_invalid+.
+  # +nil+ is an update-only value: a create has nothing to clear.
+  class Domains < Resource
+    # Tracking sub-domains (CNAME) under a domain.
+    attr_reader :tracking
+
+    # Domain claims — take a domain back from another publication.
+    attr_reader :claims
+
+    def initialize(request)
+      super
+      @tracking = TrackingDomains.new(request)
+      @claims = DomainClaims.new(request)
+    end
+
+    # Register a domain. The response +records+ lists the DNS records to add.
+    def create(params = nil, **fields)
+      request("POST", "/v1/domains", payload(params, fields))
+    end
+
+    # List domains. Requires +publication_id+.
+    def list(params = nil, **filters)
+      request("GET", "/v1/domains" + query(payload(params, filters)))
+    end
+
+    # Retrieve a domain with its DNS records and status. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/domains/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Verify a domain via its DNS records; +status+ becomes "verified".
+    def verify(id, params = nil, **filters)
+      request("POST", "/v1/domains/" + escape(id) + "/verify" + query(payload(params, filters)))
+    end
+
+    # Update a domain — including +custom_return_path+, which delegates a
+    # subdomain as the envelope sender so SPF aligns with your own domain. Mail
+    # keeps sending on the default return-path until the delegated DNS resolves.
+    # +publication_id+ is required and goes in the query string.
+    #
+    # <tt>tracking_subdomain: nil</tt> removes the tracking subdomain; leaving
+    # the key out leaves it alone. Only the query string drops nils, so the
+    # removal travels in the body as an explicit +null+.
+    def update(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields))
+      request("PATCH", "/v1/domains/" + escape(id) + scope, body)
+    end
+
+    # Delete a domain. Requires +publication_id+.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/domains/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea/emails.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "inbound"
+
+module Mailtea
+  # The +emails+ resource: transactional send, status, scheduling, and the
+  # inbound sub-resource. Reach it at <tt>mailtea.emails</tt>.
+  #
+  # The documented fields are named keywords; anything else the API accepts can
+  # be passed as an extra keyword or inside a leading wire-format Hash, and both
+  # styles can be mixed:
+  #
+  #   mailtea.emails.send(from: "a@b.co", to: "c@d.co", subject: "Hi", html: "<p>Hi</p>")
+  #   mailtea.emails.send({ "from" => "a@b.co", "to" => "c@d.co", "subject" => "Hi" })
+  class Emails < Resource
+    # Inbound (received) emails: list, get, reply, and attachments.
+    attr_reader :inbound
+
+    def initialize(request)
+      super
+      @inbound = InboundEmails.new(request)
+    end
+
+    # Send a transactional email. Provide +html+/+text+ OR a +template+.
+    # Returns <tt>{ "id" => ... }</tt>.
+    #
+    # Set the From with exactly one of +from+ (a <tt>Name <email></tt> string) or
+    # +sender_id+ (the id of a named, verified publication sender, which also
+    # supplies its default +reply_to+).
+    #
+    # +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+ and
+    # +bcc+.
+    #
+    # - +tags+ — an Array of <tt>{ name:, value: }</tt> for filtering and analytics.
+    # - +headers+ — a Hash of extra custom email headers.
+    # - +attachments+ — an Array of <tt>{ filename:, content: }</tt> where
+    #   +content+ is base64. Add +content_type+ and a +content_id+ to embed an
+    #   inline image referenced by <tt>cid:</tt> in the HTML; omit +content_id+
+    #   for a regular file attachment.
+    # - +scheduled_at+ — an ISO 8601 datetime to schedule the send.
+    # - +tracking_open+ / +tracking_click+ — opt this message out of the open
+    #   pixel or link rewriting. A sending domain with tracking off cannot be
+    #   overridden from a send.
+    #
+    # This deliberately shadows Object#send on the resource object, because the
+    # API's verb is "send" and reading <tt>mailtea.emails.send(...)</tt> matters
+    # more than metaprogramming on a resource. Ruby's +__send__+ is untouched.
+    def send(params = nil, to: UNSET, subject: UNSET, from: UNSET, sender_id: UNSET,
+             html: UNSET, text: UNSET, template: UNSET, cc: UNSET, bcc: UNSET,
+             reply_to: UNSET, tags: UNSET, headers: UNSET, attachments: UNSET,
+             scheduled_at: UNSET, tracking_open: UNSET, tracking_click: UNSET, **rest)
+      body = payload(
+        params,
+        { to: to, subject: subject, from: from, sender_id: sender_id, html: html,
+          text: text, template: template, cc: cc, bcc: bcc, reply_to: reply_to,
+          tags: tags, headers: headers, attachments: attachments,
+          scheduled_at: scheduled_at, tracking_open: tracking_open,
+          tracking_click: tracking_click },
+        rest
+      )
+      request("POST", "/v1/emails", body)
+    end
+
+    # Send up to 100 emails in one request. Takes an Array of send payloads and
+    # returns <tt>{ "data" => [{ "id" => ... }] }</tt>.
+    #
+    # The array goes out as the request body verbatim, so each item takes the
+    # same fields as #send except +scheduled_at+ and +attachments+.
+    def batch(emails)
+      unless emails.is_a?(Array)
+        raise Error.new(
+          "emails.batch takes an Array of email payloads, got #{emails.class}.",
+          code: "invalid_batch"
+        )
+      end
+
+      request("POST", "/v1/emails/batch", emails.map { |email| payload(email) })
+    end
+
+    # Retrieve an email with its delivery status and tracking counters.
+    #
+    # Adds a friendly +status+ alias of the raw +last_event+ wire field:
+    # "queued", "scheduled", "sent", "delivered", "bounced", "complained",
+    # "failed", "delivery_delayed", "suppressed" or "canceled".
+    def get(id)
+      email = request("GET", "/v1/emails/" + escape(id))
+      email["status"] = email["last_event"] if email.is_a?(Hash) && email["status"].nil?
+      email
+    end
+
+    # List emails (most recent first). Optional filters: +status+, +tag_name+,
+    # +tag_value+, +search+ (substring match on recipient/sender/subject),
+    # +from_date+, +to_date+, +limit+, +offset+.
+    #
+    # +from_date+ is clamped to the plan's analytics retention window — 30 days
+    # on most plans, 90 on Scale and Enterprise. A value reaching further back
+    # returns data from the start of that window rather than an error, and
+    # omitting it returns the window rather than all time.
+    def list(params = nil, **filters)
+      request("GET", "/v1/emails" + query(payload(params, filters)))
+    end
+
+    # Aggregate transactional metrics over an optional date window: totals,
+    # delivered/bounced/open/click counts, per-status counts, and rates.
+    # Optional filters: +from_date+, +to_date+ (ISO 8601).
+    #
+    # +from_date+ is clamped the same way as #list, and the +from_date+ in the
+    # response reports the window actually used.
+    def analytics(params = nil, **filters)
+      request("GET", "/v1/emails/analytics" + query(payload(params, filters)))
+    end
+
+    # Update a scheduled email (currently only +scheduled_at+).
+    def update(id, params = nil, scheduled_at: UNSET, **rest)
+      body = payload(params, { scheduled_at: scheduled_at }, rest)
+      request("PATCH", "/v1/emails/" + escape(id), body)
+    end
+
+    # Convenience wrapper over #update for the reschedule case.
+    def reschedule(id, scheduled_at)
+      update(id, scheduled_at: scheduled_at)
+    end
+
+    # Cancel a scheduled email before it sends.
+    #
+    # Only a message still sitting at +last_event+ "scheduled" can be cancelled:
+    # a send with no +scheduled_at+ is already on its way and answers 422, and so
+    # does a scheduled one once its time has passed.
+    def cancel(id)
+      request("POST", "/v1/emails/" + escape(id) + "/cancel")
+    end
+  end
+end

data/lib/mailtea/error.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Mailtea
+  # Raised when the Mailtea API returns an error, or when the client cannot get
+  # a request out of the process at all.
+  #
+  # One class covers both so a caller needs one +rescue+ on the send path:
+  # a 422 from the API and a dropped TCP connection are equally a failed send.
+  # +status+ tells them apart — it is the HTTP status for an API error and
+  # +0+ for a client-side fault (missing key, no transport, unreachable host).
+  #
+  #   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
+  #     e.code             # "marketing_plan_required", 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
+  class Error < StandardError
+    # HTTP status code, or 0 for a client-side error.
+    attr_reader :status
+
+    # Machine-readable code, when the API sends one (e.g. +marketing_plan_required+)
+    # or for a client-side fault (+missing_api_key+, +connection_error+). May be nil.
+    # Branching on this survives a copy change to the message.
+    attr_reader :code
+
+    # The API's +details+ array (validation issues), when present. May be nil.
+    attr_reader :details
+
+    # The API's +x-request-id+ header, for support and debugging. May be nil.
+    attr_reader :request_id
+
+    def initialize(message, status: 0, code: nil, details: nil, request_id: nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+      @request_id = request_id
+    end
+  end
+end

data/lib/mailtea/events.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +events+ resource (custom product events that trigger automations and
+  # resume +wait_for_event+ steps). Reach it at <tt>mailtea.events</tt>.
+  #
+  # Events are scoped to a publication — pass +publication_id+.
+  class Events < Resource
+    # Record an event for a contact. Takes +publication_id+, +name+, and exactly
+    # one of +contact_id+ or +email+ (both is a 400 +contact_reference_conflict+,
+    # neither a 400 +contact_reference_required+). Optional: +create_contact+,
+    # +properties+, +occurred_at+, +idempotency_key+.
+    #
+    # +create_contact+ is *opt-in* — without it an unresolvable address is a 404
+    # +contact_not_found+ rather than a new contact.
+    #
+    # Returns 202 with +enrolled_automations+ and +resumed_runs+. A replay of the
+    # same +idempotency_key+ returns the ORIGINAL event id with
+    # <tt>replayed: true</tt> and always reports <tt>enrolled_automations: 0,
+    # resumed_runs: 0</tt>. Note that <tt>resumed_runs: 0</tt> on a FRESH ingest
+    # does not prove nothing matched — a run being advanced concurrently is
+    # invisible for that instant, so read the run itself
+    # (Mailtea::AutomationRuns#get) rather than the counter.
+    #
+    # Like Emails#send this shadows Object#send on the resource object;
+    # +__send__+ is untouched.
+    def send(params = nil, **fields)
+      request("POST", "/v1/events", payload(params, fields))
+    end
+
+    # List recorded events (cursor-paginated). Filters: +publication_id+
+    # (required), +name+, +contact_id+, +limit+, +after+ (cursor from a previous
+    # +next_cursor+).
+    def list(params = nil, **filters)
+      request("GET", "/v1/events" + query(payload(params, filters)))
+    end
+  end
+
+  # The +event_definitions+ resource (the catalog of event names a publication
+  # expects, with optional property schemas). Reach it at
+  # <tt>mailtea.event_definitions</tt>.
+  #
+  # Definitions are scoped to a publication — pass +publication_id+. They are
+  # documentation and tooling, not a gate: Events#send accepts an event with no
+  # definition.
+  class EventDefinitions < Resource
+    # Create an event definition. Takes +publication_id+ and +name+, plus
+    # optional +description+ and +schema_json+. The name is immutable once created.
+    def create(params = nil, **fields)
+      request("POST", "/v1/event-definitions", payload(params, fields))
+    end
+
+    # List event definitions (cursor-paginated). Filters: +publication_id+
+    # (required), +limit+, +after+. List items carry no +inferred_properties+ —
+    # use #get for those.
+    def list(params = nil, **filters)
+      request("GET", "/v1/event-definitions" + query(payload(params, filters)))
+    end
+
+    # Retrieve one definition. Requires +publication_id+. Adds
+    # +schema_properties+ and +inferred_properties+ — the latter computed on read
+    # over the last 500 events, reporting each key's type, sample count and
+    # *coverage*. Low coverage is the trap: a condition on a key present in 3% of
+    # events will almost never match.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/event-definitions/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update a definition's +description+ or +schema_json+ (+nil+ clears the
+    # schema back to free-form). +publication_id+ is required and goes in the
+    # query string. +name+ is immutable — sending it is a 400
+    # +event_name_immutable+, not a silently dropped rename.
+    def update(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields), keep_in_body: false)
+      request("PATCH", "/v1/event-definitions/" + escape(id) + scope, body)
+    end
+
+    # Delete an event definition. Requires +publication_id+. Events already
+    # recorded under that name are untouched.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/event-definitions/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end