unione-rails 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c8d33828c26cc73b7a60e6eda7fb390bbc11355ee8c59c390579eb9a304f1434
+  data.tar.gz: f26567d24240704ee28d003cfb70a1192393661a7ad4d7f0a9c0182e725d2c4c
+SHA512:
+  metadata.gz: 5f18c81a7d3ce510e6e14100ae72c5886d9c69f4b4920d74523595e40d1a4638ef840cc93c2178ae8ce65bd4d7101190e5eac7e13ebbd80cbcad886204f2c729
+  data.tar.gz: da6fd0b07611a2d119bb094b18f77880a0b05291f31638aab1924c80b63484286cc56d05e3b9494c1715adfd534416b6cad32e77736dca7d35c14d2993a3f3a1

data/AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+UniOne Ruby on Rails — Ruby on Rails integration of the UniOne Ruby SDK (`unione`) for the UniOne transactional email Web API (Web API 1.90).
+
+## Working on this repository
+
+- **Generated code.** The whole package is generated by the UniOne team from the UniOne Web API OpenAPI spec (Web API 1.90): sources, docs, README.md and this file. Do not hand-edit it: the next release replaces the content of this repository. Report problems and requests in the issues of this repository (https://github.com/unione-repo/unione-rails).
+- **Build and check:**
+
+  ```bash
+  gem build *.gemspec
+  ```
+
+- **Source label.** Every request carries the query parameter `platform=rails.1.1.3,ruby-sdk.1.1.3` (this package, then the SDK it is built on).
+- **Tests.** Before a release the generator installs the package into a test app of Ruby on Rails and checks the client, the webhook endpoint and the mailer against a mock of the API: no real API key, no real sends.
+- **Release.** The version (1.1.3 in the gemspec) and the tag `v1.1.3` come from the generator; README.md states the Web API version the release was generated from.
+- **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
+
+## Integrating UniOne with this package
+
+Full guide: [README.md](README.md). Ruby on Rails integration of the [UniOne Ruby SDK](https://github.com/unione-repo/unione-ruby-sdk) (`unione`): the API client in the application config (`config.unione`), a webhook endpoint with signature check, a Action Mailer transport that sends through `email/send`.
+
+Install:
+
+```bash
+bundle add unione-rails
+```
+
+Requirements: Ruby 2.7+, Rails 6.1+.
+
+Rules that generated code must follow:
+
+- Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
+- Base URL `https://api.unione.io/en/transactional/api/v1` (an account registered on another host uses that one: `eu1.unione.io`, `us1.unione.io`); every method is POST with a JSON body; auth header `X-API-KEY`. The package does all of it.
+- First email without DNS: `domain/get-sandbox-domain` → `confirmed-email/create` (the user clicks the link within 48 hours) → `email/send` from `noreply@<sandbox-domain>` to the confirmed address. Account API key only; up to 10 confirmed addresses, 100 emails a day; the domain expires after 31 days.
+- Never ship a sandbox domain as the production sender (it is not in `domain/list`); read `from_email` from config. Production needs a verified domain: `domain/get-dns-records` → DNS records → `domain/validate-verification-record`, `domain/validate-dkim` → `domain/list`.
+- Set `message.idempotence_key` on retryable sends; retry network errors, `429` and `5xx` with backoff, not other errors unchanged. Up to 500 recipients and 10 MB per request, each attachment up to 7 MB; always `body.html` or `body.plaintext`.
+- Delivery events via webhook (`webhook/set`), not polling; the webhook endpoint of this package checks the `auth` signature of every notification.
+- Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
+- Do not invent methods or fields. Check the [README](README.md), the [API reference](https://docs.unione.io/en/web-api-ref) or [llms.txt](https://docs.unione.io/llms.txt).
+
+### Configuration
+
+The API key goes to `UNIONE_API_KEY`.
+
+```ruby
+# .env / environment: UNIONE_API_KEY=YOUR_API_KEY
+# or config/application.rb:
+config.unione.api_key = ENV.fetch('UNIONE_API_KEY')
+config.unione.host = 'us1.unione.io'
+config.action_mailer.delivery_method = :unione
+```
+
+| Option | Environment variable | Default | Description |
+|---|---|---|---|
+| `config.unione.api_key` | `UNIONE_API_KEY` |  | User or project API key (required). |
+| `config.unione.host` | `UNIONE_HOST` | `api.unione.io` | API host (datacenter: `api.unione.io`, `eu1.unione.io`, `us1.unione.io`) or a full base URL. |
+| `config.unione.timeout` | `UNIONE_TIMEOUT` | `30` | Request timeout, seconds. |
+| `config.unione.webhook_key` | `UNIONE_WEBHOOK_KEY` |  | API key the webhooks are signed with (the key of the user/project of the webhook), if it differs from the API key. |
+| `config.unione.webhook_path` | `UNIONE_WEBHOOK_PATH` | `/unione/webhook` | Path of the webhook endpoint. |
+
+### Sending mail
+
+Messages of the Action Mailer go through [email/send](https://docs.unione.io/en/web-api-ref#email-send): from, to/cc/bcc, reply-to, subject, HTML and text parts, attachments, inline images and `X-*` headers.
+
+```ruby
+class OrderMailer < ApplicationMailer
+  def shipped(order)
+    headers['X-Order-Id'] = order.id.to_s
+    attachments['invoice.pdf'] = order.invoice_pdf
+    mail(to: order.email, cc: order.manager_email, subject: 'Order shipped')
+  end
+end
+
+message = OrderMailer.shipped(order).deliver_now
+message.delivery_method.response['job_id']
+```
+
+### Webhooks
+
+The endpoint answers `GET` with 200 OK (the URL check of [webhook/set](https://docs.unione.io/en/web-api-ref#webhook-set)) and accepts the `POST` notifications: it checks the `auth` field (MD5 of the request body in which the `auth` value is replaced by the API key), answers 401 to a wrong signature, and passes the notification and each of its events to the application.
+
+```ruby
+# config/initializers/unione.rb
+ActiveSupport::Notifications.subscribe('event.unione') do |*, payload|
+  event = payload[:event]
+  data = event.event_data
+  Rails.logger.info("UniOne #{event.event_name}: #{data&.email} #{data&.status}")
+end
+```
+
+Register the URL of the endpoint with `webhook/set`, e.g. `https://example.com/unione/webhook`.
+
+### Reference
+
+- [UniOne Ruby SDK](https://github.com/unione-repo/unione-ruby-sdk): every API method, models, errors ([AGENTS.md](https://github.com/unione-repo/unione-ruby-sdk/blob/HEAD/AGENTS.md))
+- [API reference](https://docs.unione.io/en/web-api-ref)
+- [Full API reference for LLMs](https://docs.unione.io/llms-full.txt)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 UniOne
+
+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,274 @@
+# UniOne Ruby on Rails 1.1.3
+
+Web API 1.90
+
+Quickstart guide: [Send emails with Ruby](https://docs.unione.io/en/send-with-ruby) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt) · [API reference](https://docs.unione.io/en/web-api-ref)
+
+Ruby on Rails integration of the [UniOne Ruby SDK](https://github.com/unione-repo/unione-ruby-sdk) (`unione`): the API client in the application config (`config.unione`), a webhook endpoint with signature check, a Action Mailer transport that sends through `email/send`.
+
+## Install
+
+```bash
+bundle add unione-rails
+```
+
+Requirements: Ruby 2.7+, Rails 6.1+.
+
+## Get an API key
+
+1. Sign up at [cp.unione.io](https://cp.unione.io/en/user/registration/).
+2. Copy your API key from [Settings → Security → API](https://cp.unione.io/en/settings/security/api).
+3. Put it in an environment variable:
+
+```bash
+export UNIONE_API_KEY="your-api-key"
+```
+
+The package reads it from `UNIONE_API_KEY` (see the configuration below).
+
+> **Server-side only.** Use this package in backend code: API routes, server functions, workers.
+> Never ship the API key to a browser or a mobile app, and never commit it.
+
+## Configuration
+
+Settings are read from the environment by default:
+
+```ruby
+# .env / environment: UNIONE_API_KEY=YOUR_API_KEY
+# or config/application.rb:
+config.unione.api_key = ENV.fetch('UNIONE_API_KEY')
+config.unione.host = 'us1.unione.io'
+config.action_mailer.delivery_method = :unione
+```
+
+| Option | Environment variable | Default | Description |
+|---|---|---|---|
+| `config.unione.api_key` | `UNIONE_API_KEY` |  | User or project API key (required). |
+| `config.unione.host` | `UNIONE_HOST` | `api.unione.io` | API host (datacenter: `api.unione.io`, `eu1.unione.io`, `us1.unione.io`) or a full base URL. |
+| `config.unione.timeout` | `UNIONE_TIMEOUT` | `30` | Request timeout, seconds. |
+| `config.unione.webhook_key` | `UNIONE_WEBHOOK_KEY` |  | API key the webhooks are signed with (the key of the user/project of the webhook), if it differs from the API key. |
+| `config.unione.webhook_path` | `UNIONE_WEBHOOK_PATH` | `/unione/webhook` | Path of the webhook endpoint. |
+
+The API key can also be stored in the credentials (`unione: { api_key: ... }`). The webhook route `unione_webhook` is a Rack endpoint (no CSRF, no session); `config.unione.webhook_enabled = false` turns it off.
+
+## Send your first email — no DNS setup
+
+Every account can send test email right away from a **sandbox domain**: pre-verified, DKIM and SPF already set.
+It delivers only to addresses you confirm.
+
+The examples use the API client of the package (see the configuration above).
+
+**1. Get your sandbox domain** (`domain/get-sandbox-domain`). The call creates the domain on first use and returns the same one afterwards.
+
+```ruby
+response = UniOne::Wrapper.client.domain.get_sandbox_domain
+puts response.domain
+```
+
+**2. Confirm your inbox** (`confirmed-email/create`). UniOne sends a confirmation email; click the link in it within 48 hours.
+
+```ruby
+ConfirmedEmail = UniOne::Api::ConfirmedEmail::Model
+
+response = UniOne::Wrapper.client.confirmed_email.create(ConfirmedEmail::ConfirmedEmailRequest.new(
+  email: 'you@example.com'
+))
+puts response.status
+```
+
+Check the status with `confirmed-email/list` — your address should show `"status": "confirmed"`.
+
+**3. Send the email** (`email/send`) from any address on the sandbox domain to the confirmed address.
+
+```ruby
+Common = UniOne::Common::Model
+Email = UniOne::Api::Email::Model
+
+response = UniOne::Wrapper.client.email.send_email(Email::EmailSendRequest.new(
+  message: Email::MessageObject.new(
+    recipients: [
+      Email::MessageObjectRecipientsItem.new(
+        email: 'you@example.com'
+      )
+    ],
+    body: Common::BodyObject.new(
+      html: '<p>It works!</p>'
+    ),
+    subject: 'Hello from UniOne',
+    from_email: 'noreply@<sandbox-domain>'
+  )
+))
+puts response.job_id
+```
+
+### What you get back
+
+```json
+{
+  "status": "success",
+  "job_id": "1ZymBc-00041N-9X",
+  "emails": [
+    "you@example.com"
+  ]
+}
+```
+
+On error the API returns `status: "error"`, a `message` and a numeric `code`:
+
+```json
+{
+  "status": "error",
+  "code": 102,
+  "message": "Error ID:83274F98-C7D5-11F1-B221-6214FF8707B1. Can not decode key wrongkey"
+}
+```
+
+### Same flow with curl
+
+```bash
+BASE=https://api.unione.io/en/transactional/api/v1
+
+curl -s -X POST $BASE/domain/get-sandbox-domain.json \
+  -H "Content-Type: application/json" -H "X-API-KEY: $UNIONE_API_KEY" -d '{}'
+
+curl -s -X POST $BASE/confirmed-email/create.json \
+  -H "Content-Type: application/json" -H "X-API-KEY: $UNIONE_API_KEY" \
+  -d '{"email": "you@example.com"}'
+
+curl -s -X POST $BASE/email/send.json \
+  -H "Content-Type: application/json" -H "X-API-KEY: $UNIONE_API_KEY" \
+  -d '{
+        "message": {
+          "recipients": [
+            {
+              "email": "you@example.com"
+            }
+          ],
+          "from_email": "noreply@<sandbox-domain>",
+          "subject": "Hello from UniOne",
+          "body": {
+            "html": "<p>It works!</p>"
+          }
+        }
+      }'
+```
+
+## Sending mail
+
+Messages of the Action Mailer go through [email/send](https://docs.unione.io/en/web-api-ref#email-send): from, to/cc/bcc, reply-to, subject, HTML and text parts, attachments, inline images and `X-*` headers.
+
+```ruby
+class OrderMailer < ApplicationMailer
+  def shipped(order)
+    headers['X-Order-Id'] = order.id.to_s
+    attachments['invoice.pdf'] = order.invoice_pdf
+    mail(to: order.email, cc: order.manager_email, subject: 'Order shipped')
+  end
+end
+
+message = OrderMailer.shipped(order).deliver_now
+message.delivery_method.response['job_id']
+```
+
+## Webhooks
+
+The endpoint answers `GET` with 200 OK (the URL check of [webhook/set](https://docs.unione.io/en/web-api-ref#webhook-set)) and accepts the `POST` notifications: it checks the `auth` field (MD5 of the request body in which the `auth` value is replaced by the API key), answers 401 to a wrong signature, and passes the notification and each of its events to the application.
+
+```ruby
+# config/initializers/unione.rb
+ActiveSupport::Notifications.subscribe('event.unione') do |*, payload|
+  event = payload[:event]
+  data = event.event_data
+  Rails.logger.info("UniOne #{event.event_name}: #{data&.email} #{data&.status}")
+end
+```
+
+Register the URL of the endpoint with `webhook/set`, e.g. `https://example.com/unione/webhook`.
+
+## API client
+
+Every section of the API is available on the client, see the [SDK docs](https://github.com/unione-repo/unione-ruby-sdk).
+
+```ruby
+client = UniOne::Wrapper.client
+info = client.system.info
+puts info.accounting&.emails_sent
+```
+
+## Sending through the API
+
+Besides the Action Mailer, mail can be sent through the API client directly. The client calls [email/send](https://docs.unione.io/en/web-api-ref#email-send) with all of its options: templates, substitutions, metadata, tracking. Fields of the request and other examples: [Ruby SDK docs](https://github.com/unione-repo/unione-ruby-sdk/blob/HEAD/docs/Email.md#send_email).
+
+```ruby
+Common = UniOne::Common::Model
+Email = UniOne::Api::Email::Model
+
+response = UniOne::Wrapper.client.email.send_email(Email::EmailSendRequest.new(
+  message: Email::MessageObject.new(
+    recipients: [
+      Email::MessageObjectRecipientsItem.new(
+        email: 'user@example.com',
+        substitutions: {
+          'CustomerId' => '12452',
+          'to_name' => 'John Smith',
+        }
+      )
+    ],
+    body: Common::BodyObject.new(
+      html: '<b>Hello, {{to_name}}</b>',
+      plaintext: 'Hello, {{to_name}}'
+    ),
+    subject: 'UniOne test email ',
+    from_email: 'email@example.com',
+    from_name: 'John Smith'
+  )
+))
+puts response.job_id
+```
+
+## Sandbox limits
+
+- Sends only to confirmed addresses: up to 10 per account.
+- Up to 100 emails a day.
+- The sandbox domain expires after 31 days; call `domain/get-sandbox-domain` again to get a new one.
+- Works only with the account API key, not a project key.
+- Not listed in `domain/list`; the other `domain/*` methods do not apply to it.
+
+The sandbox is for development and testing. Do not use a sandbox domain as the sender in production.
+
+## Before production: verify your domain
+
+1. `domain/get-dns-records` — returns the values for your DNS records.
+2. Add these records at your DNS provider (the domain page of the control panel shows them too):
+
+   | Type | Host | Value |
+   |---|---|---|
+   | TXT | `@` | the `verification-record` value (`unione-validate-hash=…`) |
+   | TXT | `<selector>._domainkey` (the selector is on the domain page of the control panel, e.g. `us`) | `v=DKIM1; k=rsa; p=<dkim>` |
+   | TXT | `@` | `v=spf1 include:spf.unione.io ~all` |
+   | CNAME | `_dmarc` | the `dmarc` value |
+
+3. `domain/validate-verification-record`, then `domain/validate-dkim`.
+4. `domain/list` — wait until the verification record is confirmed and DKIM is active.
+5. Read `from_email` from your config, so switching from the sandbox needs no code change.
+
+## Sending reliably
+
+- **Retries:** set `message.idempotence_key` on sends that may be retried, so a repeated request does not send twice.
+- **Limits:** up to 500 recipients and 10 MB per request; each attachment up to 7 MB.
+- **Body:** always include `body.html` or `body.plaintext`.
+- **Delivery status:** register a webhook (`webhook/set`) with a fast, idempotent HTTPS handler instead of polling.
+- **Defaults:** keep the default unsubscribe footer and tracking; changing them requires UniOne support.
+- **Errors:** retry `429` and `5xx` with backoff; do not retry other errors unchanged.
+
+## Links
+
+- [Send emails with Ruby](https://docs.unione.io/en/send-with-ruby) and other [integration guides](https://docs.unione.io/en/integrations/)
+- [Web API reference](https://docs.unione.io/en/web-api-ref)
+- [llms.txt](https://docs.unione.io/llms.txt) for AI coding agents
+- [UniOne MCP server and agent setup](https://unione.io/en/agents)
+- [Support](https://cp.unione.io/en/support)
+
+## For package contributors
+
+See [AGENTS.md](AGENTS.md): how this package is generated from the OpenAPI spec, built, tested and released.

data/lib/unione/wrapper/delivery_method.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Wrapper
+    # Action Mailer delivery method :unione, sends through email/send:
+    #
+    #   config.action_mailer.delivery_method = :unione
+    #   config.action_mailer.unione_settings = { api_key: '...' } # optional, default: config.unione
+    #
+    # The API response ("job_id", "emails", "failed_emails") is in mail.delivery_method.response.
+    class DeliveryMethod
+      attr_accessor :settings
+      attr_reader :response
+
+      def initialize(settings = {})
+        @settings = settings || {}
+        @response = nil
+      end
+
+      def deliver!(mail)
+        @response = client.api_client.call('/email/send.json', { 'message' => EmailPayload.from_mail(mail) })
+      end
+
+      private
+
+      def client
+        return ::UniOne::Wrapper.client if @settings[:api_key].nil?
+
+        ::UniOne::Wrapper.build_client(@settings)
+      end
+    end
+  end
+end

data/lib/unione/wrapper/email_payload.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module UniOne
+  module Wrapper
+    # Converts a Mail::Message to the "message" of email/send.
+    #
+    # - recipients: to, cc and bcc, the display name goes to the "to_name" substitution;
+    # - with cc the "To" and "CC" headers are set, so every recipient sees the same headers;
+    # - inline attachments become inline_attachments named by their Content-ID (cid:...);
+    # - X-* and List-* / In-Reply-To / References headers are passed as is.
+    module EmailPayload
+      PASSED_HEADERS = %w[list-unsubscribe list-subscribe list-help list-owner list-archive in-reply-to references].freeze
+
+      def self.from_mail(mail)
+        from = addresses(mail, :from).first
+        raise ArgumentError, 'The message has no sender (From)' if from.nil?
+
+        message = {
+          'recipients' => recipients(mail),
+          'subject' => mail.subject.to_s,
+          'from_email' => from.address
+        }
+        message['from_name'] = from.display_name if present?(from.display_name)
+        reply_to = addresses(mail, :reply_to).first
+        if reply_to
+          message['reply_to'] = reply_to.address
+          message['reply_to_name'] = reply_to.display_name if present?(reply_to.display_name)
+        end
+        body = body_parts(mail)
+        message['body'] = body unless body.empty?
+        headers = headers(mail)
+        message['headers'] = headers unless headers.empty?
+        mail.attachments.each do |part|
+          inline = part.inline? && present?(part.cid)
+          item = { 'type' => part.mime_type.to_s, 'name' => inline ? part.cid : part.filename.to_s,
+                   'content' => Base64.strict_encode64(part.decoded) }
+          (message[inline ? 'inline_attachments' : 'attachments'] ||= []) << item
+        end
+        message
+      end
+
+      def self.recipients(mail)
+        %i[to cc bcc].flat_map { |field| addresses(mail, field) }.map do |address|
+          recipient = { 'email' => address.address }
+          recipient['substitutions'] = { 'to_name' => address.display_name } if present?(address.display_name)
+          recipient
+        end
+      end
+
+      def self.body_parts(mail)
+        html = mail.html_part
+        text = mail.text_part
+        if html.nil? && text.nil? && !mail.multipart?
+          key = mail.mime_type.to_s == 'text/html' ? 'html' : 'plaintext'
+          return { key => mail.body.decoded }
+        end
+        { 'html' => html&.decoded, 'plaintext' => text&.decoded }.compact
+      end
+
+      def self.headers(mail)
+        headers = {}
+        cc = addresses(mail, :cc)
+        unless cc.empty?
+          headers['To'] = addresses(mail, :to).map(&:to_s).join(', ')
+          headers['CC'] = cc.map(&:to_s).join(', ')
+        end
+        mail.header.fields.each do |field|
+          name = field.name.to_s
+          next unless name.downcase.start_with?('x-') || PASSED_HEADERS.include?(name.downcase)
+
+          headers[name] = field.value.to_s
+        end
+        headers
+      end
+
+      def self.addresses(mail, field)
+        header = mail[field]
+        return [] if header.nil?
+
+        list = header.respond_to?(:address_list) ? header.address_list : nil
+        list ? list.addresses : Array(header.addrs)
+      end
+
+      def self.present?(value)
+        !value.nil? && !value.to_s.empty?
+      end
+    end
+  end
+end

data/lib/unione/wrapper/railtie.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module UniOne
+  module Wrapper
+    # config.unione settings, the :unione delivery method of Action Mailer and the webhook route.
+    class Railtie < ::Rails::Railtie
+      config.unione = ::UniOne::Wrapper.default_configuration
+
+      initializer 'unione.configure' do |app|
+        options = app.config.unione
+        if options.api_key.nil? || options.api_key.to_s.empty?
+          credentials = begin
+            app.credentials.unione
+          rescue StandardError
+            nil
+          end
+          options.api_key = credentials[:api_key] if credentials.respond_to?(:[])
+        end
+        ::UniOne::Wrapper.configuration = options
+      end
+
+      initializer 'unione.action_mailer' do
+        ActiveSupport.on_load(:action_mailer) do
+          add_delivery_method :unione, ::UniOne::Wrapper::DeliveryMethod
+        end
+      end
+
+      initializer 'unione.webhook_route' do |app|
+        options = app.config.unione
+        if options.webhook_enabled != false
+          app.routes.prepend do
+            match options.webhook_path, to: ::UniOne::Wrapper::WebhookEndpoint.new, via: %i[get head post],
+                                        as: 'unione_webhook'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unione/wrapper/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Wrapper
+    VERSION = '1.1.3'
+    # The gem and its version in the "platform" query parameter of the requests, before the SDK one.
+    PLATFORM = 'rails.1.1.3'
+  end
+end

data/lib/unione/wrapper/webhook_endpoint.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'active_support/notifications'
+
+module UniOne
+  module Wrapper
+    # Rack endpoint of the webhooks (no CSRF, no session): GET/HEAD -> 200 (URL check of webhook/set),
+    # POST -> signature check (401 when wrong), then ActiveSupport::Notifications:
+    #   "webhook.unione" - the whole notification: payload[:callback] (WebhookCallback), payload[:data] (Hash)
+    #   "event.unione"   - every event: payload[:event], payload[:user] (user/project of the event)
+    # Subscribers must be fast: the API waits for 200 OK for 3 seconds only.
+    class WebhookEndpoint
+      HEADERS = { 'content-type' => 'text/plain' }.freeze
+
+      def call(env)
+        return reply(200, 'OK') unless env['REQUEST_METHOD'] == 'POST'
+
+        input = env['rack.input']
+        body = input ? input.read.to_s : ''
+        input&.rewind if input.respond_to?(:rewind)
+        return reply(401, 'Invalid signature') unless WebhookSignature.verify(body, ::UniOne::Wrapper.webhook_key)
+
+        begin
+          callback = ::UniOne::Api::Webhook::WebhookApi.parse_callback(body)
+          data = JSON.parse(body)
+        rescue JSON::ParserError, TypeError, NoMethodError
+          return reply(400, 'Invalid body')
+        end
+
+        ActiveSupport::Notifications.instrument('webhook.unione', callback: callback, data: data)
+        (callback.events_by_user || []).each do |user|
+          (user.events || []).each do |event|
+            ActiveSupport::Notifications.instrument('event.unione', event: event, user: user)
+          end
+        end
+        reply(200, 'OK')
+      end
+
+      private
+
+      def reply(status, text)
+        [status, HEADERS.dup, [text]]
+      end
+    end
+  end
+end

data/lib/unione/wrapper/webhook_signature.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'digest/md5'
+require 'active_support/security_utils'
+
+module UniOne
+  module Wrapper
+    # Signature of the webhook notifications: the "auth" field is the MD5 of the request body in which the "auth"
+    # value is replaced by the API key of the user/project of the webhook.
+    module WebhookSignature
+      PLACEHOLDER = '0' * 32
+
+      def self.verify(body, api_key)
+        return false if api_key.nil? || api_key.empty?
+
+        match = body.match(/"auth"\s*:\s*"(\h{32})"/)
+        return false if match.nil?
+
+        expected = Digest::MD5.hexdigest(body.gsub(match[1], api_key))
+        ActiveSupport::SecurityUtils.secure_compare(match[1].downcase, expected)
+      end
+
+      # Signs a body that has "auth" set to the placeholder, e.g. for tests.
+      def self.sign(body, api_key, placeholder = PLACEHOLDER)
+        body.gsub(placeholder, Digest::MD5.hexdigest(body.gsub(placeholder, api_key)))
+      end
+    end
+  end
+end

data/lib/unione/wrapper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'unione'
+require 'active_support'
+require 'active_support/ordered_options'
+require_relative 'wrapper/version'
+require_relative 'wrapper/webhook_signature'
+require_relative 'wrapper/email_payload'
+require_relative 'wrapper/delivery_method'
+require_relative 'wrapper/webhook_endpoint'
+
+module UniOne
+  # Rails integration: UniOne::Wrapper.client is the UniOne API client configured by config.unione.
+  module Wrapper
+    class << self
+      # Settings: api_key, host, timeout, webhook_key, webhook_path, webhook_enabled (config.unione in Rails).
+      def configuration
+        @configuration ||= default_configuration
+      end
+
+      def configuration=(options)
+        @configuration = options
+        @client = nil
+      end
+
+      def configure
+        yield configuration
+        @client = nil
+      end
+
+      # @return [UniOne::UniOneClient] memoized client of the configuration
+      def client
+        @client ||= build_client(configuration)
+      end
+
+      # A client for other settings: { api_key:, host:, timeout: } (missing ones come from the configuration).
+      def build_client(options)
+        api_key = present(options[:api_key])
+        raise ArgumentError, 'UniOne: set config.unione.api_key (UNIONE_API_KEY)' if api_key.nil?
+
+        timeout = present(options[:timeout]) || configuration[:timeout] || 30
+        ::UniOne::UniOneClient.new(api_key, present(options[:host]), timeout: timeout.to_i, platform: PLATFORM)
+      end
+
+      # API key the webhook notifications are signed with.
+      def webhook_key
+        present(configuration[:webhook_key]) || present(configuration[:api_key]).to_s
+      end
+
+      def default_configuration
+        options = ActiveSupport::OrderedOptions.new
+        options.api_key = ENV['UNIONE_API_KEY']
+        options.host = ENV['UNIONE_HOST']
+        options.timeout = (ENV['UNIONE_TIMEOUT'] || 30).to_i
+        options.webhook_key = ENV['UNIONE_WEBHOOK_KEY']
+        options.webhook_path = ENV['UNIONE_WEBHOOK_PATH'] || '/unione/webhook'
+        options.webhook_enabled = ENV['UNIONE_WEBHOOK_ENABLED'] != 'false'
+        options
+      end
+
+      private
+
+      def present(value)
+        value.nil? || value.to_s.empty? ? nil : value
+      end
+    end
+  end
+end
+
+require_relative 'wrapper/railtie' if defined?(::Rails::Railtie)

data/lib/unione-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'unione/wrapper'

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: unione-rails
+version: !ruby/object:Gem::Version
+  version: 1.1.3
+platform: ruby
+authors:
+- UniOne
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: unione
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- LICENSE
+- README.md
+- lib/unione-rails.rb
+- lib/unione/wrapper.rb
+- lib/unione/wrapper/delivery_method.rb
+- lib/unione/wrapper/email_payload.rb
+- lib/unione/wrapper/railtie.rb
+- lib/unione/wrapper/version.rb
+- lib/unione/wrapper/webhook_endpoint.rb
+- lib/unione/wrapper/webhook_signature.rb
+homepage: https://github.com/unione-repo/unione-rails
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://docs.unione.io/en/web-api-ref
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+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: 'UniOne Web API for Rails: API client, Action Mailer delivery method, webhooks'
+test_files: []