Web API 1.90

Official Ruby library for the UniOne transactional email API.

Quickstart guide: Send emails with Ruby · Docs for LLMs: llms.txt · API reference

gem install unione

Requirements: Ruby 2.7+. No third-party dependencies.

1. Sign up at cp.unione.io.
2. Copy your API key from Settings → Security → API.
3. Put it in an environment variable:

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.

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.

1. Get your sandbox domain (domain/get-sandbox-domain). The call creates the domain on first use and returns the same one afterwards.

require 'unione'

client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))

response = client.domain.get_sandbox_domain
p response.domain

2. Confirm your inbox (confirmed-email/create). UniOne sends a confirmation email; click the link in it within 48 hours.

require 'unione'

ConfirmedEmail = UniOne::Api::ConfirmedEmail::Model

client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))

response = client.confirmed_email.create(ConfirmedEmail::ConfirmedEmailRequest.new(
  email: 'you@example.com'
))
p response.confirmed_email

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.

require 'unione'

Common = UniOne::Common::Model
Email = UniOne::Api::Email::Model

client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))

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

{
  "status": "success",
  "job_id": "1ZymBc-00041N-9X",
  "emails": [
    "you@example.com"
  ]
}

On error the API returns status: "error", a message and a numeric code:

{
  "status": "error",
  "code": 102,
  "message": "Error ID:83274F98-C7D5-11F1-B221-6214FF8707B1. Can not decode key wrongkey"
}

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>"
          }
        }
      }'

• 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.

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.

• 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.

• Send emails with Ruby and other integration guides
• Web API reference
• llms.txt for AI coding agents
• UniOne MCP server and agent setup
• Support

See AGENTS.md: how this SDK is generated from the OpenAPI spec, built, tested and released.

The second argument selects the API host (datacenter) or a full base URL.

require 'unione'

client = UniOne.client('YOUR_API_KEY', 'us1.unione.io')
client = UniOne.client('YOUR_API_KEY', UniOne::Client::Configuration::HOST_US1)

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.

require 'unione'

# Logs every request and retries network failures and HTTP 5xx.
class RetryTransport
  def initialize(inner = UniOne::Client::NetHttpTransport.new, attempts: 3)
    @inner = inner
    @attempts = attempts
  end

  def call(method, uri, headers, body, timeout)
    (1..@attempts).each do |attempt|
      puts "#{method} #{uri}"
      begin
        status, raw = @inner.call(method, uri, headers, body, timeout)
        return [status, raw] if status < 500 || attempt == @attempts
      rescue StandardError
        raise if attempt == @attempts
      end
      sleep attempt
    end
  end
end

client = UniOne.client('YOUR_API_KEY', transport: RetryTransport.new, headers: { 'X-Request-Id' => '42' })

Models with free-form keys (HeadersObject) have an extra hash: its keys go next to the named fields.

require 'unione'

headers = UniOne::Common::Model::HeadersObject.new(extra: {
  'X-MyHeader' => 'some data',
  'CC' => 'copy@example.com',
  'List-Unsubscribe' => '<mailto:unsubscribe@example.com>'
})

Every method raises ApiError when the API returns an error; it carries the API error code and the HTTP status.