utobo-email 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f99b1c98483d5c62504904bd4cbb735d1a50e8260f98b2f6926897d852a0b89
+  data.tar.gz: 5fe4c2dfb7c4fe3b1a891db293a9703e867baa9acf644ab850f29b2faabc269c
+SHA512:
+  metadata.gz: 7923f8b1cbc0b50825859fae50aa278acfecdc8bda4308f7604d7c66e2998cb0387403b6af9d1d38d92bc2bd2224c4024ab77fb864df13e9293f59d97e01f1dd
+  data.tar.gz: 2e4bcb8efab5946163cdc638781b5d98800ae5203228480a9473d9889db89ff48b6097fa382f4dd79a18e54adc6087ba3110ab713a40d5f079ca1146a58180ad

data/README.md

@@ -0,0 +1,50 @@
+# utobo-email
+
+Official Ruby SDK for the [utobo email](https://utobo.com/email) email platform.
+
+## Install
+
+```bash
+gem install utobo-email
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "utobo-email"
+```
+
+## Quickstart
+
+```ruby
+require "utobo_email"
+
+client = UtoboEmail.new("av_live_...")
+
+result = client.emails.send(
+  from: "Acme <noreply@acme.com>",
+  to: "user@example.com",
+  subject: "Welcome!",
+  html: "<p>Welcome to Acme!</p>"
+)
+
+puts result["id"]
+```
+
+## Check delivery status
+
+```ruby
+status = client.emails.get("3c9b0f4e-...")
+puts status["status"]  # "sent" | "failed"
+```
+
+## Configuration
+
+| Option | Env var | Default |
+|--------|---------|---------|
+| `api_key` (1st arg) | `UTOBO_EMAIL_API_KEY` | — (required) |
+| `base_url:` | `UTOBO_EMAIL_BASE_URL` | `https://api.email.utobo.com/v1` |
+
+## License
+
+MIT

data/lib/utobo_email/client.rb

@@ -0,0 +1,69 @@
+require "net/http"
+require "uri"
+require "json"
+
+module UtoboEmail
+  class Client
+    DEFAULT_BASE_URL = "https://api.email.utobo.com/v1"
+    SDK_VERSION = "1.0.0"
+
+    attr_reader :emails
+
+    def initialize(api_key = nil, base_url: nil)
+      @api_key = api_key || ENV["UTOBO_EMAIL_API_KEY"] || ENV["UTOBO_MAIL_API_KEY"]
+      raise ArgumentError, <<~MSG.strip if @api_key.nil? || @api_key.empty?
+        Missing API key. Pass it to UtoboEmail.new("av_live_...") or set UTOBO_EMAIL_API_KEY.
+      MSG
+
+      @base_url = base_url || ENV["UTOBO_EMAIL_BASE_URL"] || ENV["UTOBO_MAIL_BASE_URL"] || DEFAULT_BASE_URL
+      @emails = Emails.new(self)
+    end
+
+    # @api private
+    def post(path, body)
+      uri = URI("#{@base_url}#{path}")
+      req = Net::HTTP::Post.new(uri)
+      set_headers(req)
+      req.body = JSON.generate(body)
+      execute(uri, req)
+    end
+
+    # @api private
+    def get(path)
+      uri = URI("#{@base_url}#{path}")
+      req = Net::HTTP::Get.new(uri)
+      set_headers(req)
+      execute(uri, req)
+    end
+
+    private
+
+    def set_headers(req)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Content-Type"] = "application/json"
+      req["User-Agent"] = "utobo-email-ruby/#{SDK_VERSION}"
+    end
+
+    def execute(uri, req)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      resp = http.request(req)
+      body = JSON.parse(resp.body) rescue {}
+
+      if resp.code.to_i >= 400
+        raise ApiError.new(
+          status_code: resp.code.to_i,
+          name: body["name"] || "api_error",
+          message: body["message"] || "Request failed"
+        )
+      end
+
+      body
+    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError, e.message
+    end
+  end
+end

data/lib/utobo_email/emails.rb

@@ -0,0 +1,45 @@
+module UtoboEmail
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    # Send a transactional email.
+    #
+    # @param from [String] Sender address ("Name <email>" format)
+    # @param to [String, Array<String>] Recipient(s)
+    # @param subject [String] Email subject
+    # @param html [String, nil] HTML body
+    # @param text [String, nil] Plain-text body
+    # @param reply_to [String, Array<String>, nil]
+    # @param cc [String, Array<String>, nil]
+    # @param bcc [String, Array<String>, nil]
+    # @param attachments [Array<Hash>, nil] Each hash requires :filename and :content (base64), optional :contentType
+    # @param headers [Hash, nil] Custom email headers
+    # @return [Hash] { "id" => "...", "message" => "..." }
+    def send(from:, to:, subject:, html: nil, text: nil, reply_to: nil, cc: nil, bcc: nil, attachments: nil, headers: nil)
+      body = {
+        from: from,
+        to: Array(to),
+        subject: subject,
+      }
+      body[:html] = html if html
+      body[:text] = text if text
+      body[:reply_to] = Array(reply_to) if reply_to
+      body[:cc] = Array(cc) if cc
+      body[:bcc] = Array(bcc) if bcc
+      body[:attachments] = attachments if attachments
+      body[:headers] = headers if headers
+
+      @client.post("/send-email", body)
+    end
+
+    # Retrieve the status of a previously sent email.
+    #
+    # @param id [String] The email ID returned by send()
+    # @return [Hash] { "id", "from", "to", "subject", "status", "ses_message_id", "created_at" }
+    def get(id)
+      @client.get("/send-email/#{id}")
+    end
+  end
+end

data/lib/utobo_email/errors.rb

@@ -0,0 +1,19 @@
+module UtoboEmail
+  class Error < StandardError; end
+
+  class ApiError < Error
+    attr_reader :status_code, :name
+
+    def initialize(status_code:, name:, message:)
+      @status_code = status_code
+      @name = name
+      super("#{name} (#{status_code}): #{message}")
+    end
+  end
+
+  class NetworkError < Error
+    def initialize(msg = "Unable to reach the utobo email API")
+      super(msg)
+    end
+  end
+end

data/lib/utobo_email.rb

@@ -0,0 +1,11 @@
+require_relative "utobo_email/client"
+require_relative "utobo_email/emails"
+require_relative "utobo_email/errors"
+
+module UtoboEmail
+  VERSION = "1.0.0"
+
+  def self.new(api_key = nil, base_url: nil)
+    Client.new(api_key, base_url: base_url)
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: utobo-email
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Utobo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-09 00:00:00.000000000 Z
+dependencies: []
+description: Send transactional emails and check delivery status via the utobo email
+  API.
+email: hello@mail.utobo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/utobo_email.rb
+- lib/utobo_email/client.rb
+- lib/utobo_email/emails.rb
+- lib/utobo_email/errors.rb
+homepage: https://utobo.com/email
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/myutobo/utobo-email-ruby
+  bug_tracker_uri: https://github.com/myutobo/utobo-email-ruby/issues
+  documentation_uri: https://utobo.com/email/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.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for the utobo email Email Platform
+test_files: []