UniOne Python SDK 1.1.3

Web API 1.90

Official Python library for the UniOne transactional email API.

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

Install

pip install unione-sdk

Requirements: Python 3.8+. No third-party dependencies.

Get an API key

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.

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.

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

import os
import unione

client = unione.client(os.environ["UNIONE_API_KEY"])

response = client.domain.get_sandbox_domain()
print(response.domain)

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

import os
import unione
from unione.api.confirmed_email import ConfirmedEmailRequest

client = unione.client(os.environ["UNIONE_API_KEY"])

response = client.confirmed_email.create(ConfirmedEmailRequest(
    email="you@example.com",
))
print(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.

import os
import unione
from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
from unione.common import BodyObject

client = unione.client(os.environ["UNIONE_API_KEY"])

response = client.email.send(EmailSendRequest(
    message=MessageObject(
        recipients=[
            MessageObjectRecipientsItem(
                email="you@example.com",
            ),
        ],
        body=BodyObject(
            html="<p>It works!</p>",
        ),
        subject="Hello from UniOne",
        from_email="noreply@<sandbox-domain>",
    ),
))
print(response.job_id)

What you get back

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

Same flow with curl

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

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 Python and other integration guides
• Web API reference
• llms.txt for AI coding agents
• UniOne MCP server and agent setup
• Support

For SDK contributors

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

SDK reference

API host

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

import unione
from unione.client import HOST_US1

client = unione.client("YOUR_API_KEY", "us1.unione.io")
client = unione.client("YOUR_API_KEY", HOST_US1)

Custom HTTP client / headers

headers adds HTTP headers to every request. transport replaces the HTTP layer: any object with send(method, url, headers, body, timeout) -> (status, body) (body: bytes; or such a function). Wrap the default UrllibTransport for retries or logging, or call requests / httpx in your own one; an exception of the transport becomes ApiError.

import time

import unione
from unione.client import UrllibTransport


class RetryTransport:
    """Logs every request and retries network failures and HTTP 5xx."""

    def __init__(self, inner=None, attempts=3):
        self.inner = inner or UrllibTransport()
        self.attempts = attempts

    def send(self, method, url, headers, body, timeout):
        for attempt in range(1, self.attempts + 1):
            print(method, url)
            try:
                status, raw = self.inner.send(method, url, headers, body, timeout)
            except unione.ApiError:
                if attempt == self.attempts:
                    raise
            else:
                if status < 500 or attempt == self.attempts:
                    return status, raw
            time.sleep(attempt)


client = unione.client("YOUR_API_KEY", transport=RetryTransport(), headers={"X-Request-Id": "42"})

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

from unione.common import HeadersObject

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

Error handling

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

Sections