sendping 1.0.0

data/lib/sendping/emails.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Send and inspect emails. Inbound mail lives under SendPing::Emails::Receiving.
+  module Emails
+    class << self
+      # Send a single email. POST /emails
+      #   SendPing::Emails.send({ from: "...", to: ["..."], subject: "...", html: "..." })
+      #
+      # Write ordinary links. Anchors, markdown links and bare URLs/domains in
+      # BOTH the :html and :text bodies are converted to tracked redirects at
+      # send time (when the sending domain has click tracking on), so a click is
+      # recorded whichever alternative the recipient's mail client renders.
+      # Opt-out links are never wrapped, and the content you send is stored and
+      # returned UNCHANGED — only the delivered copy carries the tracking URL.
+      # Pass { idempotency_key: "order-123" } as the second argument to retry safely.
+      def send(params, options = {})
+        Client.request(:post, "/emails", body: params, options: options)
+      end
+
+      # Send up to 100 emails in one request. POST /emails/batch (alias of Batch.send).
+      # Batch items reject `attachments` and `scheduled_at` — send those
+      # individually via Emails.send.
+      def batch(payloads, options = {})
+        Client.request(:post, "/emails/batch", body: payloads, options: options)
+      end
+
+      # List sent emails (trimmed list items) — cursor pagination plus optional
+      # server-side filters: `campaign_id`, `automation_id`, `source`
+      # ("individual" for all one-off sends with no campaign/automation origin,
+      # "api" for one-off sends made with an API key — which also covers mail
+      # sent before the send origin was recorded — or "dashboard" for one-off
+      # mail composed in the dashboard: the composer and inbox replies/forwards;
+      # honoured only when neither `campaign_id` nor `automation_id` is
+      # supplied), `domain_id`, `status` (matched case-insensitively
+      # against the row's `last_event`), `folder` (one of "outbox", "sent",
+      # "scheduled" or "failed" — any other value is rejected with a 422) and
+      # `search` (recipients, subject and sender). `q` is the server's alias
+      # for `search`, honoured only when `search` is absent. GET /emails
+      def list(params = {})
+        query = Client.pagination(params).merge(
+          Client.filters(params, :campaign_id, :automation_id, :source, :domain_id, :status, :search, :q, :folder)
+        )
+        Client.request(:get, "/emails", query: query)
+      end
+
+      # Per-source send metrics, one row per origin. `kind` is "campaign",
+      # "automation", "api" (one-off API-key sends, including mail sent before
+      # the send origin was recorded) or "individual" (dashboard-composed
+      # one-offs); `id`, `name`, `subject` and `status` are null for both the
+      # "api" and "individual" rows. Not paginated. GET /emails/sources
+      def sources
+        Client.request(:get, "/emails/sources")
+      end
+
+      # Retrieve a sent email and its events. GET /emails/:id
+      def get(email_id)
+        Client.request(:get, "/emails/#{Client.path_escape(email_id)}")
+      end
+
+      # List a sent email's attachments. GET /emails/:id/attachments
+      def list_attachments(email_id)
+        Client.request(:get, "/emails/#{Client.path_escape(email_id)}/attachments")
+      end
+
+      # Retrieve one attachment's metadata. GET /emails/:id/attachments/:attachment_id
+      def get_attachment(email_id, attachment_id)
+        Client.request(:get, "/emails/#{Client.path_escape(email_id)}/attachments/#{Client.path_escape(attachment_id)}")
+      end
+
+      # Reschedule a scheduled email. PATCH /emails/:id
+      #   SendPing::Emails.update("email_id", { scheduled_at: "2026-08-01T09:00:00Z" })
+      def update(email_id, params)
+        Client.request(:patch, "/emails/#{Client.path_escape(email_id)}", body: params)
+      end
+
+      # Cancel a scheduled email. POST /emails/:id/cancel
+      def cancel(email_id)
+        Client.request(:post, "/emails/#{Client.path_escape(email_id)}/cancel")
+      end
+    end
+
+    # Inbound (received) email.
+    module Receiving
+      class << self
+        # List received emails — cursor pagination plus an optional
+        # `received_for` filter (only messages received for that address).
+        # With no `limit` and no cursor the endpoint returns up to 1000 rows in
+        # one response; pass `limit` to get normal 1-100 pages.
+        # GET /emails/receiving
+        def list(params = {})
+          query = Client.pagination(params).merge(Client.filters(params, :received_for))
+          Client.request(:get, "/emails/receiving", query: query)
+        end
+
+        # Per-address inbound stats (totals, replies, last received).
+        # Not paginated. GET /emails/receiving/addresses
+        def list_addresses
+          Client.request(:get, "/emails/receiving/addresses")
+        end
+
+        # Retrieve a received email. GET /emails/receiving/:id
+        def get(email_id)
+          Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}")
+        end
+
+        # List a received email's attachments. With no `limit` and no `after`
+        # one page carries up to 1,000 of them and `has_more` reports any
+        # truncation; supplying either paginates normally.
+        # GET /emails/receiving/:id/attachments
+        def list_attachments(email_id, params = {})
+          Client.request(
+            :get,
+            "/emails/receiving/#{Client.path_escape(email_id)}/attachments",
+            query: Client.pagination(params)
+          )
+        end
+
+        # Download one attachment as raw bytes (binary String).
+        # GET /emails/receiving/:id/attachments/:attachment_id
+        def get_attachment(email_id, attachment_id)
+          Client.request(
+            :get,
+            "/emails/receiving/#{Client.path_escape(email_id)}/attachments/#{Client.path_escape(attachment_id)}",
+            raw: true
+          )
+        end
+
+        # Download the original RFC822/MIME message as raw bytes (binary String).
+        # GET /emails/receiving/:id/raw
+        def get_raw(email_id)
+          Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}/raw", raw: true)
+        end
+
+        # Forward a received email. POST /emails/receiving/:id/forward
+        #   Receiving.forward(id, { from: "you@yourdomain.com", to: "team@you.com" })
+        def forward(email_id, params, options = {})
+          Client.request(:post, "/emails/receiving/#{Client.path_escape(email_id)}/forward", body: params, options: options)
+        end
+
+        # Reply to a received email's sender, threaded into the conversation.
+        # POST /emails/receiving/:id/reply
+        def reply(email_id, params, options = {})
+          Client.request(:post, "/emails/receiving/#{Client.path_escape(email_id)}/reply", body: params, options: options)
+        end
+
+        # Delete a received email. DELETE /emails/receiving/:id
+        def delete(email_id)
+          Client.request(:delete, "/emails/receiving/#{Client.path_escape(email_id)}")
+        end
+      end
+    end
+  end
+
+  # Batch send — SendPing::Batch.send([...]). POST /emails/batch
+  # Batch items reject `attachments` and `scheduled_at` — send those
+  # individually via SendPing::Emails.send.
+  module Batch
+    class << self
+      def send(payloads, options = {})
+        Client.request(:post, "/emails/batch", body: payloads, options: options)
+      end
+    end
+  end
+end

data/lib/sendping/error.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Raised for every non-2xx API response. Mirrors the API error shape
+  # { statusCode, name, message }:
+  #
+  #   begin
+  #     SendPing::Emails.send(params)
+  #   rescue SendPing::Error => e
+  #     e.status_code # => 422
+  #     e.name        # => "validation_error"
+  #     e.message     # => "The `from` address must use a verified domain."
+  #   end
+  #
+  # Match on #name, never on #message — messages are scrubbed of provider
+  # identifiers server-side and are not a stable contract. A handler may also
+  # answer with a status other than the one a name usually maps to, so read
+  # #status_code rather than assuming one from the name.
+  #
+  # Some errors carry additive fields on top of those three. The whole parsed
+  # body is kept on #body, with the common extras surfaced as readers that
+  # return nil on an ordinary error:
+  #
+  #   rescue SendPing::Error => e
+  #     if (cap = e.limit)                   # WHICH quota ran out
+  #       cap["kind"]                        # => "emails_daily"
+  #       cap["used"]; cap["limit"]          # => 100, 100
+  #       cap.dig("next_plan", "name")       # => "Pro"
+  #     end
+  #     e.reputation                         # reputation gates
+  #     e.sent                               # a batch that failed part way through
+  #     e.sent_count                         #   — do NOT resend these
+  #   end
+  class Error < StandardError
+    attr_reader :status_code, :error_name
+
+    # The full parsed error body ({} when the response was not a JSON object).
+    # Read it for any additive field newer than this SDK version.
+    attr_reader :body
+
+    def initialize(message = nil, status_code: nil, error_name: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @error_name = error_name
+      @body = body.is_a?(Hash) ? body : {}
+    end
+
+    # The API error `name` (e.g. "validation_error", "not_found").
+    def name
+      @error_name
+    end
+
+    # Original email for a failed or unconfirmed send; inspect before resending.
+    def id
+      value = @body["id"]
+      value.is_a?(String) ? value : nil
+    end
+
+    # Reserved prefix, including uncertain sends. Never automatically resend it.
+    def reserved
+      value = @body["reserved"]
+      value.is_a?(Array) ? value : nil
+    end
+
+    # The never-attempted tail; distinct from uncertain reserved items.
+    def unsent_count
+      value = @body["unsent_count"]
+      value.is_a?(Integer) ? value : nil
+    end
+
+    # The plan/quota cap this request hit, else nil. Carried by
+    # plan_limit_reached, every *_quota_exceeded, contact_limit_reached and
+    # ai_credits_exceeded — it says WHICH quota ran out, how much of it was
+    # used, and the cheapest plan that would fit.
+    def limit
+      hash_field("limit")
+    end
+
+    # The reputation-gate detail on reputation_paused /
+    # reputation_limit_exceeded, else nil. Carries at least "retryable" and
+    # "scope" ("tenant" | "domain" | "platform").
+    def reputation
+      hash_field("reputation")
+    end
+
+    # The emails that were already sent before a batch failed part way through
+    # (POST /emails/batch with an idempotency_key), else nil. Do NOT resend them.
+    def sent
+      value = @body["sent"]
+      value.is_a?(Array) ? value : nil
+    end
+
+    # How many emails went out before a batch failed part way through, else nil.
+    # Falls back to #sent's size when the body carried the list but not the count.
+    def sent_count
+      count = @body["sent_count"]
+      return count if count.is_a?(Integer)
+
+      sent&.size
+    end
+
+    private
+
+    def hash_field(key)
+      value = @body[key]
+      value.is_a?(Hash) ? value : nil
+    end
+  end
+end

data/lib/sendping/events.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Custom events that automations trigger on. Events are DOMAIN-FIRST:
+  # `domain` is required on send, and only that domain's automations fire.
+  module Events
+    class << self
+      # Send a custom event. POST /events/send
+      #   SendPing::Events.send({ event: "signup.completed", domain: "yourdomain.com",
+      #                             email: "user@example.com", payload: { plan: "pro" } })
+      # Identify the contact by `contact_id` OR `email`. Event names cannot
+      # start with the reserved "sendping:" prefix.
+      #
+      # NOTE: only POST /emails, POST /emails/batch, and received-email reply/forward honour `Idempotency-Key`.
+      # An `idempotency_key` passed here is still forwarded, but the server
+      # ignores it, so a retry ingests a SECOND event and can enroll the contact
+      # twice — de-duplicate on your side instead.
+      def send(params, options = {})
+        Client.require_domain!(params, "Events.send")
+        Client.request(:post, "/events/send", body: params, options: options)
+      end
+
+      # Create a custom-event definition (name + optional payload schema).
+      # Schema values are one of "string", "number", "boolean", "date".
+      # POST /events
+      #   SendPing::Events.create({ name: "signup.completed", schema: { plan: "string" } })
+      #
+      # NOTE: `options[:idempotency_key]` carries no guarantee here — see
+      # `send`. A duplicate event name is already a 422 validation_error.
+      def create(params, options = {})
+        Client.request(:post, "/events", body: params, options: options)
+      end
+
+      # Update a definition's payload schema. PATCH /events/:id
+      # The event NAME is immutable (automations reference it) — passing `name`
+      # is a 422; pass `schema: nil` to clear the schema.
+      #   SendPing::Events.update("evt_1", { schema: { plan: "string" } })
+      def update(event_id, params)
+        Client.request(:patch, "/events/#{Client.path_escape(event_id)}", body: params)
+      end
+
+      # List custom-event definitions. GET /events
+      def list(params = {})
+        Client.request(:get, "/events", query: Client.pagination(params))
+      end
+
+      # Delete a custom-event definition. DELETE /events/:id
+      def delete(event_id)
+        Client.request(:delete, "/events/#{Client.path_escape(event_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/logs.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SendPing
+  # API request logs.
+  module Logs
+    class << self
+      # List logs — cursor pagination plus optional server-side `method`
+      # (e.g. "POST") and `status` (e.g. 429) filters. GET /logs
+      def list(params = {})
+        query = Client.pagination(params)
+        method = Client.opt(params, :method)
+        status = Client.opt(params, :status)
+        query[:method] = method if method
+        query[:status] = status unless status.nil?
+        Client.request(:get, "/logs", query: query)
+      end
+
+      # Retrieve one log with request/response bodies. GET /logs/:id
+      def get(log_id)
+        Client.request(:get, "/logs/#{Client.path_escape(log_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/polls.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Read-only results of the in-email poll widget.
+  module Polls
+    class << self
+      # One summary row per email that has poll responses. GET /polls
+      def list(params = {})
+        Client.request(:get, "/polls", query: Client.pagination(params))
+      end
+
+      # The aggregated answer breakdown for one email. GET /polls/:email_id
+      def get(email_id)
+        Client.request(:get, "/polls/#{Client.path_escape(email_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/segments.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Segments are DOMAIN-FIRST: `domain` is required on create and list. Names
+  # are unique within a domain (reusable across domains); every domain also
+  # carries an auto-created "General" (all contacts) segment.
+  module Segments
+    class << self
+      # POST /segments
+      #   SendPing::Segments.create({ domain: "yourdomain.com", name: "VIP",
+      #                                 filter: { status: "subscribed" } })
+      def create(params)
+        Client.require_domain!(params, "Segments.create")
+        Client.request(:post, "/segments", body: params)
+      end
+
+      # GET /segments/:id
+      def get(segment_id)
+        Client.request(:get, "/segments/#{Client.path_escape(segment_id)}")
+      end
+
+      # List a domain's segments (`domain` required). GET /segments?domain=
+      def list(params)
+        domain = Client.require_domain!(params, "Segments.list")
+        Client.request(:get, "/segments", query: { domain: domain }.merge(Client.pagination(params)))
+      end
+
+      # Preview the contacts a segment currently resolves to (filter matches
+      # plus explicit memberships). With no pagination params the response is
+      # capped at 1,000 contacts and sets `has_more` — a segment can hold far
+      # more than that, so page with `limit` + `after` to read all of it.
+      # GET /segments/:id/contacts
+      def contacts(segment_id, params = {})
+        Client.request(
+          :get,
+          "/segments/#{Client.path_escape(segment_id)}/contacts",
+          query: Client.pagination(params)
+        )
+      end
+
+      # PATCH /segments/:id
+      def update(segment_id, params)
+        Client.request(:patch, "/segments/#{Client.path_escape(segment_id)}", body: params)
+      end
+
+      # DELETE /segments/:id
+      def delete(segment_id)
+        Client.request(:delete, "/segments/#{Client.path_escape(segment_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/templates.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SendPing
+  module Templates
+    class << self
+      # POST /templates — params: { name:, alias:, subject:, html:, text:, variables: [...] }
+      def create(params)
+        Client.request(:post, "/templates", body: params)
+      end
+
+      # GET /templates/:id (an alias works anywhere an id is accepted)
+      def get(template_id)
+        Client.request(:get, "/templates/#{Client.path_escape(template_id)}")
+      end
+
+      # GET /templates
+      def list(params = {})
+        Client.request(:get, "/templates", query: Client.pagination(params))
+      end
+
+      # PATCH /templates/:id
+      def update(template_id, params)
+        Client.request(:patch, "/templates/#{Client.path_escape(template_id)}", body: params)
+      end
+
+      # Duplicate a template. POST /templates/:id/duplicate — params: { name:, alias: }
+      def duplicate(template_id, params = {})
+        Client.request(:post, "/templates/#{Client.path_escape(template_id)}/duplicate", body: params)
+      end
+
+      # Publish a template (make its latest draft live). POST /templates/:id/publish
+      def publish(template_id)
+        Client.request(:post, "/templates/#{Client.path_escape(template_id)}/publish")
+      end
+
+      # DELETE /templates/:id
+      def delete(template_id)
+        Client.request(:delete, "/templates/#{Client.path_escape(template_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/topics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Topics (granular subscriptions) are DOMAIN-FIRST: `domain` is required on
+  # create and list. Topic names are reusable across domains.
+  module Topics
+    class << self
+      # POST /topics
+      #   SendPing::Topics.create({ domain: "yourdomain.com", name: "Product updates",
+      #                               default_subscription: "opt_in" })
+      def create(params)
+        Client.require_domain!(params, "Topics.create")
+        Client.request(:post, "/topics", body: params)
+      end
+
+      # GET /topics/:id
+      def get(topic_id)
+        Client.request(:get, "/topics/#{Client.path_escape(topic_id)}")
+      end
+
+      # List a domain's topics (`domain` required). GET /topics?domain=
+      def list(params)
+        domain = Client.require_domain!(params, "Topics.list")
+        Client.request(:get, "/topics", query: { domain: domain }.merge(Client.pagination(params)))
+      end
+
+      # PATCH /topics/:id
+      def update(topic_id, params)
+        Client.request(:patch, "/topics/#{Client.path_escape(topic_id)}", body: params)
+      end
+
+      # DELETE /topics/:id
+      def delete(topic_id)
+        Client.request(:delete, "/topics/#{Client.path_escape(topic_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SendPing
+  VERSION = "1.0.0"
+end