unione-fastapi 1.1.3__tar.gz

unione_fastapi-1.1.3/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.

unione_fastapi-1.1.3/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: unione-fastapi
+Version: 1.1.3
+Summary: UniOne Web API for FastAPI: API client, webhooks
+Author: UniOne
+License: MIT
+Project-URL: Homepage, https://github.com/unione-repo/unione-fastapi
+Project-URL: Documentation, https://docs.unione.io/en/web-api-ref
+Keywords: unione,fastapi,email,webhook
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: unione-sdk>=1.1.3
+Requires-Dist: fastapi>=0.100
+Dynamic: license-file
+
+# UniOne FastAPI 1.1.3
+
+Web API 1.90
+
+Quickstart guide: [Send emails with Python](https://docs.unione.io/en/send-with-python) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt) · [API reference](https://docs.unione.io/en/web-api-ref)
+
+FastAPI integration of the [UniOne Python SDK](https://github.com/unione-repo/unione-python-sdk) (``): the API client in the dependencies (`Depends(get_client)`), a webhook endpoint with signature check.
+
+## Install
+
+```bash
+pip install unione-fastapi
+```
+
+Requirements: Python 3.8+, FastAPI 0.100+.
+
+## 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:
+
+```bash
+UNIONE_API_KEY=YOUR_API_KEY
+UNIONE_HOST=us1.unione.io
+```
+
+| Option | Environment variable | Default | Description |
+|---|---|---|---|
+| `Settings.api_key` | `UNIONE_API_KEY` |  | User or project API key (required). |
+| `Settings.host` | `UNIONE_HOST` | `api.unione.io` | API host (datacenter: `api.unione.io`, `eu1.unione.io`, `us1.unione.io`) or a full base URL. |
+| `Settings.timeout` | `UNIONE_TIMEOUT` | `30` | Request timeout, seconds. |
+| `Settings.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. |
+| `Settings.webhook_path` | `UNIONE_WEBHOOK_PATH` | `/unione/webhook` | Path of the webhook endpoint. |
+
+Other settings in code: `app.dependency_overrides[get_settings] = lambda: Settings(api_key=...)`.
+
+## 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.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+
+
+@app.post("/sandbox-domain")
+def get_sandbox_domain(client: UniOneClient = Depends(get_client)):
+    response = client.domain.get_sandbox_domain()
+    return {"domain": response.domain}
+```
+
+**2. Confirm your inbox** (`confirmed-email/create`). UniOne sends a confirmation email; click the link in it within 48 hours.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.confirmed_email import ConfirmedEmailRequest
+
+
+@app.post("/confirm-email")
+def confirm_email(client: UniOneClient = Depends(get_client)):
+    response = client.confirmed_email.create(ConfirmedEmailRequest(
+        email="you@example.com",
+    ))
+    return {"status": 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.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
+from unione.common import BodyObject
+
+
+@app.post("/send")
+def send(client: UniOneClient = Depends(get_client)):
+    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>",
+        ),
+    ))
+    return {"job_id": 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>"
+          }
+        }
+      }'
+```
+
+## 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.
+
+```python
+from unione_wrapper import Webhooks
+
+webhooks = Webhooks()
+
+
+@webhooks.on_event
+async def on_event(event, user):
+    data = event.event_data
+    print(event.event_name, data.email, data.status)
+
+
+app.include_router(webhooks.router())  # /unione/webhook
+```
+
+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-python-sdk).
+
+```python
+from fastapi import Depends, FastAPI
+from unione import UniOneClient
+from unione_wrapper import get_client
+
+app = FastAPI()
+
+
+@app.get("/usage")
+def usage(client: UniOneClient = Depends(get_client)):  # the client is synchronous: a def endpoint
+    info = client.system.info()
+    return {"emails_sent": info.accounting.emails_sent if info.accounting else None}
+```
+
+## Sending through the API
+
+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: [Python SDK docs](https://github.com/unione-repo/unione-python-sdk/blob/HEAD/docs/Email.md#send).
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
+from unione.common import BodyObject
+
+
+@app.post("/send")
+def send(client: UniOneClient = Depends(get_client)):
+    response = client.email.send(EmailSendRequest(
+        message=MessageObject(
+            recipients=[
+                MessageObjectRecipientsItem(
+                    email="user@example.com",
+                    substitutions={
+                        "CustomerId": "12452",
+                        "to_name": "John Smith",
+                    },
+                ),
+            ],
+            body=BodyObject(
+                html="<b>Hello, {{to_name}}</b>",
+                plaintext="Hello, {{to_name}}",
+            ),
+            subject="UniOne test email ",
+            from_email="email@example.com",
+            from_name="John Smith",
+        ),
+    ))
+    return {"job_id": 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 Python](https://docs.unione.io/en/send-with-python) 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.

unione_fastapi-1.1.3/README.md

@@ -0,0 +1,293 @@
+# UniOne FastAPI 1.1.3
+
+Web API 1.90
+
+Quickstart guide: [Send emails with Python](https://docs.unione.io/en/send-with-python) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt) · [API reference](https://docs.unione.io/en/web-api-ref)
+
+FastAPI integration of the [UniOne Python SDK](https://github.com/unione-repo/unione-python-sdk) (``): the API client in the dependencies (`Depends(get_client)`), a webhook endpoint with signature check.
+
+## Install
+
+```bash
+pip install unione-fastapi
+```
+
+Requirements: Python 3.8+, FastAPI 0.100+.
+
+## 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:
+
+```bash
+UNIONE_API_KEY=YOUR_API_KEY
+UNIONE_HOST=us1.unione.io
+```
+
+| Option | Environment variable | Default | Description |
+|---|---|---|---|
+| `Settings.api_key` | `UNIONE_API_KEY` |  | User or project API key (required). |
+| `Settings.host` | `UNIONE_HOST` | `api.unione.io` | API host (datacenter: `api.unione.io`, `eu1.unione.io`, `us1.unione.io`) or a full base URL. |
+| `Settings.timeout` | `UNIONE_TIMEOUT` | `30` | Request timeout, seconds. |
+| `Settings.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. |
+| `Settings.webhook_path` | `UNIONE_WEBHOOK_PATH` | `/unione/webhook` | Path of the webhook endpoint. |
+
+Other settings in code: `app.dependency_overrides[get_settings] = lambda: Settings(api_key=...)`.
+
+## 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.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+
+
+@app.post("/sandbox-domain")
+def get_sandbox_domain(client: UniOneClient = Depends(get_client)):
+    response = client.domain.get_sandbox_domain()
+    return {"domain": response.domain}
+```
+
+**2. Confirm your inbox** (`confirmed-email/create`). UniOne sends a confirmation email; click the link in it within 48 hours.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.confirmed_email import ConfirmedEmailRequest
+
+
+@app.post("/confirm-email")
+def confirm_email(client: UniOneClient = Depends(get_client)):
+    response = client.confirmed_email.create(ConfirmedEmailRequest(
+        email="you@example.com",
+    ))
+    return {"status": 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.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
+from unione.common import BodyObject
+
+
+@app.post("/send")
+def send(client: UniOneClient = Depends(get_client)):
+    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>",
+        ),
+    ))
+    return {"job_id": 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>"
+          }
+        }
+      }'
+```
+
+## 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.
+
+```python
+from unione_wrapper import Webhooks
+
+webhooks = Webhooks()
+
+
+@webhooks.on_event
+async def on_event(event, user):
+    data = event.event_data
+    print(event.event_name, data.email, data.status)
+
+
+app.include_router(webhooks.router())  # /unione/webhook
+```
+
+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-python-sdk).
+
+```python
+from fastapi import Depends, FastAPI
+from unione import UniOneClient
+from unione_wrapper import get_client
+
+app = FastAPI()
+
+
+@app.get("/usage")
+def usage(client: UniOneClient = Depends(get_client)):  # the client is synchronous: a def endpoint
+    info = client.system.info()
+    return {"emails_sent": info.accounting.emails_sent if info.accounting else None}
+```
+
+## Sending through the API
+
+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: [Python SDK docs](https://github.com/unione-repo/unione-python-sdk/blob/HEAD/docs/Email.md#send).
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
+from unione.common import BodyObject
+
+
+@app.post("/send")
+def send(client: UniOneClient = Depends(get_client)):
+    response = client.email.send(EmailSendRequest(
+        message=MessageObject(
+            recipients=[
+                MessageObjectRecipientsItem(
+                    email="user@example.com",
+                    substitutions={
+                        "CustomerId": "12452",
+                        "to_name": "John Smith",
+                    },
+                ),
+            ],
+            body=BodyObject(
+                html="<b>Hello, {{to_name}}</b>",
+                plaintext="Hello, {{to_name}}",
+            ),
+            subject="UniOne test email ",
+            from_email="email@example.com",
+            from_name="John Smith",
+        ),
+    ))
+    return {"job_id": 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 Python](https://docs.unione.io/en/send-with-python) 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.

unione_fastapi-1.1.3/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unione-fastapi"
+version = "1.1.3"
+description = "UniOne Web API for FastAPI: API client, webhooks"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "UniOne" }]
+keywords = ["unione", "fastapi", "email", "webhook"]
+classifiers = ["Framework :: FastAPI"]
+dependencies = ["unione-sdk>=1.1.3", "fastapi>=0.100"]
+
+[project.urls]
+Homepage = "https://github.com/unione-repo/unione-fastapi"
+Documentation = "https://docs.unione.io/en/web-api-ref"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["py.typed"]

unione_fastapi-1.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unione_fastapi-1.1.3/src/unione_fastapi.egg-info/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: unione-fastapi
+Version: 1.1.3
+Summary: UniOne Web API for FastAPI: API client, webhooks
+Author: UniOne
+License: MIT
+Project-URL: Homepage, https://github.com/unione-repo/unione-fastapi
+Project-URL: Documentation, https://docs.unione.io/en/web-api-ref
+Keywords: unione,fastapi,email,webhook
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: unione-sdk>=1.1.3
+Requires-Dist: fastapi>=0.100
+Dynamic: license-file
+
+# UniOne FastAPI 1.1.3
+
+Web API 1.90
+
+Quickstart guide: [Send emails with Python](https://docs.unione.io/en/send-with-python) · Docs for LLMs: [llms.txt](https://docs.unione.io/llms.txt) · [API reference](https://docs.unione.io/en/web-api-ref)
+
+FastAPI integration of the [UniOne Python SDK](https://github.com/unione-repo/unione-python-sdk) (``): the API client in the dependencies (`Depends(get_client)`), a webhook endpoint with signature check.
+
+## Install
+
+```bash
+pip install unione-fastapi
+```
+
+Requirements: Python 3.8+, FastAPI 0.100+.
+
+## 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:
+
+```bash
+UNIONE_API_KEY=YOUR_API_KEY
+UNIONE_HOST=us1.unione.io
+```
+
+| Option | Environment variable | Default | Description |
+|---|---|---|---|
+| `Settings.api_key` | `UNIONE_API_KEY` |  | User or project API key (required). |
+| `Settings.host` | `UNIONE_HOST` | `api.unione.io` | API host (datacenter: `api.unione.io`, `eu1.unione.io`, `us1.unione.io`) or a full base URL. |
+| `Settings.timeout` | `UNIONE_TIMEOUT` | `30` | Request timeout, seconds. |
+| `Settings.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. |
+| `Settings.webhook_path` | `UNIONE_WEBHOOK_PATH` | `/unione/webhook` | Path of the webhook endpoint. |
+
+Other settings in code: `app.dependency_overrides[get_settings] = lambda: Settings(api_key=...)`.
+
+## 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.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+
+
+@app.post("/sandbox-domain")
+def get_sandbox_domain(client: UniOneClient = Depends(get_client)):
+    response = client.domain.get_sandbox_domain()
+    return {"domain": response.domain}
+```
+
+**2. Confirm your inbox** (`confirmed-email/create`). UniOne sends a confirmation email; click the link in it within 48 hours.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.confirmed_email import ConfirmedEmailRequest
+
+
+@app.post("/confirm-email")
+def confirm_email(client: UniOneClient = Depends(get_client)):
+    response = client.confirmed_email.create(ConfirmedEmailRequest(
+        email="you@example.com",
+    ))
+    return {"status": 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.
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
+from unione.common import BodyObject
+
+
+@app.post("/send")
+def send(client: UniOneClient = Depends(get_client)):
+    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>",
+        ),
+    ))
+    return {"job_id": 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>"
+          }
+        }
+      }'
+```
+
+## 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.
+
+```python
+from unione_wrapper import Webhooks
+
+webhooks = Webhooks()
+
+
+@webhooks.on_event
+async def on_event(event, user):
+    data = event.event_data
+    print(event.event_name, data.email, data.status)
+
+
+app.include_router(webhooks.router())  # /unione/webhook
+```
+
+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-python-sdk).
+
+```python
+from fastapi import Depends, FastAPI
+from unione import UniOneClient
+from unione_wrapper import get_client
+
+app = FastAPI()
+
+
+@app.get("/usage")
+def usage(client: UniOneClient = Depends(get_client)):  # the client is synchronous: a def endpoint
+    info = client.system.info()
+    return {"emails_sent": info.accounting.emails_sent if info.accounting else None}
+```
+
+## Sending through the API
+
+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: [Python SDK docs](https://github.com/unione-repo/unione-python-sdk/blob/HEAD/docs/Email.md#send).
+
+```python
+from fastapi import Depends
+from unione import UniOneClient
+from unione_wrapper import get_client
+from unione.api.email import EmailSendRequest, MessageObject, MessageObjectRecipientsItem
+from unione.common import BodyObject
+
+
+@app.post("/send")
+def send(client: UniOneClient = Depends(get_client)):
+    response = client.email.send(EmailSendRequest(
+        message=MessageObject(
+            recipients=[
+                MessageObjectRecipientsItem(
+                    email="user@example.com",
+                    substitutions={
+                        "CustomerId": "12452",
+                        "to_name": "John Smith",
+                    },
+                ),
+            ],
+            body=BodyObject(
+                html="<b>Hello, {{to_name}}</b>",
+                plaintext="Hello, {{to_name}}",
+            ),
+            subject="UniOne test email ",
+            from_email="email@example.com",
+            from_name="John Smith",
+        ),
+    ))
+    return {"job_id": 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 Python](https://docs.unione.io/en/send-with-python) 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.

unione_fastapi-1.1.3/src/unione_fastapi.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/unione_fastapi.egg-info/PKG-INFO
+src/unione_fastapi.egg-info/SOURCES.txt
+src/unione_fastapi.egg-info/dependency_links.txt
+src/unione_fastapi.egg-info/requires.txt
+src/unione_fastapi.egg-info/top_level.txt
+src/unione_wrapper/__init__.py
+src/unione_wrapper/_settings.py
+src/unione_wrapper/py.typed
+src/unione_wrapper/signature.py
+src/unione_wrapper/webhook.py

unione_fastapi-1.1.3/src/unione_fastapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

unione_fastapi-1.1.3/src/unione_fastapi.egg-info/requires.txt

@@ -0,0 +1,2 @@
+unione-sdk>=1.1.3
+fastapi>=0.100

unione_fastapi-1.1.3/src/unione_fastapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+unione_wrapper

unione_fastapi-1.1.3/src/unione_wrapper/__init__.py

@@ -0,0 +1,106 @@
+"""UniOne Web API for FastAPI: client dependency, webhooks.
+
+    webhooks = Webhooks()
+
+    @webhooks.on_event
+    async def on_event(event, user): ...
+
+    app.include_router(webhooks.router())
+
+    @app.get("/usage")
+    def usage(client: UniOneClient = Depends(get_client)): ...
+
+Settings come from the environment variables UNIONE_*; replace them with
+app.dependency_overrides[get_settings] = lambda: Settings(api_key=...).
+"""
+from __future__ import annotations
+
+import inspect
+from functools import lru_cache
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import PlainTextResponse
+from unione import UniOneClient
+
+from . import webhook as notifications
+from ._settings import Settings
+from .webhook import WebhookCallback, WebhookCallbackEventsByUserItemEventsItem, WebhookCallbackEventsByUserItem
+
+__all__ = ["Settings", "Webhooks", "get_client", "get_settings"]
+__version__ = "1.1.3"
+
+
+@lru_cache(maxsize=None)
+def get_settings() -> Settings:
+    """Settings from the environment variables UNIONE_* (dependency, can be overridden)."""
+    return Settings.load()
+
+
+@lru_cache(maxsize=None)
+def _client(settings: Settings) -> UniOneClient:
+    return UniOneClient(settings.require_key(), settings.host, settings.timeout, platform="fastapi.1.1.3")
+
+
+def get_client(settings: Settings = Depends(get_settings)) -> UniOneClient:
+    """Dependency: the UniOne API client of the settings (one instance per settings).
+
+    The client is synchronous: use it in `def` endpoints (FastAPI runs them in a thread pool).
+    """
+    return _client(settings)
+
+
+NotificationHandler = Callable[[WebhookCallback, Dict[str, Any]], Union[None, Awaitable[None]]]
+EventHandler = Callable[[WebhookCallbackEventsByUserItemEventsItem, WebhookCallbackEventsByUserItem], Union[None, Awaitable[None]]]
+
+
+async def _call(handler: Callable[..., Any], *args: Any) -> None:
+    value = handler(*args)
+    if inspect.isawaitable(value):
+        await value
+
+
+class Webhooks:
+    """Handlers of the webhook notifications and the router of the endpoint.
+
+    GET/HEAD -> 200 (URL check of webhook/set), POST -> signature check, then every on_notification handler
+    with (callback, payload) and every on_event handler with (event, user) for each event. Handlers may be sync
+    or async; keep them fast, the API waits for 200 OK for 3 seconds only.
+    """
+
+    def __init__(self) -> None:
+        self.notification_handlers: List[NotificationHandler] = []
+        self.event_handlers: List[EventHandler] = []
+
+    def on_notification(self, handler: NotificationHandler) -> NotificationHandler:
+        self.notification_handlers.append(handler)
+        return handler
+
+    def on_event(self, handler: EventHandler) -> EventHandler:
+        self.event_handlers.append(handler)
+        return handler
+
+    async def handle(self, body: bytes, settings: Settings) -> PlainTextResponse:
+        try:
+            callback, payload = notifications.parse(body, settings.signing_key)
+        except notifications.WebhookError as e:
+            return PlainTextResponse(str(e), status_code=e.status)
+        for handler in self.notification_handlers:
+            await _call(handler, callback, payload)
+        for event, user in notifications.events(callback):
+            for event_handler in self.event_handlers:
+                await _call(event_handler, event, user)
+        return PlainTextResponse("OK")
+
+    def router(self, path: Optional[str] = None, **kwargs: Any) -> APIRouter:
+        """Router with the endpoint at path (default: UNIONE_WEBHOOK_PATH or /unione/webhook); kwargs go to APIRouter."""
+        router = APIRouter(**kwargs)
+
+        async def webhook(request: Request, settings: Settings = Depends(get_settings)) -> PlainTextResponse:
+            if request.method != "POST":
+                return PlainTextResponse("OK")
+            return await self.handle(await request.body(), settings)
+
+        router.add_api_route(path or get_settings().webhook_path, webhook, methods=["GET", "HEAD", "POST"],
+                             include_in_schema=False, name="unione_webhook")
+        return router

unione_fastapi-1.1.3/src/unione_wrapper/_settings.py

@@ -0,0 +1,53 @@
+"""Settings of the UniOne API: environment variables UNIONE_* with overrides of the framework config."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+ENV_PREFIX = "UNIONE_"
+DEFAULT_WEBHOOK_PATH = "/unione/webhook"
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: str = ""
+    """User or project API key."""
+
+    host: Optional[str] = None
+    """API host (datacenter: api.unione.io, eu1.unione.io, us1.unione.io) or a full base URL; None: the default one."""
+
+    timeout: float = 30.0
+    """Request timeout, seconds."""
+
+    webhook_key: Optional[str] = None
+    """API key the webhooks are signed with; None: api_key."""
+
+    webhook_path: str = DEFAULT_WEBHOOK_PATH
+    """Path of the webhook endpoint."""
+
+    @property
+    def signing_key(self) -> str:
+        return self.webhook_key or self.api_key
+
+    @classmethod
+    def load(cls, overrides: Optional[Mapping[str, Any]] = None, environ: Optional[Mapping[str, str]] = None) -> "Settings":
+        """Environment variables UNIONE_API_KEY, ..._HOST, ..._TIMEOUT, ..._WEBHOOK_KEY, ..._WEBHOOK_PATH; overrides
+        (keys api_key, host, ... in any case) win over them."""
+        env = os.environ if environ is None else environ
+        values = {key: env.get(ENV_PREFIX + key.upper()) for key in ("api_key", "host", "timeout", "webhook_key", "webhook_path")}
+        for key, value in (overrides or {}).items():
+            if key.lower() in values and value is not None:
+                values[key.lower()] = value
+        return cls(
+            api_key=str(values["api_key"] or ""),
+            host=str(values["host"]) if values["host"] else None,
+            timeout=float(values["timeout"] or 30.0),
+            webhook_key=str(values["webhook_key"]) if values["webhook_key"] else None,
+            webhook_path=str(values["webhook_path"] or DEFAULT_WEBHOOK_PATH),
+        )
+
+    def require_key(self) -> str:
+        if not self.api_key:
+            raise RuntimeError("UniOne: the API key is not set (UNIONE_API_KEY).")
+        return self.api_key

unione_fastapi-1.1.3/src/unione_wrapper/signature.py

@@ -0,0 +1,33 @@
+"""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."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+from typing import Union
+
+_AUTH = re.compile(rb'"auth"\s*:\s*"([0-9a-fA-F]{32})"')
+PLACEHOLDER = "0" * 32
+
+
+def _bytes(value: Union[bytes, str]) -> bytes:
+    return value.encode("utf-8") if isinstance(value, str) else value
+
+
+def verify(body: Union[bytes, str], api_key: str) -> bool:
+    """True when the "auth" field of the body is its signature made with api_key."""
+    body = _bytes(body)
+    match = _AUTH.search(body)
+    if not api_key or match is None:
+        return False
+    auth = match.group(1)
+    expected = hashlib.md5(body.replace(auth, _bytes(api_key))).hexdigest()
+    return hmac.compare_digest(expected, auth.decode("ascii").lower())
+
+
+def sign(body: Union[bytes, str], api_key: str, placeholder: str = PLACEHOLDER) -> bytes:
+    """Signs a body whose "auth" is the placeholder (32 hex digits), e.g. for tests."""
+    body = _bytes(body)
+    auth = hashlib.md5(body.replace(_bytes(placeholder), _bytes(api_key))).hexdigest()
+    return body.replace(_bytes(placeholder), auth.encode("ascii"))

unione_fastapi-1.1.3/src/unione_wrapper/webhook.py

@@ -0,0 +1,39 @@
+"""Webhook notifications: signature check, parsing, events."""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Iterator, Tuple, Union
+
+from unione.api.webhook import WebhookApi, WebhookCallback, WebhookCallbackEventsByUserItem, WebhookCallbackEventsByUserItemEventsItem
+
+from . import signature
+
+__all__ = ["WebhookError", "parse", "events", "WebhookCallback", "WebhookCallbackEventsByUserItem", "WebhookCallbackEventsByUserItemEventsItem"]
+
+
+class WebhookError(Exception):
+    """Rejected notification: status is the HTTP status of the answer (401 signature, 400 body)."""
+
+    def __init__(self, message: str, status: int) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+def parse(body: Union[bytes, str], api_key: str) -> Tuple[WebhookCallback, Dict[str, Any]]:
+    """Checks the signature and parses the notification: (callback model, decoded body)."""
+    if not signature.verify(body, api_key):
+        raise WebhookError("Invalid signature", 401)
+    text = body.decode("utf-8") if isinstance(body, bytes) else body
+    try:
+        payload = json.loads(text)
+        callback = WebhookApi.parse_callback(text)
+    except (ValueError, TypeError, KeyError, AttributeError) as e:
+        raise WebhookError(f"Invalid body: {e}", 400) from e
+    return callback, payload
+
+
+def events(callback: WebhookCallback) -> Iterator[Tuple[WebhookCallbackEventsByUserItemEventsItem, WebhookCallbackEventsByUserItem]]:
+    """Every event of the notification with its user/project."""
+    for user in callback.events_by_user or []:
+        for event in user.events or []:
+            yield event, user