mailengin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88d3555674981032a0373f45f7d3dcde4e8d7d66fc54df3db1518ea1555b4aa7
+  data.tar.gz: 69d7013ba3242bcf870f7355d8749e9e8c66a6f52dd394cdd70d1b643f853e9e
+SHA512:
+  metadata.gz: 42eabe1d62d66e95dfc74b88ebf9fede0a2751b5c4dcad43993d62052a416b8e5951504d83729f0ff0c92d2ed07920c0c1e5784355ff3c15d391c343ad149318
+  data.tar.gz: bc0c863858e5e2d1127e141ed205cb3992fd91f5c75c11ce8e39ee609fbd9be12531db45438e69ac58ac348d720bd67de2960bb5ed07b79784a4a829a5091231

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this gem will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+### Added
+
+- Initial Ruby SDK with keyword-based APIs and immutable response objects.
+- Single and personalized bulk email operations.
+- Template, raw HTML, variables, sender override, and reply-routing support.
+- Structured API, timeout, malformed-response, and network errors.
+- Injectable transport, Minitest, CI, and trusted RubyGems publishing.

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 MailEngin
+
+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,271 @@
+# MailEngin Ruby SDK
+
+[![Ruby](https://img.shields.io/badge/Ruby-3.2%2B-cc342d.svg)](https://www.ruby-lang.org/)
+[![RubyGems](https://img.shields.io/badge/RubyGems-ready-e9573f.svg)](https://rubygems.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-111827.svg)](./LICENSE)
+
+The official Ruby SDK for sending transactional email through [MailEngin](https://mailengin.app). It uses the Ruby standard library and provides keyword-based APIs, immutable response objects, configurable timeouts, injectable transports, and structured errors.
+
+> [!IMPORTANT]
+> This gem is for server-side applications only. Never expose a MailEngin API key in browser, mobile, desktop, or other client-distributed code.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- A MailEngin API key and verified sending domain
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "mailengin", "~> 0.1"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install mailengin
+```
+
+## Before You Send
+
+1. [Verify a sending domain](https://mailengin.app/dashboard/domains).
+2. [Create an API key](https://mailengin.app/dashboard/api-keys) and save the full secret.
+3. [Create and publish a Developer Template](https://mailengin.app/dashboard/dev-templates).
+4. Copy the template API name, such as `welcome-email`.
+
+Store the key in your runtime's secret manager or environment:
+
+```env
+MAILENGIN_API_KEY=re_your_full_secret_key
+```
+
+MailEngin displays the full key only once. A masked key cannot authenticate requests.
+
+## Quick Start
+
+```ruby
+require "mailengin"
+
+client = MailEngin::Client.new(api_key: ENV.fetch("MAILENGIN_API_KEY"))
+
+email = client.emails.send(
+  to: "user@example.com",
+  from_email: "hello@yourdomain.com",
+  template_name: "welcome-email",
+  variables: { first_name: "Asha" }
+)
+
+puts email.id
+```
+
+The published template supplies the subject and HTML. Values in `variables` replace matching template variables such as `{{first_name}}`.
+
+## Send One Email
+
+```ruby
+email = client.emails.send(
+  to: "customer@example.com",
+  from_email: "hello@yourdomain.com",
+  template_name: "account-verification",
+  variables: {
+    first_name: "Asha",
+    verification_url: "https://yourapp.com/verify/token"
+  },
+  reply_to_mailengin: true
+)
+
+puts "Queued email #{email.id} at #{email.created_at}"
+```
+
+### Send keyword arguments
+
+| Keyword | Type | Required | Description |
+| --- | --- | --- | --- |
+| `to` | `String` | Yes | Recipient email address. |
+| `template_name` | `String` | Recommended | Published template API name or exact display name. |
+| `template_id` | `String` | No | Legacy template identifier. Prefer `template_name`. |
+| `variables` | `Hash` | No | Values used to render template variables. |
+| `subject` | `String` | Raw HTML only | Template subject override, or required subject for raw HTML. |
+| `from_email` | `String` | Recommended | Sender on a verified domain authorized for the API key. |
+| `html` | `String` | Advanced | Raw HTML used when no template is supplied. |
+| `reply_to_mailengin` | `true` / `false` | No | Route recipient replies into the MailEngin inbox. |
+
+Exactly one content source is required: `template_name`, `template_id`, or `html`. Raw HTML sends also require `subject`.
+
+## Send Personalized Bulk Email
+
+Bulk requests support up to 1,000 recipients. Request-level variables apply to every recipient; recipient variables take precedence.
+
+```ruby
+job = client.emails.send_bulk(
+  to: [
+    {
+      email: "asha@example.com",
+      variables: { first_name: "Asha" }
+    },
+    {
+      email: "ben@example.com",
+      variables: { first_name: "Ben" }
+    }
+  ],
+  from_email: "hello@yourdomain.com",
+  template_name: "product-update",
+  variables: { product_name: "MailEngin" }
+)
+
+puts "Queued #{job.queued_count} recipients in job #{job.job_id}"
+```
+
+For recipients without individual variables, use strings:
+
+```ruby
+job = client.emails.send_bulk(
+  to: ["a@example.com", "b@example.com"],
+  template_name: "maintenance-notice"
+)
+```
+
+A successful bulk response confirms that recipients were queued. It is not a guarantee that every message was delivered.
+
+## Send Raw HTML
+
+Published templates are recommended for reusable product email. For a one-off message, provide both `subject` and `html`:
+
+```ruby
+email = client.emails.send(
+  to: "user@example.com",
+  from_email: "reports@yourdomain.com",
+  subject: "Your report is ready",
+  html: "<h1>Report ready</h1><p>You can download it now.</p>"
+)
+```
+
+## Sender Selection
+
+MailEngin resolves the sender in this order:
+
+1. `from_email` supplied in the request.
+2. Sender saved in the published Developer Template.
+3. `noreply@<authorized-domain>` fallback.
+
+The sender domain must be verified and authorized for the API key.
+
+## Error Handling
+
+API, timeout, malformed-response, and network failures raise `MailEngin::Error`:
+
+```ruby
+begin
+  client.emails.send(
+    to: "user@example.com",
+    template_name: "welcome-email"
+  )
+rescue MailEngin::Error => error
+  warn error.message
+  warn error.status.inspect       # HTTP status, when available
+  warn error.code.inspect         # Machine-readable error code
+  warn error.request_id.inspect   # Include when contacting support
+  warn error.retry_after.inspect  # Seconds supplied with HTTP 429
+  warn error.body.inspect         # Parsed JSON or response text
+  warn error.retryable?.to_s
+end
+```
+
+`retryable?` is true for network errors, timeouts, HTTP `408`, HTTP `429`, and `5xx` responses. The SDK never retries sends automatically because a retry could create a duplicate email until idempotency keys are supported.
+
+Invalid local input raises `ArgumentError` before an API request is made.
+
+## Configuration
+
+```ruby
+client = MailEngin::Client.new(
+  api_key: ENV.fetch("MAILENGIN_API_KEY"),
+  base_url: "https://api.mailengin.app",
+  timeout: 15
+)
+```
+
+| Keyword | Default | Description |
+| --- | --- | --- |
+| `api_key` | None | Full server-side MailEngin API key. |
+| `base_url` | `https://api.mailengin.app` | Override for local, test, or dedicated environments. |
+| `timeout` | `30` | Open and read timeout in seconds. |
+| `transport` | `MailEngin::Transport` | Injectable object responding to `call`. |
+
+Create one client and reuse it throughout the application.
+
+## Rails Integration
+
+Initialize one client after application configuration is available:
+
+```ruby
+# config/initializers/mailengin.rb
+MAILENGIN = MailEngin::Client.new(
+  api_key: ENV.fetch("MAILENGIN_API_KEY")
+)
+```
+
+For larger applications, register the client in your dependency container instead of relying on a global constant. Keep the API key in Rails credentials or the deployment environment, never in source control.
+
+## Testing With an Injected Transport
+
+Inject a small callable transport to test without a real API key or network request:
+
+```ruby
+response = Struct.new(:code, :body) do
+  def is_a?(type)
+    type == Net::HTTPSuccess || super
+  end
+
+  def [](name)
+    nil
+  end
+end
+
+transport = lambda do |uri:, request:, timeout:|
+  response.new(
+    "200",
+    JSON.generate(
+      id: "email_123",
+      from: "hello@example.com",
+      to: "user@example.com",
+      template_name: "welcome-email",
+      created_at: "2026-08-31T12:00:00Z"
+    )
+  )
+end
+
+client = MailEngin::Client.new(api_key: "test_key", transport: transport)
+```
+
+The repository Minitest suite contains complete transport examples for success, errors, and timeouts.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+gem build mailengin.gemspec
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution rules and [PUBLISHING.md](./PUBLISHING.md) for maintainer release instructions.
+
+## Resources
+
+- [MailEngin API documentation](https://mailengin.app/dashboard/docs)
+- [Developer Templates](https://mailengin.app/dashboard/dev-templates)
+- [API keys](https://mailengin.app/dashboard/api-keys)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
+
+## License
+
+Released under the [MIT License](./LICENSE). Copyright 2026 MailEngin.

data/lib/mailengin/client.rb

@@ -0,0 +1,58 @@
+require "json"
+require "net/http"
+require "uri"
+require_relative "error"
+require_relative "emails"
+require_relative "transport"
+require_relative "version"
+
+module MailEngin
+  class Client
+    DEFAULT_BASE_URL = "https://api.mailengin.app"
+
+    attr_reader :emails
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30, transport: Transport.new)
+      raise ArgumentError, "MailEngin requires a non-empty api_key" if api_key.to_s.strip.empty?
+      raise ArgumentError, "MailEngin timeout must be positive" unless timeout.positive?
+      @api_key = api_key.strip
+      @base_url = base_url.sub(%r{/+$}, "")
+      @timeout = timeout
+      @transport = transport
+      @emails = Emails.new(self)
+    end
+
+    def post(path, body)
+      uri = URI(@base_url + path)
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"] = "application/json"
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "mailengin-ruby/#{VERSION}"
+      request.body = JSON.generate(body)
+      response = @transport.call(uri: uri, request: request, timeout: @timeout)
+      parsed = parse(response.body)
+      unless response.is_a?(Net::HTTPSuccess)
+        message = parsed.is_a?(Hash) && parsed["message"].is_a?(String) ? parsed["message"] : "MailEngin API request failed with status #{response.code}."
+        code = parsed.is_a?(Hash) && parsed["code"].is_a?(String) ? parsed["code"] : nil
+        retry_after = Float(response["Retry-After"], exception: false)
+        raise Error.new(message, status: response.code.to_i, code: code, request_id: response["x-request-id"], retry_after: retry_after, body: parsed)
+      end
+      raise Error.new("MailEngin API returned invalid JSON.", code: "invalid_response", body: response.body) unless parsed.is_a?(Hash)
+      parsed
+    rescue Net::OpenTimeout, Net::ReadTimeout => error
+      raise Error.new("MailEngin request timed out.", code: "request_timeout", cause: error)
+    rescue SocketError, SystemCallError, IOError => error
+      raise Error.new("Unable to reach the MailEngin API.", code: "network_error", cause: error)
+    end
+
+    private
+
+    def parse(raw)
+      return nil if raw.nil? || raw.empty?
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raw
+    end
+  end
+end

data/lib/mailengin/emails.rb

@@ -0,0 +1,65 @@
+module MailEngin
+  SendEmailResponse = Data.define(:id, :from, :to, :template_name, :created_at)
+  SendBulkEmailResponse = Data.define(:success, :job_id, :queued_count, :sent_count, :failed_count, :template_name, :message)
+
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    def send(to:, template_name: nil, template_id: nil, variables: nil, subject: nil, from_email: nil, html: nil, reply_to_mailengin: nil)
+      raise ArgumentError, "mailengin.emails.send requires to" if to.to_s.strip.empty?
+      require_content(template_name, template_id, html, subject)
+      body = compact(
+        to: to, template_name: template_name, template_id: template_id, variables: variables,
+        subject: subject, from_email: from_email, html: html, reply_to_mailengin: reply_to_mailengin
+      )
+      data = @client.post("/api/developer/send", body)
+      SendEmailResponse.new(
+        id: data.fetch("id"), from: data.fetch("from"), to: data.fetch("to"),
+        template_name: data["template_name"], created_at: data.fetch("created_at")
+      )
+    rescue KeyError, TypeError => error
+      raise Error.new("MailEngin API returned an invalid response.", code: "invalid_response", body: data, cause: error)
+    end
+
+    def send_bulk(to:, template_name: nil, template_id: nil, variables: nil, subject: nil, from_email: nil, html: nil, reply_to_mailengin: nil)
+      raise ArgumentError, "mailengin.emails.send_bulk requires recipients" unless to.is_a?(Array) && !to.empty?
+      raise ArgumentError, "mailengin.emails.send_bulk accepts up to 1000 recipients" if to.length > 1_000
+      recipients = to.map do |recipient|
+        if recipient.is_a?(String)
+          raise ArgumentError, "every bulk recipient requires an email" if recipient.strip.empty?
+          recipient
+        else
+          email = recipient[:email] || recipient["email"]
+          raise ArgumentError, "every bulk recipient requires an email" if email.to_s.strip.empty?
+          compact(email: email, variables: recipient[:variables] || recipient["variables"])
+        end
+      end
+      require_content(template_name, template_id, html, subject)
+      data = @client.post("/api/developer/send-bulk", compact(
+        to: recipients, template_name: template_name, template_id: template_id, variables: variables,
+        subject: subject, from_email: from_email, html: html, reply_to_mailengin: reply_to_mailengin
+      ))
+      SendBulkEmailResponse.new(
+        success: data.fetch("success"), job_id: data.fetch("jobId"), queued_count: data.fetch("queued_count"),
+        sent_count: data["sent_count"], failed_count: data["failed_count"],
+        template_name: data["template_name"], message: data.fetch("message")
+      )
+    rescue KeyError, TypeError => error
+      raise Error.new("MailEngin API returned an invalid response.", code: "invalid_response", body: data, cause: error)
+    end
+
+    private
+
+    def require_content(template_name, template_id, html, subject)
+      has_template = !template_name.to_s.strip.empty? || !template_id.to_s.strip.empty?
+      raise ArgumentError, "provide template_name, template_id, or html" if !has_template && html.to_s.strip.empty?
+      raise ArgumentError, "raw HTML sends require subject" if !has_template && subject.to_s.strip.empty?
+    end
+
+    def compact(values)
+      values.reject { |_, value| value.nil? }
+    end
+  end
+end

data/lib/mailengin/error.rb

@@ -0,0 +1,19 @@
+module MailEngin
+  class Error < StandardError
+    attr_reader :status, :code, :request_id, :retry_after, :body
+
+    def initialize(message, status: nil, code: nil, request_id: nil, retry_after: nil, body: nil, cause: nil)
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @retry_after = retry_after
+      @body = body
+      set_backtrace(cause.backtrace) if cause
+    end
+
+    def retryable?
+      %w[network_error request_timeout].include?(code) || [408, 429].include?(status) || (!status.nil? && status >= 500)
+    end
+  end
+end

data/lib/mailengin/transport.rb

@@ -0,0 +1,11 @@
+require "net/http"
+
+module MailEngin
+  class Transport
+    def call(uri:, request:, timeout:)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) do |http|
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/mailengin/version.rb

@@ -0,0 +1,3 @@
+module MailEngin
+  VERSION = "0.1.0"
+end

data/lib/mailengin.rb

@@ -0,0 +1,6 @@
+require_relative "mailengin/client"
+require_relative "mailengin/error"
+require_relative "mailengin/version"
+
+module MailEngin
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: mailengin
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MailEngin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Server-side Ruby client for sending transactional email through MailEngin.
+email:
+- support@mailengin.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mailengin.rb
+- lib/mailengin/client.rb
+- lib/mailengin/emails.rb
+- lib/mailengin/error.rb
+- lib/mailengin/transport.rb
+- lib/mailengin/version.rb
+homepage: https://mailengin.app
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mailengin/mailengin-ruby-sdk
+  bug_tracker_uri: https://github.com/mailengin/mailengin-ruby-sdk/issues
+  documentation_uri: https://mailengin.app/dashboard/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Official Ruby SDK for the MailEngin Email API
+test_files: []