usend 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b268a5e6ce690133139c0bbd3825ba7063df55be6ccf0f0a7145423affb134a
+  data.tar.gz: f831022189dedb8270399b49791cd55f237233bc065a05dc23ebe3e122ff4e4f
+SHA512:
+  metadata.gz: 635efa4c472902029d1f59e52f1d85325a8b5ceda309117bf066e085afd75675bcac385d8404e86f27838595fa55fbbc607eb7db521c9c7ba2e6a05c256c0487
+  data.tar.gz: 4ce45b1683cef56f8b892dfd88290d27fee4f893d4c512b2d1dde7e94fe22d4fc483f528350f64dd1d5c160f99a69f5f1a92e80d3156bd943c65d0af9f038bd0

data/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 uSend
+
+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,107 @@
+# usend for Ruby
+
+The official Ruby SDK for [usend](https://usend.et), the email API for developers. Standard library only
+(`net/http`, `json`), Ruby 3.0 or newer.
+
+```bash
+gem install usend
+# or in your Gemfile: gem "usend"
+```
+
+## Quick start
+
+```ruby
+require "usend"
+
+usend = Usend::Client.new(api_key: ENV["USEND_API_KEY"])
+
+email = usend.emails.send_email(
+  from: "Acme <hello@acme.com>",
+  to: "ann@example.com",
+  subject: "Your login code",
+  html: "<p>Your code is <b>482913</b></p>"
+)
+puts email["id"]
+```
+
+`emails.send` is an alias of `emails.send_email`. Methods return the API's JSON (Hash or Array with string
+keys) and raise `Usend::Error` on failure.
+
+- The key defaults to `USEND_API_KEY`; the base URL to `USEND_BASE_URL` or `https://api.usend.et`.
+- Options: `timeout:` (seconds, default 30), `max_retries:` (default 2).
+- Resources: `emails`, `events` (custom events), `automations`, `logs`, `received` (inbound mail), `inboxes` (shared mailboxes), `domains`, `api_keys`, `templates`,
+  `contacts`, `contact_properties`, `contact_imports`, `segments`, `topics`, `audiences`, `broadcasts`, `webhooks`, `suppressions`, `tools`, `oauth`.
+
+```ruby
+usend.emails.batch([{ from: "...", to: "a@x.com", subject: "Hi", html: "..." }])
+usend.emails.get("email-id")
+usend.emails.list(limit: 20)
+usend.emails.update("email-id", scheduled_at: "2030-01-01T09:00:00Z")
+usend.emails.cancel("email-id")
+usend.emails.events("email-id")
+usend.domains.create(name: "acme.com")
+usend.domains.verify("domain-id")
+usend.templates.publish("welcome")
+usend.contacts.create(email: "ann@example.com", first_name: "Ann")
+usend.broadcasts.send_broadcast("broadcast-id")
+```
+
+Pass an idempotency key to make a send safe to repeat:
+
+```ruby
+usend.emails.send_email({ from: "...", to: "...", subject: "...", html: "..." }, idempotency_key: "order-1042")
+```
+
+## Errors and retries
+
+```ruby
+begin
+  usend.emails.send_email(from: "nobody@unverified.com", to: "ann@example.com", subject: "Hi", html: "x")
+rescue Usend::Error => e
+  e.status_code # 403 (nil for network failures)
+  e.name        # "validation_error", "rate_limit_exceeded", ...
+  e.message
+end
+```
+
+Requests are retried up to `max_retries` times with backoff on `429` (honoring `Retry-After`), `5xx` and network
+errors. A `POST` is only retried after a `5xx` or network error when it carries an `idempotency_key`, so an email
+is never sent twice by accident.
+
+## SMTP
+
+Send through SMTP instead; the API key is the password. Port 465 is implicit TLS, 587 is STARTTLS.
+
+```ruby
+s = Usend.smtp_settings(api_key: ENV["USEND_API_KEY"])           # smtp.usend.et:465
+s = Usend.smtp_settings(api_key: ENV["USEND_API_KEY"], port: 587) # STARTTLS
+# or usend.smtp_settings(port: 587)
+
+# s => { address:, port:, user_name: "usend", password:, authentication: :plain, tls:, enable_starttls_auto: }
+```
+
+For a self-hosted platform pass `host:`, set `USEND_SMTP_HOST`, or construct the client with
+`base_url: "https://api.example.com"` (gives `smtp.example.com`).
+
+## Webhooks
+
+Verify a delivery ([Standard Webhooks](https://www.standardwebhooks.com)) using the **raw** request body:
+
+```ruby
+event = Usend::Webhook.verify(
+  payload: request.raw_post,
+  headers: request.headers, # any Hash-like with webhook-id, webhook-timestamp, webhook-signature
+  secret: ENV["USEND_WEBHOOK_SECRET"] # whsec_...
+)
+```
+
+It returns the parsed event, or raises `Usend::Error` (`name: "invalid_webhook"`). The default tolerance is 5
+minutes (`tolerance_seconds:`).
+
+## Tests
+
+```bash
+ruby -Ilib -Itest test/usend_test.rb
+```
+
+Docs: https://usend.et/docs

data/lib/usend/client.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Usend
+  # Client for the usend API.
+  #
+  #   usend = Usend::Client.new(api_key: ENV["USEND_API_KEY"])
+  #   usend.emails.send_email(from: "Acme <hi@acme.com>", to: "ann@example.com", subject: "Hi", html: "<p>Hi</p>")
+  class Client
+    attr_reader :api_key, :base_url, :emails, :events, :automations, :logs, :received, :inboxes, :domains, :api_keys, :templates,
+                :contacts, :contact_properties, :contact_imports, :segments, :topics, :short_links, :audiences, :broadcasts, :webhooks, :suppressions, :tools, :oauth
+
+    # api_key defaults to ENV["USEND_API_KEY"]; base_url to ENV["USEND_BASE_URL"] or https://api.usend.et.
+    # max_retries applies to 429 and 5xx responses and network errors (a POST is only retried after
+    # a 5xx or network error when it carries an idempotency key).
+    def initialize(api_key: nil, base_url: nil, timeout: 30, max_retries: 2)
+      @api_key = api_key || ENV["USEND_API_KEY"]
+      if @api_key.nil? || @api_key.empty?
+        raise Error.new('Missing API key. Pass api_key: or set USEND_API_KEY.', name: "missing_api_key")
+      end
+
+      @base_url = (base_url || ENV["USEND_BASE_URL"] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      http = HTTP.new(api_key: @api_key, base_url: @base_url, timeout: timeout, max_retries: max_retries)
+      @emails = Emails.new(http)
+      @events = Events.new(http)
+      @logs = Logs.new(http)
+      @received = Received.new(http)
+      @inboxes = Inboxes.new(http)
+      @automations = Automations.new(http)
+      @contact_properties = ContactProperties.new(http)
+      @contact_imports = ContactImports.new(http)
+      @tools = Tools.new(http)
+      @oauth = OAuth.new(http)
+      @domains = Domains.new(http)
+      @api_keys = ApiKeys.new(http)
+      @templates = Templates.new(http)
+      @contacts = Contacts.new(http)
+      @segments = Segments.new(http)
+      @topics = Topics.new(http)
+      @short_links = ShortLinks.new(http)
+      @audiences = Audiences.new(http)
+      @broadcasts = Broadcasts.new(http)
+      @webhooks = Webhooks.new(http)
+      @suppressions = Suppressions.new(http)
+    end
+
+    # SMTP settings for this key (see Usend.smtp_settings).
+    def smtp_settings(port: 465, host: nil)
+      Usend.smtp_settings(api_key: @api_key, port: port, host: host, base_url: @base_url)
+    end
+  end
+end

data/lib/usend/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Usend
+  # An error from the usend API ({ statusCode, name, message }). Network failures have
+  # status_code nil and name "application_error".
+  class Error < StandardError
+    attr_reader :status_code, :name
+
+    def initialize(message = "usend error", name: "application_error", status_code: nil)
+      super(message)
+      @name = name
+      @status_code = status_code
+    end
+
+    def inspect
+      "#<Usend::Error status_code=#{status_code.inspect} name=#{name.inspect} message=#{message.inspect}>"
+    end
+  end
+end

data/lib/usend/http.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Usend
+  DEFAULT_BASE_URL = "https://api.usend.et"
+
+  # Minimal HTTP layer: JSON in and out, retries on 429 and 5xx with backoff.
+  class HTTP
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    attr_reader :base_url
+
+    def initialize(api_key:, base_url:, timeout:, max_retries:)
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @max_retries = max_retries
+    end
+
+    # Returns the parsed JSON body (Hash/Array), or {} when empty. Raises Usend::Error.
+    def request(method, path, body: nil, headers: {}, auth: true)
+      uri = URI.parse(@base_url + path)
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          res = perform(uri, method, body, headers, auth)
+        rescue SystemCallError, SocketError, IOError, Timeout::Error, OpenSSL::SSL::SSLError, Net::ProtocolError => e
+          # A POST without an idempotency key may already have been processed: never repeat it.
+          unless retry_safe?(method, headers) && attempt <= @max_retries
+            raise Error.new(e.message.to_s.empty? ? e.class.name : e.message)
+          end
+
+          sleep(backoff(attempt, nil))
+          next
+        end
+        status = res.code.to_i
+        return(res.body.nil? || res.body.empty? ? {} : JSON.parse(res.body)) if status >= 200 && status < 300
+
+        if RETRY_STATUSES.include?(status) && attempt <= @max_retries && (status == 429 || retry_safe?(method, headers))
+          sleep(backoff(attempt, res["retry-after"]))
+          next
+        end
+        raise api_error(res, status)
+      end
+    end
+
+    private
+
+    def perform(uri, method, body, headers, auth)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      req = Net::HTTPGenericRequest.new(method.to_s.upcase, !body.nil?, true, uri.request_uri)
+      req["Authorization"] = "Bearer #{@api_key}" if auth
+      req["User-Agent"] = "usend-ruby/#{VERSION}"
+      req["Accept"] = "application/json"
+      headers.each { |k, v| req[k] = v }
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      http.start { |h| h.request(req) }
+    end
+
+    def retry_safe?(method, headers)
+      method.to_s.upcase != "POST" || headers.key?("Idempotency-Key")
+    end
+
+    def backoff(attempt, retry_after)
+      if retry_after && retry_after.to_s.match?(/\A\d+(\.\d+)?\z/)
+        [retry_after.to_f, 30.0].min
+      else
+        [0.5 * (2**(attempt - 1)), 8.0].min
+      end
+    end
+
+    def api_error(res, status)
+      err = begin
+        JSON.parse(res.body.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+      err = {} unless err.is_a?(Hash)
+      Error.new(err["message"] || "HTTP #{status}", name: err["name"] || "application_error", status_code: status)
+    end
+  end
+end

data/lib/usend/resources.rb

@@ -0,0 +1,623 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "uri"
+
+module Usend
+  # Base for resource objects. Every method returns the API's parsed JSON (Hash or Array)
+  # and raises Usend::Error on failure.
+  class Resource
+    def initialize(http)
+      @http = http
+    end
+
+    private
+
+    def req(method, path, body: nil, headers: {}, auth: true)
+      @http.request(method, path, body: body, headers: headers, auth: auth)
+    end
+
+    def esc(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    def qs(params)
+      pairs = (params || {}).reject { |_, v| v.nil? }
+      pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
+    end
+
+    def idem(key)
+      key ? { "Idempotency-Key" => key } : {}
+    end
+  end
+
+  # Standard create/list/get/update/remove on one path.
+  class Crud < Resource
+    def create(body)
+      req("POST", self.class::PATH, body: body)
+    end
+
+    def list(params = {})
+      req("GET", "#{self.class::PATH}#{qs(params)}")
+    end
+
+    def get(id)
+      req("GET", "#{self.class::PATH}/#{esc(id)}")
+    end
+
+    def update(id, body)
+      req("PATCH", "#{self.class::PATH}/#{esc(id)}", body: body)
+    end
+
+    def remove(id)
+      req("DELETE", "#{self.class::PATH}/#{esc(id)}")
+    end
+  end
+
+  class Emails < Resource
+    # idempotency_key: makes the send safe to retry.
+    #
+    # Takes the email as a Hash or as keywords: send_email(from: "...", to: "...", subject: "...", html: "...").
+    def send_email(email = nil, idempotency_key: nil, **fields)
+      email = fields if email.nil?
+      req("POST", "/emails", body: email, headers: idem(idempotency_key))
+    end
+    alias send send_email
+
+    # validation: "strict" (default) or "permissive".
+    def batch(emails, idempotency_key: nil, validation: nil)
+      headers = idem(idempotency_key)
+      headers["x-batch-validation"] = validation if validation
+      req("POST", "/emails/batch", body: emails, headers: headers)
+    end
+
+    def get(id)
+      req("GET", "/emails/#{esc(id)}")
+    end
+
+    def list(params = {})
+      req("GET", "/emails#{qs(params)}")
+    end
+
+    # Reschedules a scheduled email.
+    def update(id, scheduled_at:)
+      req("PATCH", "/emails/#{esc(id)}", body: { scheduled_at: scheduled_at })
+    end
+
+    def cancel(id)
+      req("POST", "/emails/#{esc(id)}/cancel")
+    end
+
+    def events(id)
+      req("GET", "/emails/#{esc(id)}/events")
+    end
+
+    def attachments(id)
+      req("GET", "/emails/#{esc(id)}/attachments")
+    end
+
+    def attachment(id, attachment_id)
+      req("GET", "/emails/#{esc(id)}/attachments/#{esc(attachment_id)}")
+    end
+
+    # Aggregate sending metrics (start_date, end_date, metrics, dimensions, granularity, ...).
+    def metrics(params = {})
+      req("GET", "/emails/metrics#{qs(params)}")
+    end
+
+    # Creates a public read-only link; expires_in like "10m", "2 hours", "1 day" (max 48h).
+    def share(id, expires_in: nil)
+      req("POST", "/emails/#{esc(id)}/share", body: expires_in ? { expires_in: expires_in } : {})
+    end
+
+    # Sends the content to the signed-in user's own address (dashboard sessions and OAuth tokens).
+    def test(body)
+      req("POST", "/emails/test", body: body)
+    end
+
+    # Deliverability findings for the stored message.
+    def insights(id)
+      req("GET", "/emails/#{esc(id)}/insights")
+    end
+  end
+
+  # Custom events that trigger automations (not email delivery events: see Emails#events).
+  class Events < Crud
+    PATH = "/events"
+
+    # Fires an event for a contact: { event:, contact_id: | email:, payload: }. The API answers 202.
+    def send_event(body)
+      req("POST", "/events/send", body: body)
+    end
+    alias send send_event
+  end
+
+  class Automations < Crud
+    PATH = "/automations"
+
+    def duplicate(id)
+      req("POST", "/automations/#{esc(id)}/duplicate")
+    end
+
+    def stop(id)
+      req("POST", "/automations/#{esc(id)}/stop")
+    end
+
+    def runs(id, params = {})
+      req("GET", "/automations/#{esc(id)}/runs#{qs(params)}")
+    end
+
+    def run(id, run_id)
+      req("GET", "/automations/#{esc(id)}/runs/#{esc(run_id)}")
+    end
+  end
+
+  class ContactProperties < Crud
+    PATH = "/contact-properties"
+  end
+
+  # Bulk contact imports (POST /contacts/imports) and their progress.
+  class ContactImports < Resource
+    def create(body)
+      req("POST", "/contacts/imports", body: body)
+    end
+
+    def list(params = {})
+      req("GET", "/contacts/imports#{qs(params)}")
+    end
+
+    def get(id)
+      req("GET", "/contacts/imports/#{esc(id)}")
+    end
+  end
+
+  # Deliverability tools.
+  class Tools < Resource
+    def dmarc_check(domain)
+      req("POST", "/tools/dmarc-check", body: { domain: domain })
+    end
+  end
+
+  # API request logs: GET /logs.
+  class Logs < Resource
+    def list(params = {})
+      req("GET", "/logs#{qs(params)}")
+    end
+
+    def get(id)
+      req("GET", "/logs/#{esc(id)}")
+    end
+
+    def user_agents
+      req("GET", "/logs/user-agents")
+    end
+  end
+
+  # Received (inbound) emails.
+  class Received < Resource
+    def list(params = {})
+      req("GET", "/inbound/emails#{qs(params)}")
+    end
+
+    def get(id)
+      req("GET", "/inbound/emails/#{esc(id)}")
+    end
+
+    def raw(id)
+      req("GET", "/inbound/emails/#{esc(id)}/raw")
+    end
+
+    def attachment(id, attachment_id)
+      req("GET", "/inbound/emails/#{esc(id)}/attachments/#{esc(attachment_id)}")
+    end
+  end
+
+  # Shared mailboxes with threads, labels, drafts and replies (full-access keys only).
+  class Inboxes < Crud
+    PATH = "/inboxes"
+
+    def create_label(inbox_id, body)
+      req("POST", "/inboxes/#{esc(inbox_id)}/labels", body: body)
+    end
+
+    def labels(inbox_id)
+      req("GET", "/inboxes/#{esc(inbox_id)}/labels")
+    end
+
+    def label(inbox_id, label_id)
+      req("GET", "/inboxes/#{esc(inbox_id)}/labels/#{esc(label_id)}")
+    end
+
+    def update_label(inbox_id, label_id, body)
+      req("PATCH", "/inboxes/#{esc(inbox_id)}/labels/#{esc(label_id)}", body: body)
+    end
+
+    def remove_label(inbox_id, label_id)
+      req("DELETE", "/inboxes/#{esc(inbox_id)}/labels/#{esc(label_id)}")
+    end
+
+    # params: folder, label, assignee, unread, q, limit, after, before
+    def threads(inbox_id, params = {})
+      req("GET", "/inboxes/#{esc(inbox_id)}/threads#{qs(params)}")
+    end
+
+    def thread(inbox_id, thread_id)
+      req("GET", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}")
+    end
+
+    # body: folder, labels, assignee_user_id, read
+    def update_thread(inbox_id, thread_id, body)
+      req("PATCH", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}", body: body)
+    end
+
+    def remove_thread(inbox_id, thread_id)
+      req("DELETE", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}")
+    end
+
+    def thread_emails(inbox_id, thread_id, params = {})
+      req("GET", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}/emails#{qs(params)}")
+    end
+
+    def thread_email(inbox_id, thread_id, email_id)
+      req("GET", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}/emails/#{esc(email_id)}")
+    end
+
+    def reply(inbox_id, thread_id, email_id, body)
+      req("POST", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}/emails/#{esc(email_id)}/reply", body: body)
+    end
+
+    def forward(inbox_id, thread_id, email_id, body)
+      req("POST", "/inboxes/#{esc(inbox_id)}/threads/#{esc(thread_id)}/emails/#{esc(email_id)}/forward", body: body)
+    end
+
+    def create_draft(inbox_id, body)
+      req("POST", "/inboxes/#{esc(inbox_id)}/drafts", body: body)
+    end
+
+    def drafts(inbox_id, params = {})
+      req("GET", "/inboxes/#{esc(inbox_id)}/drafts#{qs(params)}")
+    end
+
+    def draft(inbox_id, draft_id)
+      req("GET", "/inboxes/#{esc(inbox_id)}/drafts/#{esc(draft_id)}")
+    end
+
+    def update_draft(inbox_id, draft_id, body)
+      req("PATCH", "/inboxes/#{esc(inbox_id)}/drafts/#{esc(draft_id)}", body: body)
+    end
+
+    def remove_draft(inbox_id, draft_id)
+      req("DELETE", "/inboxes/#{esc(inbox_id)}/drafts/#{esc(draft_id)}")
+    end
+
+    def send_draft(inbox_id, draft_id)
+      req("POST", "/inboxes/#{esc(inbox_id)}/drafts/#{esc(draft_id)}/send")
+    end
+  end
+
+  class Domains < Crud
+    PATH = "/domains"
+
+    # Domain claim. body: { name: }
+    def create_claim(body)
+      req("POST", "/domains/claim", body: body)
+    end
+
+    def claim(id)
+      req("GET", "/domains/claim/#{esc(id)}")
+    end
+
+    def verify_claim(id)
+      req("POST", "/domains/claim/#{esc(id)}/verify")
+    end
+
+    def insights(id)
+      req("GET", "/domains/#{esc(id)}/insights")
+    end
+
+    def verify(id)
+      req("POST", "/domains/#{esc(id)}/verify")
+    end
+
+    def auto_configure(id, api_token:, provider: "cloudflare")
+      req("POST", "/domains/#{esc(id)}/auto-configure", body: { provider: provider, api_token: api_token })
+    end
+  end
+
+  class ApiKeys < Resource
+    def create(body)
+      req("POST", "/api-keys", body: body)
+    end
+
+    def update(id, body)
+      req("PATCH", "/api-keys/#{esc(id)}", body: body)
+    end
+
+    def list
+      req("GET", "/api-keys")
+    end
+
+    def remove(id)
+      req("DELETE", "/api-keys/#{esc(id)}")
+    end
+  end
+
+  class Templates < Crud
+    PATH = "/templates"
+
+    def publish(id_or_alias)
+      req("POST", "/templates/#{esc(id_or_alias)}/publish")
+    end
+
+    def duplicate(id_or_alias)
+      req("POST", "/templates/#{esc(id_or_alias)}/duplicate")
+    end
+
+    def versions(id_or_alias)
+      req("GET", "/templates/#{esc(id_or_alias)}/versions")
+    end
+
+    def version(id_or_alias, version_id)
+      req("GET", "/templates/#{esc(id_or_alias)}/versions/#{esc(version_id)}")
+    end
+
+    def restore_version(id_or_alias, version_id)
+      req("POST", "/templates/#{esc(id_or_alias)}/versions/#{esc(version_id)}/restore")
+    end
+  end
+
+  class Contacts < Crud
+    PATH = "/contacts"
+
+    def import(csv)
+      req("POST", "/contacts/import", body: { csv: csv })
+    end
+
+    def stats
+      req("GET", "/contacts/stats")
+    end
+
+    def segments(id_or_email)
+      req("GET", "/contacts/#{esc(id_or_email)}/segments")
+    end
+
+    def add_to_segment(id_or_email, segment_id)
+      req("POST", "/contacts/#{esc(id_or_email)}/segments/#{esc(segment_id)}")
+    end
+
+    def remove_from_segment(id_or_email, segment_id)
+      req("DELETE", "/contacts/#{esc(id_or_email)}/segments/#{esc(segment_id)}")
+    end
+
+    def topics(id_or_email)
+      req("GET", "/contacts/#{esc(id_or_email)}/topics")
+    end
+
+    def update_topics(id_or_email, body)
+      req("PATCH", "/contacts/#{esc(id_or_email)}/topics", body: body)
+    end
+  end
+
+  class Segments < Resource
+    def create(body)
+      req("POST", "/segments", body: body)
+    end
+
+    def list
+      req("GET", "/segments")
+    end
+
+    def get(id)
+      req("GET", "/segments/#{esc(id)}")
+    end
+
+    def update(id, body)
+      req("PATCH", "/segments/#{esc(id)}", body: body)
+    end
+
+    def remove(id)
+      req("DELETE", "/segments/#{esc(id)}")
+    end
+
+    # params: limit, after, before, subscription ("subscribed" | "unsubscribed")
+    def contacts(id, params = {})
+      req("GET", "/segments/#{esc(id)}/contacts#{qs(params)}")
+    end
+
+    def metrics(id)
+      req("GET", "/segments/#{esc(id)}/metrics")
+    end
+  end
+
+  class Topics < Crud
+    PATH = "/topics"
+  end
+
+  # Short links on the shared tracking host that redirect to a target URL and count clicks.
+  #
+  #   usend.short_links.create(target_url: "https://acme.com/sale", code: "sale")
+  #
+  # update(id, ...) takes target_url:, title:, disabled:, expires_at: (nil clears the expiry).
+  class ShortLinks < Crud
+    PATH = "/short-links"
+
+    # Click statistics for the last `days` days (1 to 365, default 30).
+    def stats(id, days: nil)
+      req("GET", "/short-links/#{esc(id)}/stats#{qs(days: days)}")
+    end
+  end
+
+  # Audiences (v1 name for segments) and their contacts.
+  class Audiences < Resource
+    def create(body)
+      req("POST", "/audiences", body: body)
+    end
+
+    def list
+      req("GET", "/audiences")
+    end
+
+    def get(id)
+      req("GET", "/audiences/#{esc(id)}")
+    end
+
+    def remove(id)
+      req("DELETE", "/audiences/#{esc(id)}")
+    end
+
+    def create_contact(audience_id, body)
+      req("POST", "/audiences/#{esc(audience_id)}/contacts", body: body)
+    end
+
+    def list_contacts(audience_id, params = {})
+      req("GET", "/audiences/#{esc(audience_id)}/contacts#{qs(params)}")
+    end
+
+    def get_contact(audience_id, id_or_email)
+      req("GET", "/audiences/#{esc(audience_id)}/contacts/#{esc(id_or_email)}")
+    end
+
+    def update_contact(audience_id, id_or_email, body)
+      req("PATCH", "/audiences/#{esc(audience_id)}/contacts/#{esc(id_or_email)}", body: body)
+    end
+
+    def remove_contact(audience_id, id_or_email)
+      req("DELETE", "/audiences/#{esc(audience_id)}/contacts/#{esc(id_or_email)}")
+    end
+
+    def import_contacts(audience_id, csv)
+      req("POST", "/audiences/#{esc(audience_id)}/contacts/import", body: { csv: csv })
+    end
+  end
+
+  class Broadcasts < Crud
+    PATH = "/broadcasts"
+
+    def send_broadcast(id, scheduled_at: nil)
+      req("POST", "/broadcasts/#{esc(id)}/send", body: scheduled_at ? { scheduled_at: scheduled_at } : {})
+    end
+    alias send send_broadcast
+
+    def test(id, to)
+      req("POST", "/broadcasts/#{esc(id)}/test", body: { to: to })
+    end
+
+    def cancel(id)
+      req("POST", "/broadcasts/#{esc(id)}/cancel")
+    end
+
+    def duplicate(id)
+      req("POST", "/broadcasts/#{esc(id)}/duplicate")
+    end
+
+    # type is required: sent, delivered, opened, clicked, bounced, complained, unsubscribed or suppressed.
+    # Rows are { id, contact_id, email, count?, bounce_type?, clicked_links? }. Other params: limit, after,
+    # before, email, bounce_type.
+    def recipients(id, type:, **params)
+      req("GET", "/broadcasts/#{esc(id)}/recipients#{qs(params.merge(type: type))}")
+    end
+
+    def clicked_links(id)
+      req("GET", "/broadcasts/#{esc(id)}/clicked-links")
+    end
+
+    def performance(id)
+      req("GET", "/broadcasts/#{esc(id)}/performance")
+    end
+  end
+
+  class Webhooks < Crud
+    PATH = "/webhooks"
+
+    def deliveries(id, params = {})
+      req("GET", "/webhooks/#{esc(id)}/deliveries#{qs(params)}")
+    end
+
+    def replay(id, delivery_id)
+      req("POST", "/webhooks/#{esc(id)}/deliveries/#{esc(delivery_id)}/replay")
+    end
+
+    # Returns the new signing secret; the old one stops signing at once.
+    def rotate_secret(id)
+      req("POST", "/webhooks/#{esc(id)}/rotate-secret")
+    end
+
+    # Webhook events across endpoints.
+    def events(params = {})
+      req("GET", "/webhooks/events#{qs(params)}")
+    end
+
+    def event(event_id)
+      req("GET", "/webhooks/events/#{esc(event_id)}")
+    end
+
+    def replay_event(event_id)
+      req("POST", "/webhooks/events/#{esc(event_id)}/replay")
+    end
+
+    def event_attempts(event_id)
+      req("GET", "/webhooks/events/#{esc(event_id)}/attempts")
+    end
+
+    # See Usend::Webhook.verify.
+    def verify(**opts)
+      Usend::Webhook.verify(**opts)
+    end
+  end
+
+  class Suppressions < Resource
+    def list(params = {})
+      req("GET", "/suppressions#{qs(params)}")
+    end
+
+    def create(body)
+      req("POST", "/suppressions", body: body)
+    end
+
+    def get(id_or_email)
+      req("GET", "/suppressions/#{esc(id_or_email)}")
+    end
+
+    # emails: up to 100 addresses.
+    def batch_create(emails)
+      req("POST", "/suppressions/batch", body: { emails: emails })
+    end
+
+    def batch_remove(emails)
+      req("DELETE", "/suppressions/batch", body: { emails: emails })
+    end
+
+    def remove(id)
+      req("DELETE", "/suppressions/#{esc(id)}")
+    end
+  end
+
+  # OAuth 2.0 for apps acting on a customer's org (PKCE required). These endpoints take no API key.
+  class OAuth < Resource
+    def metadata
+      req("GET", "/.well-known/oauth-authorization-server", auth: false)
+    end
+
+    # { client_name:, redirect_uris: [...] }
+    def register(body)
+      req("POST", "/oauth/register", body: body, auth: false)
+    end
+
+    # grant_type "authorization_code" (client_id, code, code_verifier, redirect_uri)
+    # or "refresh_token" (client_id, refresh_token)
+    def token(body)
+      req("POST", "/oauth/token", body: body, auth: false)
+    end
+
+    def revoke(token, client_id: nil)
+      req("POST", "/oauth/revoke", body: { token: token, client_id: client_id }.compact, auth: false)
+    end
+
+    # The URL to send the user's browser to.
+    def authorize_url(client_id:, redirect_uri:, scope:, code_challenge:, state: nil)
+      q = { response_type: "code", client_id: client_id, redirect_uri: redirect_uri, scope: scope,
+            code_challenge: code_challenge, code_challenge_method: "S256", state: state }.compact
+      "#{@http.base_url}/oauth/authorize?#{URI.encode_www_form(q)}"
+    end
+  end
+end

data/lib/usend/smtp.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Usend
+  DEFAULT_SMTP_HOST = "smtp.usend.et"
+
+  # SMTP settings for sending through usend; the API key is the password. Port 465 is implicit
+  # TLS (tls: true), 587 is STARTTLS (enable_starttls_auto: true). The host is smtp.usend.et; for a
+  # self-hosted platform pass host:, set USEND_SMTP_HOST, or pass base_url: ("https://api.x.com"
+  # gives "smtp.x.com"). The keys match ActionMailer's smtp_settings.
+  def self.smtp_settings(api_key: nil, port: 465, host: nil, base_url: nil)
+    key = api_key || ENV["USEND_API_KEY"]
+    raise Error.new("Missing API key. Pass api_key: or set USEND_API_KEY.", name: "missing_api_key") if key.nil? || key.empty?
+    raise Error.new("usend accepts SMTP on port 465 (TLS) or 587 (STARTTLS).", name: "invalid_port") unless [465, 587].include?(port)
+
+    {
+      address: host || ENV["USEND_SMTP_HOST"] || smtp_host_for(base_url),
+      port: port,
+      user_name: "usend",
+      password: key,
+      authentication: :plain,
+      tls: port == 465,
+      enable_starttls_auto: port == 587
+    }
+  end
+
+  def self.smtp_host_for(base_url)
+    return DEFAULT_SMTP_HOST if base_url.nil? || base_url.empty?
+
+    hostname = URI.parse(base_url).host.to_s
+    hostname.start_with?("api.") ? "smtp.#{hostname[4..]}" : DEFAULT_SMTP_HOST
+  rescue URI::InvalidURIError
+    DEFAULT_SMTP_HOST
+  end
+end

data/lib/usend/version.rb

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

data/lib/usend/webhook.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module Usend
+  # Standard Webhooks verification.
+  module Webhook
+    # Verifies a delivery and returns the parsed event (a Hash); raises Usend::Error if invalid.
+    # payload must be the raw request body exactly as received; headers is a Hash (any key case;
+    # Rack-style "HTTP_WEBHOOK_ID" keys also work); secret is the endpoint's whsec_... secret.
+    def self.verify(payload:, headers:, secret:, tolerance_seconds: 300)
+      h = headers.each_with_object({}) { |(k, v), m| m[k.to_s.downcase.sub(/\Ahttp_/, "").tr("_", "-")] = v }
+      id = h["webhook-id"]
+      ts = h["webhook-timestamp"]
+      sigs = h["webhook-signature"]
+      raise invalid("Missing webhook-id, webhook-timestamp or webhook-signature header") unless id && ts && sigs
+      raise invalid("Invalid webhook timestamp") unless ts.to_s.match?(/\A\d+\z/)
+      raise invalid("Webhook timestamp is too old or too new") if (Time.now.to_i - ts.to_i).abs > tolerance_seconds
+
+      key = Base64.decode64(secret.to_s.sub(/\Awhsec_/, ""))
+      expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{ts}.#{payload}"))
+      ok = sigs.to_s.split(" ").any? do |part|
+        version, sig = part.split(",", 2)
+        version == "v1" && sig && sig.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(sig, expected)
+      end
+      raise invalid("Invalid webhook signature") unless ok
+
+      JSON.parse(payload)
+    end
+
+    def self.invalid(msg)
+      Error.new(msg, name: "invalid_webhook")
+    end
+    private_class_method :invalid
+  end
+end

data/lib/usend.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "usend/version"
+require "usend/error"
+require "usend/smtp"
+require "usend/webhook"
+require "usend/http"
+require "usend/resources"
+require "usend/client"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: usend
+version: !ruby/object:Gem::Version
+  version: 1.3.0
+platform: ruby
+authors:
+- usend
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-23 00:00:00.000000000 Z
+dependencies: []
+description: Send email, manage domains, templates, contacts, broadcasts and webhooks
+  with usend. Standard library only.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/usend.rb
+- lib/usend/client.rb
+- lib/usend/error.rb
+- lib/usend/http.rb
+- lib/usend/resources.rb
+- lib/usend/smtp.rb
+- lib/usend/version.rb
+- lib/usend/webhook.rb
+homepage: https://usend.et
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/usend/usend-ruby
+  documentation_uri: https://usend.et/docs
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for usend, the email API for developers
+test_files: []