UniOne Django

Django integration of the UniOne Python SDK (``): the API client in the settings (get_client()), a webhook endpoint with signature check, a Django email transport that sends through `email/send`.

API reference · Docs for LLMs: llms.txt

Install

pip install unione-django

Requirements: Python 3.8+, Django 4.2+.

Configuration

Get an API key in the control panel and keep it in the environment, never in code:

export UNIONE_API_KEY="your-api-key"

Settings are read from the environment by default:

# settings.py
INSTALLED_APPS = [..., "unione_wrapper"]

UNIONE = {
    "API_KEY": os.environ["UNIONE_API_KEY"],
    "HOST": "us1.unione.io",  # optional
}
MAILERS = {"default": {"BACKEND": "unione_wrapper.mail.EmailBackend"}}  # Django 6.1+
# EMAIL_BACKEND = "unione_wrapper.mail.EmailBackend"                    # Django < 6.1
DEFAULT_FROM_EMAIL = "Shop <shop@example.com>"

# urls.py
urlpatterns = [..., path("unione/", include("unione_wrapper.urls"))]  # /unione/webhook

us1.unione.io in the example is for an account on another datacenter; without the host setting the package uses api.unione.io.

Settings of the UNIONE dict win over the environment variables. The webhook URL is set by include("unione_wrapper.urls"); the view is csrf_exempt.

Sending mail

Messages of the Django email go through email/send: from, to/cc/bcc, reply-to, subject, HTML and text parts, attachments, inline images and X-* headers.

from django.core.mail import EmailMultiAlternatives, send_mail

send_mail("Order shipped", "Your order is on its way", None, ["user@example.com"])

message = EmailMultiAlternatives("Order shipped", "Text", to=["User <user@example.com>"], headers={"X-Order": "42"})
message.attach_alternative("<b>HTML</b>", "text/html")
message.tags = ["orders"]                 # -> tags
message.metadata = {"order_id": "42"}     # -> global_metadata
message.send()
print(message.job_id)

No verified domain yet? Send from the test sandbox domain.

Webhooks

The endpoint answers GET with 200 OK (the URL check of 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.

from django.dispatch import receiver
from unione_wrapper.signals import webhook_event_received


@receiver(webhook_event_received)
def on_event(sender, event, user, **kwargs):
    data = event.event_data
    print(event.event_name, data.email, data.status)

Register the URL of the endpoint with webhook/set, e.g. https://example.com/unione/webhook.

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.

API client

Every section of the API is available on the client, see the SDK docs.

from unione_wrapper import get_client

info = get_client().system.info()
print(info.accounting)

Sending through the API

Besides the Django email, mail can be sent through the API client directly. The client calls email/send with all of its options: templates, substitutions, metadata, tracking. Fields of the request and other examples: Python SDK docs.

from django.http import JsonResponse
from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem as Recipient
from unione.common import BodyObject
from unione_wrapper import get_client


def send_email(request):
    client = get_client()
    response = client.email.send(EmailSendRequest(
        message=MessageObject(
            recipients=[Recipient.from_address("Alex <alex@example.com>")],
            from_email="shop@example.com",
            from_name="Shop",
            subject="Your order",
            body=BodyObject.from_html("<p>Hello, {{to_name}}! Your order has shipped.</p>"),
        ),
    ))
    return JsonResponse({"job_id": response.job_id})

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

The examples use the API client of the package (see the configuration above).

from django.http import JsonResponse
from unione.api.confirmed_email import ConfirmedEmailRequest
from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem as Recipient
from unione.common import BodyObject
from unione_wrapper import get_client


def send_from_sandbox(request):
    client = get_client()

    # 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(ConfirmedEmailRequest(email="you@example.com"))

    # 3. Send from any address on the sandbox domain to the confirmed one
    client.email.send(EmailSendRequest(
        message=MessageObject(
            recipients=[Recipient.from_address("you@example.com")],
            from_email=f"noreply@{domain}",
            subject="Hello from UniOne",
            body=BodyObject.from_html("<p>It works!</p>"),
        ),
    ))

    return JsonResponse({"domain": domain})

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

Going to production

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.

2. Make sending reliable.

Help

• Integration guides
• Python SDK
• AI coding agents: llms.txt, the MCP server, skills: npx skills add https://github.com/unione-repo/unione-skills.git
• Support · Issues
• Contributing: AGENTS.md — the package is generated from the OpenAPI spec.