unione 1.1.3 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 966428a227c0701201a9efb14fb683d891df950a2cc1e446fda99113eca0b2b6
-  data.tar.gz: 9664b54ea7723c2172e47fdd062468610505fcc24f040d5fae1e5f8e1e364697
+  metadata.gz: 905c25d5be2c9eb7f499e528962a173bd5852d40ed4239d07d9484d830227900
+  data.tar.gz: 2b0bc8aa4a2149a3e663ed7da251174ceeb180671e3f90ee932814ad791cbfc9
 SHA512:
-  metadata.gz: 8f1a2f280c5d7066e0b033c8ab86de1e647540e3a73c9232b189c83e2d8798cb3ad55134b2c276ed3898dfa5e956592cb8ac233c660631dab7452881bc9afed3
-  data.tar.gz: f36d07366d6b07d739d0f91268e2ef0a9e5dffe7f60bc99006aade3a926983b52f378d3a44e3fc23f43911d47e1b673094d0f378ca77ab260cb19fdb154b33fa
+  metadata.gz: a0916665cc508953defe333e3517a0b72b0000a6dde8ffce70753e1cf01a5b9772fd78a26a118c188481f55c41bc40601345c86574399afab16a296e96323c06
+  data.tar.gz: 92a7e623a9c261c4577cbeb3cbce612dfa21742bdad0a48c30628f844f2f4d0fb5bacf0755d9eaec37d5c6588da303398b60cfb07c412276416e04a32d20f00f

data/AGENTS.md

@@ -11,9 +11,9 @@ UniOne Ruby SDK — client for the UniOne transactional email Web API (Web API 1
   gem build *.gemspec
   ```
 
-- **Source label.** Every request carries the query parameter `platform=ruby-sdk.1.1.3`, added in one place, the shared request client (`ApiClient`); a package built on this SDK puts its own label in front: `<package>.<version>,ruby-sdk.1.1.3`.
+- **Source label.** Every request carries the query parameter `platform=ruby-sdk.1.2.3`, added in one place, the shared request client (`ApiClient`); a package built on this SDK puts its own label in front: `<package>.<version>,ruby-sdk.1.2.3`.
 - **Tests.** Before a release the generator builds and lints the package and runs every example of docs/ and of this file 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.
+- **Release.** The version (1.2.3 in the gemspec) and the tag `v1.2.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 SDK
@@ -38,7 +38,7 @@ Rules that generated code must follow:
 - 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 SDK 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`.
+- 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 with the attachments in base64 (a third larger than the files); always `body.html` or `body.plaintext`.
 - Delivery events via webhook (`webhook/set`) with a fast, idempotent HTTPS handler, not polling; check the `auth` field of every notification: the MD5 of the request body with the `auth` value replaced by the API key.
 - Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
 - Do not invent methods or fields. Check [docs/](docs/) of this package, the [API reference](https://docs.unione.io/en/web-api-ref) or [llms.txt](https://docs.unione.io/llms.txt).

data/README.md

@@ -1,10 +1,12 @@
-# UniOne Ruby SDK 1.1.3
+# UniOne Ruby SDK
 
-Web API 1.90
+[![Ruby](https://img.shields.io/gem/v/unione)](https://rubygems.org/gems/unione) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 Official Ruby library for the [UniOne](https://unione.io) transactional email API.
 
-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)
+[API reference](https://docs.unione.io/en/web-api-ref) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt)
+
+> **On Ruby on Rails?** Install [`unione-rails`](https://github.com/unione-repo/unione-rails) instead: this SDK plus configuration, a mailer and a webhook route.
 
 ## Install
 
@@ -14,106 +16,214 @@ gem install unione
 
 Requirements: Ruby 2.7+. No third-party dependencies.
 
-## 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:
+Get an API key in the [control panel](https://cp.unione.io/en/settings/security/api) and keep it in the environment, never in code:
 
 ```bash
 export UNIONE_API_KEY="your-api-key"
 ```
 
-> **Server-side only.** Use this SDK in backend code: API routes, server functions, workers.
-> Never ship the API key to a browser or a mobile app, and never commit it.
+## Send an email
+
+```ruby
+require 'unione'
+
+Body = UniOne::Common::Model::BodyObject
+Email = UniOne::Api::Email::Model
+Recipient = UniOne::Api::Email::Model::MessageObjectRecipientsItem
+
+client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))
+
+message = Email::MessageObject.new(
+  recipients: [Recipient.from_address('Alex <alex@example.com>')],
+  body: Body.html('<p>Hello, {{to_name}}! Your order has shipped.</p>'),
+  subject: 'Your order',
+  from_email: 'shop@example.com',
+  from_name: 'Shop'
+)
+response = client.email.send_email(Email::EmailSendRequest.new(message: message))
+puts response.job_id
+```
+
+The sender address must be on a domain verified in your account. No domain yet? Send from the [sandbox domain](#no-domain-yet-the-test-sandbox-domain) in three steps.
+
+## Contents
 
-## Send your first email — no DNS setup
+- [Recipes](#recipes): personalization · attachments · CC and BCC · scheduling · safe retries · errors · webhooks
+- [No domain yet: the test sandbox domain](#no-domain-yet-the-test-sandbox-domain)
+- [Going to production](#going-to-production)
+- [Reference](#reference)
+- [Help](#help)
 
-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.
+## Recipes
 
-<!-- checked examples -->
+Every recipe continues the example above: the client and its imports are there.
 
-**1. Get your sandbox domain** (`domain/get-sandbox-domain`). The call creates the domain on first use and returns the same one afterwards.
+### Personalize for each recipient
+
+Up to 500 recipients per call, each gets a separate copy with its own substitutions. Metadata of a recipient comes back in its webhook events.
 
 ```ruby
-require 'unione'
+message = Email::MessageObject.new(
+  recipients: [
+    Recipient.from_address('Alex <alex@example.com>', { 'order' => '1001' }).with_metadata({ 'user_id' => '42' }),
+    Recipient.from_address('Maria <maria@example.com>', { 'order' => '1002' }).with_metadata({ 'user_id' => '43' })
+  ],
+  body: Body.html('<p>{{to_name}}, order #{{order}} has shipped.</p>'),
+  subject: 'Order #{{order}}',
+  from_email: 'shop@example.com'
+)
+client.email.send_email(Email::EmailSendRequest.new(message: message))
+```
 
-client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))
+### Attach a file
+
+```ruby
+Common = UniOne::Common::Model
 
-response = client.domain.get_sandbox_domain
-p response.domain
+message = Email::MessageObject.new(
+  recipients: [Recipient.from_address('alex@example.com')],
+  body: Body.html('<p>Your invoice is attached.</p>'),
+  subject: 'Invoice',
+  from_email: 'shop@example.com',
+  attachments: [
+    Common::AttachmentsArrayItem.new(
+      type: 'application/pdf',
+      name: 'invoice.pdf',
+      content: [File.binread('invoice.pdf')].pack('m0')
+    )
+  ]
+)
+client.email.send_email(Email::EmailSendRequest.new(message: message))
 ```
 
-**2. Confirm your inbox** (`confirmed-email/create`). UniOne sends a confirmation email; click the link in it within 48 hours.
+### CC and BCC
+
+Every address goes to `recipients` (each gets a copy); the visible ones also go to the headers. `audit@example.com` is in neither header: a BCC. The rules and limits: [CC and BCC](https://docs.unione.io/en/cc-and-bcc).
 
 ```ruby
-require 'unione'
+Common = UniOne::Common::Model
 
-ConfirmedEmail = UniOne::Api::ConfirmedEmail::Model
+message = Email::MessageObject.new(
+  recipients: [
+    Recipient.from_address('alex@example.com'),
+    Recipient.from_address('boss@example.com'),
+    Recipient.from_address('audit@example.com')
+  ],
+  body: Body.html('<p>The report is attached.</p>'),
+  subject: 'Weekly report',
+  from_email: 'shop@example.com',
+  headers: Common::HeadersObject.new(extra: { 'To' => 'alex@example.com', 'CC' => 'boss@example.com' })
+)
+client.email.send_email(Email::EmailSendRequest.new(message: message))
+```
 
-client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))
+### Schedule
+
+`send_at` is UTC, up to 24 hours ahead.
 
-response = client.confirmed_email.create(ConfirmedEmail::ConfirmedEmailRequest.new(
-  email: 'you@example.com'
-))
-p response.confirmed_email
+```ruby
+send_at = (Time.now.utc + 3600).strftime('%Y-%m-%d %H:%M:%S') # UTC, "YYYY-MM-DD hh:mm:ss"
+message = Email::MessageObject.new(
+  recipients: [Recipient.from_address('alex@example.com')],
+  body: Body.text('See you tomorrow!'),
+  subject: 'Reminder',
+  from_email: 'shop@example.com',
+  options: Email::MessageObjectOptions.new(send_at: send_at)
+)
+client.email.send_email(Email::EmailSendRequest.new(message: message))
 ```
 
-Check the status with `confirmed-email/list` — your address should show `"status": "confirmed"`.
+### Retry safely
 
-**3. Send the email** (`email/send`) from any address on the sandbox domain to the confirmed address.
+A repeat with the same `idempotence_key` within a minute is not sent twice: retry network errors, timeouts, 429 and 5xx with it.
 
 ```ruby
-require 'unione'
+message = Email::MessageObject.new(
+  recipients: [Recipient.from_address('alex@example.com')],
+  body: Body.html('<p>Use this link to reset your password.</p>'),
+  subject: 'Reset your password',
+  from_email: 'shop@example.com',
+  idempotence_key: 'password-reset-8f3a'
+)
+client.email.send_email(Email::EmailSendRequest.new(message: message))
+```
 
-Common = UniOne::Common::Model
-Email = UniOne::Api::Email::Model
+### Handle errors
 
-client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))
+Recipients the API drops (unsubscribed, invalid, suppressed) are not an error: they are in `failed_emails` of the response, the rest still get the message.
 
-response = 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>'
-  )
-))
-p response.job_id
+```ruby
+begin
+  client.email.send_email(request)
+rescue UniOne::Client::ApiError => e
+  # HTTP status (0: network error or timeout), API error code, message
+  puts "#{e.http_status} #{e.error_code}: #{e.message}"
+end
 ```
 
-<!-- /checked examples -->
+### Receive delivery events
 
-### What you get back
+Register your HTTPS endpoint once (`webhook/set`). Then check the signature of every notification (`auth`: MD5 of the raw body with the `auth` value replaced by your API key; a wrong one gets 401) and process the events.
 
-```json
-{
-  "status": "success",
-  "job_id": "1ZymBc-00041N-9X",
-  "emails": [
-    "you@example.com"
-  ]
-}
+```ruby
+require 'digest'
+
+# raw: the body of the POST request as received; returns the HTTP status to answer
+def handle_webhook(raw)
+  callback = UniOne::Api::Webhook::WebhookApi.parse_callback(raw)
+  auth = callback.auth.to_s
+  # auth: MD5 of the raw body with the auth value replaced by your API key
+  return 401 unless Digest::MD5.hexdigest(raw.gsub(auth, ENV.fetch('UNIONE_API_KEY'))) == auth
+
+  (callback.events_by_user || []).each do |user|
+    (user.events || []).each do |event|
+      # email, status (delivered, opened, hard_bounced, spam, ...), job_id, metadata
+    end
+  end
+  200
+end
 ```
 
-On error the API returns `status: "error"`, a `message` and a numeric `code`:
+> **Answer 200 within 3 seconds** and process the events in the background (a queue): otherwise UniOne repeats the request every 10 minutes for 24 hours (`retry_count` grows), and a handler that failed every request for at least 10 events of a day is turned inactive. The handler must take at least **5 parallel requests of up to 100 events each**; deduplicate, a repeat delivers the same events again.
+
+## No domain yet: the test sandbox domain
+
+Until your domain is verified, send from the **sandbox domain**: a test domain every account has, already verified, with DKIM and SPF set. It delivers only to addresses you confirm (the confirmation link comes by email, valid 48 hours), up to 100 emails a day. The sandbox domain is deleted 31 days after it was created, but you can get it again: the next `domain/get-sandbox-domain` call creates a new one (with a new name, so read it from the call, do not hardcode it).
 
-```json
-{
-  "status": "error",
-  "code": 102,
-  "message": "Error ID:83274F98-C7D5-11F1-B221-6214FF8707B1. Can not decode key wrongkey"
-}
+```ruby
+ConfirmedEmail = UniOne::Api::ConfirmedEmail::Model
+
+# 1. Your sandbox domain: created on the first call, the same one afterwards
+domain = client.domain.get_sandbox_domain.domain
+
+# 2. Confirm your inbox: UniOne sends a link, click it within 48 hours
+client.confirmed_email.create(ConfirmedEmail::ConfirmedEmailRequest.new(email: 'you@example.com'))
+
+# 3. Send from any address on the sandbox domain to the confirmed one
+message = Email::MessageObject.new(
+  recipients: [Recipient.from_address('you@example.com')],
+  body: Body.html('<p>It works!</p>'),
+  subject: 'Hello from UniOne',
+  from_email: "noreply@#{domain}"
+)
+client.email.send_email(Email::EmailSendRequest.new(message: message))
 ```
 
-### Same flow with curl
+<details>
+<summary>Sandbox limits</summary>
+
+- 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.
+
+</details>
+
+<details>
+<summary>The same with curl</summary>
 
 ```bash
 BASE=https://api.unione.io/en/transactional/api/v1
@@ -143,58 +253,51 @@ curl -s -X POST $BASE/email/send.json \
       }'
 ```
 
-## Sandbox limits
+</details>
 
-- 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 |
+## Going to production
 
-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.
+**1. Verify your sending domain.** `domain/get-dns-records` returns the verification record, the DKIM key and the DMARC target; add the records at your DNS provider, then `domain/validate-verification-record` and `domain/validate-dkim`.
 
-## Sending reliably
+| Type | Host | Value | Where it comes from |
+|---|---|---|---|
+| TXT | `@` | `unione-validate-hash=…` | `verification-record` of the response, as is |
+| TXT | `<selector>._domainkey` (the selector is on the domain page of the control panel, e.g. `us`) | `v=DKIM1; k=rsa; p=<dkim>` | `dkim` of the response after `v=DKIM1; k=rsa; p=` |
+| TXT | `@` | `v=spf1 include:spf.unione.io ~all` | not in the response; add the include to your SPF record if you have one |
+| CNAME | `_dmarc` | `<domain>.dmarc.…` | `dmarc` of the response (UniOne publishes the DMARC policy); keep your own DMARC TXT record instead if the domain has one |
 
-- **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.
+**2. Make sending reliable.**
 
-## Links
+| | |
+|---|---|
+| Retries | `429` and `5xx` with backoff and the same `idempotence_key`; fix other errors instead of retrying |
+| Limits | 500 recipients and 10 MB per request, attachments included: base64 makes a file about a third larger |
+| Body | always `html` or `plaintext` (a template can supply it) |
+| Delivery status | a webhook, not polling |
+| Queue | send from a background job, not inside the web request |
+| Config | `from_email` from config, so the sandbox → production switch needs no code change |
+| Defaults | keep the unsubscribe footer and tracking; changing them needs UniOne support |
 
-- [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)
+## Reference
 
-## For SDK contributors
+### Sections
 
-See [AGENTS.md](AGENTS.md): how this SDK is generated from the OpenAPI spec, built, tested and released.
-
----
-
-# SDK reference
+| Section | Methods | Description |
+|---|---|---|
+| [Email](docs/Email.md) | `send_email`, `subscribe` | This group of methods is related with email sending. |
+| [EmailValidation](docs/EmailValidation.md) | `single` | Email validation methods. As a result of the check, you’ll get detailed information on email validity. It will help eliminate nonexistent emails, decrease the number of complaints, clean up the subscribers list and eventually enhance your sender reputation score. For example, you may add validation to a subscription form on your site to let users know they’ve just entered an invalid address. |
+| [ConfirmedEmail](docs/ConfirmedEmail.md) | `create`, `list`, `delete` | Manage email addresses confirmed for sandbox-domain sending. These methods are available only with a main account API key. |
+| [Template](docs/Template.md) | `set`, `get`, `list`, `delete` | You have the option of storing a template on the UniOne side and then using it by id, which is highly recommended for sending repetitive messages or high volume traffic. UniOne supports two different [template engines](https://docs.unione.io/en/template-engines). |
+| [Webhook](docs/Webhook.md) | `set`, `get`, `list`, `delete` | UniOne lets you recieve notifications about email status changes or spam blocks. You provide an URL and every time a watched event occurs we will notify you by submitting a request with JSON data to this URL. |
+| [Suppression](docs/Suppression.md) | `set`, `get`, `list`, `delete` | Methods for managing suppression lists. An email can be added to suppression list because of unsubscription, bounce or complain. |
+| [Domain](docs/Domain.md) | `get_dns_records`, `validate_verification_record`, `validate_dkim`, `list`, `get_sandbox_domain`, `delete` | You can use these methods to setup sender domains and check their statuses. They might be useful in case you want to automate adding domains for your own clients. |
+| [EventDump](docs/EventDump.md) | `create`, `get`, `list`, `delete` | These methods are used to obtain a list of events for a given period of time. The data is stored for up to 45 days, depending on your tariff, i. e. you may fetch all event data starting from 00:00:00 31 days ago and up to current time. For custom tarifs with big sending volumes event dumps are available only for the last 7 days. |
+| [Tag](docs/Tag.md) | `list`, `delete` | This family of methods is used to manage user-defined tags. Tags are used to categorize letters based on your own criteria, e. g. to create a distinction between marketing and transactional letters or group together all notifications for a particular order type. UniOne allows you to assign tags to all outgoing emails, and the tags you’ve set may then be used to filter and analyze delivery statistics. |
+| [Project](docs/Project.md) | `create`, `update`, `list`, `delete` | Projects allow you to group several independent domains, webhooks, templates, and unsubscription lists together. It's very useful if you have your own clients and manage their data from a single UniOne account. Each project receives its own API key, and all API calls with that API key only deal with the data of that project. This way, you can assign a separate project for each client and be sure that they won't conflict; e.g. unsubscribing from one project won't affect another. |
+| [System](docs/System.md) | `ping`, `info` | System operations. |
+| [Obsolete](docs/Obsolete.md) | `unsubscribed_set`, `unsubscribed_check`, `unsubscribed_list` | Obsolete methods dealing with unsubscribes. We recommend using the more flexible [suppression](https://docs.unione.io/en/web-api-ref#suppression) methods instead. Note that you can't resubscribe an unsubscribed recipient using WebAPI, but you can send him an email with subscription link using email/subscribe method. |
 
-## API host
+### API host
 
 The second argument selects the API host (datacenter) or a full base URL.
 
@@ -205,7 +308,7 @@ client = UniOne.client('YOUR_API_KEY', 'us1.unione.io')
 client = UniOne.client('YOUR_API_KEY', UniOne::Client::Configuration::HOST_US1)
 ```
 
-## Custom HTTP client / headers
+### Custom HTTP client / headers
 
 `headers:` adds HTTP headers to every request. `transport:` replaces the HTTP layer: any object responding to `call(method, uri, headers, body, timeout)` that returns `[status, body]` (a lambda works too). Wrap the default `Client::NetHttpTransport` for retries or logging, or call Faraday / HTTParty in your own one; an exception of the transport becomes `ApiError`.
 
@@ -248,23 +351,13 @@ headers = UniOne::Common::Model::HeadersObject.new(extra: {
 })
 ```
 
-## Error handling
+### Error handling
 
 Every method raises `ApiError` when the API returns an error; it carries the [API error code](https://docs.unione.io/en/web-api-ref#api-errors) and the HTTP status.
 
-## Sections
+## Help
 
-| Section | Methods | Description |
-|---|---|---|
-| [Email](docs/Email.md) | `send_email`, `subscribe` | This group of methods is related with email sending. |
-| [EmailValidation](docs/EmailValidation.md) | `single` | Email validation methods. As a result of the check, you’ll get detailed information on email validity. It will help eliminate nonexistent emails, decrease the number of complaints, clean up the subscribers list and eventually enhance your sender reputation score. For example, you may add validation to a subscription form on your site to let users know they’ve just entered an invalid address. |
-| [ConfirmedEmail](docs/ConfirmedEmail.md) | `create`, `list`, `delete` | Manage email addresses confirmed for sandbox-domain sending. These methods are available only with a main account API key. |
-| [Template](docs/Template.md) | `set`, `get`, `list`, `delete` | You have the option of storing a template on the UniOne side and then using it by id, which is highly recommended for sending repetitive messages or high volume traffic. UniOne supports two different [template engines](https://docs.unione.io/en/template-engines). |
-| [Webhook](docs/Webhook.md) | `set`, `get`, `list`, `delete` | UniOne lets you recieve notifications about email status changes or spam blocks. You provide an URL and every time a watched event occurs we will notify you by submitting a request with JSON data to this URL. |
-| [Suppression](docs/Suppression.md) | `set`, `get`, `list`, `delete` | Methods for managing suppression lists. An email can be added to suppression list because of unsubscription, bounce or complain. |
-| [Domain](docs/Domain.md) | `get_dns_records`, `validate_verification_record`, `validate_dkim`, `list`, `get_sandbox_domain`, `delete` | You can use these methods to setup sender domains and check their statuses. They might be useful in case you want to automate adding domains for your own clients. |
-| [EventDump](docs/EventDump.md) | `create`, `get`, `list`, `delete` | These methods are used to obtain a list of events for a given period of time. The data is stored for up to 45 days, depending on your tariff, i. e. you may fetch all event data starting from 00:00:00 31 days ago and up to current time. For custom tarifs with big sending volumes event dumps are available only for the last 7 days. |
-| [Tag](docs/Tag.md) | `list`, `delete` | This family of methods is used to manage user-defined tags. Tags are used to categorize letters based on your own criteria, e. g. to create a distinction between marketing and transactional letters or group together all notifications for a particular order type. UniOne allows you to assign tags to all outgoing emails, and the tags you’ve set may then be used to filter and analyze delivery statistics. |
-| [Project](docs/Project.md) | `create`, `update`, `list`, `delete` | Projects allow you to group several independent domains, webhooks, templates, and unsubscription lists together. It's very useful if you have your own clients and manage their data from a single UniOne account. Each project receives its own API key, and all API calls with that API key only deal with the data of that project. This way, you can assign a separate project for each client and be sure that they won't conflict; e.g. unsubscribing from one project won't affect another. |
-| [System](docs/System.md) | `ping`, `info` | System operations. |
-| [Obsolete](docs/Obsolete.md) | `unsubscribed_set`, `unsubscribed_check`, `unsubscribed_list` | Obsolete methods dealing with unsubscribes. We recommend using the more flexible [suppression](https://docs.unione.io/en/web-api-ref#suppression) methods instead. Note that you can't resubscribe an unsubscribed recipient using WebAPI, but you can send him an email with subscription link using email/subscribe method. |
+- [Integration guides](https://docs.unione.io/en/integrations)
+- AI coding agents: [llms.txt](https://docs.unione.io/llms.txt), the [MCP server](https://unione.io/en/agents), skills: `npx skills add https://github.com/unione-repo/unione-skills.git`
+- [Support](https://cp.unione.io/en/support) · [Issues](https://github.com/unione-repo/unione-ruby-sdk/issues)
+- Contributing: [AGENTS.md](AGENTS.md) — the SDK is generated from the OpenAPI spec.

data/docs/Domain.md

@@ -33,13 +33,16 @@ You should add then DNS records like this to all of the domains you want to conf
 
 `@             IN TXT "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661"`
 
-`us._domainkey IN TXT "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
+`us._domainkey IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
 
 `@             IN TXT  "v=spf1 include:spf.unione.io ~all"`
 
+`_dmarc        IN CNAME "example.com.dmarc.unione.io."`
+
 - First record value should contain "verification-record" field returned by get-dns-records method "as is".
-- Second record value should contain "dkim" field value after "p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
-- Third record contains optional, but very recommended SPF entry. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
+- Second record value should contain "dkim" field value after "v=DKIM1; k=rsa; p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
+- Third record contains optional, but very recommended SPF entry. It is not returned by the method. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
+- Fourth record is a CNAME of the "_dmarc" host to the "dmarc" field value: UniOne then publishes the DMARC policy of the domain. If the domain already has its own DMARC TXT record, keep it instead.
 
 Syntax requirements of different DNS providers may differ:
 - sometimes it's necesarry to put full domain name instead of @ sign.
@@ -196,6 +199,8 @@ Creates a sandbox domain for the account or returns the existing one.
 
 Returns an account sandbox domain that is ready for use in the `from_email` field of [email/send](https://docs.unione.io/en/web-api-ref#email-send). If the account has no sandbox domain, UniOne creates one and returns it. Repeated calls return the same domain.
 
+The sandbox domain is removed 31 days after it was created; the next call creates a new one. Up to 100 emails a day can be sent from it (the default limit of the account).
+
 The method is available only with an account API key. Project API keys cannot create sandbox domains.
 
 ### Request

data/lib/unione/api/domain/domain_api.rb

@@ -30,13 +30,16 @@ module UniOne
         #
         # `@             IN TXT "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661"`
         #
-        # `us._domainkey IN TXT "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
+        # `us._domainkey IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"`
         #
         # `@             IN TXT  "v=spf1 include:spf.unione.io ~all"`
         #
+        # `_dmarc        IN CNAME "example.com.dmarc.unione.io."`
+        #
         # - First record value should contain "verification-record" field returned by get-dns-records method "as is".
-        # - Second record value should contain "dkim" field value after "p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
-        # - Third record contains optional, but very recommended SPF entry. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
+        # - Second record value should contain "dkim" field value after "v=DKIM1; k=rsa; p=". Mind the name of this record! "us._domainkey." prefix is important for DKIM selector of UniOne to work properly.
+        # - Third record contains optional, but very recommended SPF entry. It is not returned by the method. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
+        # - Fourth record is a CNAME of the "_dmarc" host to the "dmarc" field value: UniOne then publishes the DMARC policy of the domain. If the domain already has its own DMARC TXT record, keep it instead.
         #
         # Syntax requirements of different DNS providers may differ:
         # - sometimes it's necesarry to put full domain name instead of @ sign.
@@ -102,6 +105,9 @@ module UniOne
         # [email/send](https://docs.unione.io/en/web-api-ref#email-send). If the account has no sandbox
         # domain, UniOne creates one and returns it. Repeated calls return the same domain.
         #
+        # The sandbox domain is removed 31 days after it was created; the next call creates a new one. Up to
+        # 100 emails a day can be sent from it (the default limit of the account).
+        #
         # The method is available only with an account API key. Project API keys cannot create sandbox
         # domains.
         #

data/lib/unione/api/email/model/message_object_recipients_item.rb

@@ -47,6 +47,31 @@ module UniOne
             @metadata = metadata
           end
 
+          # A recipient from "email" or "Name <email>": the name goes to the to_name substitution (the
+          # name in the "To" header).
+          # @param address [String]
+          # @param substitutions [Hash{String => Object}, nil] more substitutions of the recipient
+          # @return [MessageObjectRecipientsItem]
+          def self.from_address(address, substitutions = nil)
+            email = address.to_s.strip
+            name = ''
+            match = email.match(/\A(.*)<([^>]+)>\z/m)
+            if match
+              email = match[2].strip
+              name = match[1].strip.gsub(/\A"+|"+\z/, '')
+            end
+            substitutions = { 'to_name' => name }.merge(substitutions || {}) unless name.empty?
+            new(email: email, substitutions: substitutions)
+          end
+
+          # Sets the metadata of the recipient (returned in the webhook events of its email).
+          # @param metadata [Hash{String => String}]
+          # @return [MessageObjectRecipientsItem] the recipient
+          def with_metadata(metadata)
+            self.metadata = metadata
+            self
+          end
+
           # Builds the object from decoded JSON. Lenient: a missing field, nil or a value of another type
           # gives nil (data that is not a Hash gives an empty object).
           def self.from_h(data)

data/lib/unione/client/api_client.rb

@@ -7,7 +7,7 @@ require 'uri'
 module UniOne
   module Client
     # The SDK and its version in the "platform" query parameter of every request.
-    PLATFORM = 'ruby-sdk.1.1.3'
+    PLATFORM = 'ruby-sdk.1.2.3'
 
     # Default transport (HTTP layer of ApiClient): Net::HTTP of the standard library.
     #

data/lib/unione/client/configuration.rb

@@ -36,7 +36,7 @@ module UniOne
       #   default ones of the same name
       attr_accessor :headers
 
-      def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, user_agent: 'unione-ruby-sdk/1.1.3', platform: nil, headers: {})
+      def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, user_agent: 'unione-ruby-sdk/1.2.3', platform: nil, headers: {})
         @api_key = api_key
         @base_url = base_url.sub(%r{/+\z}, '')
         @timeout = timeout

data/lib/unione/common/model/body_object.rb

@@ -28,6 +28,18 @@ module UniOne
           @amp = amp
         end
 
+        # An HTML body, with an optional plain-text part.
+        # @return [BodyObject]
+        def self.html(html, plaintext = nil)
+          new(html: html, plaintext: plaintext)
+        end
+
+        # A plain-text body.
+        # @return [BodyObject]
+        def self.text(plaintext)
+          new(plaintext: plaintext)
+        end
+
         # Builds the object from decoded JSON. Lenient: a missing field, nil or a value of another type
         # gives nil (data that is not a Hash gives an empty object).
         def self.from_h(data)

data/lib/unione/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UniOne
-  VERSION = '1.1.3'
+  VERSION = '1.2.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unione
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.2.3
 platform: ruby
 authors:
 - UniOne
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies: []
 description:
 email: