sendly-python 0.2.0__tar.gz → 1.0.0__tar.gz

{sendly_python-0.2.0 → sendly_python-1.0.0}/.github/workflows/ci.yml

@@ -5,7 +5,9 @@ on:
     branches: [main]
   pull_request:
   schedule:
-    # Mondays 06:00 UTC -- surface live OpenAPI drift even without a push.
+    # Mondays 06:00 UTC -- surface OpenAPI drift even without a push. Only does
+    # anything once the SENDLY_OPENAPI_URL repository variable is set; see the
+    # drift step at the end of this file.
     - cron: "0 6 * * 1"
 
 # Public repo -> GitHub-hosted standard runners (free for public repos).
@@ -38,15 +40,25 @@ jobs:
         run: pytest tests/test_contract.py
       - name: Pytest
         run: pytest
-      # Non-blocking: diff the vendored spec against the live API so drift shows
-      # up as a warning annotation without failing the build. Runs once (on the
-      # newest interpreter) to avoid duplicate live fetches and annotations.
-      - name: Live OpenAPI drift check (non-blocking)
+      # Non-blocking: diff the vendored spec against the reference contract so
+      # drift shows up as a warning annotation without failing the build. Runs
+      # once (on the newest interpreter) to avoid duplicate reads and annotations.
+      #
+      # This step previously fetched https://api.sendly.now on every push, every
+      # pull request (forks included) and every weekly cron. Syncing the SDK spec
+      # from production is forbidden, so the source is now explicit: the step
+      # compares against whatever the SENDLY_OPENAPI_URL repository variable
+      # names, and SKIPS with a notice when that variable is unset. Until a
+      # maintainer sets it to a non-production contract, this step and the weekly
+      # schedule above are inert by design.
+      - name: OpenAPI drift check (non-blocking)
         id: spec_drift
         if: matrix.python-version == '3.13'
         continue-on-error: true
+        env:
+          SENDLY_OPENAPI_URL: ${{ vars.SENDLY_OPENAPI_URL }}
         run: python scripts/sync_spec.py --check
       - name: Annotate OpenAPI drift
         if: matrix.python-version == '3.13' && steps.spec_drift.outcome == 'failure'
         run: |
-          echo "::warning title=OpenAPI spec drift::Vendored tests/fixtures/openapi.json differs from the live spec at https://api.sendly.now/api/openapi.json. Run 'python scripts/sync_spec.py' and commit the refreshed copy."
+          echo "::warning title=OpenAPI spec drift::Vendored tests/fixtures/openapi.json differs from the contract at \$SENDLY_OPENAPI_URL. Run 'SENDLY_OPENAPI_URL=... python scripts/sync_spec.py' and commit the refreshed copy."

{sendly_python-0.2.0 → sendly_python-1.0.0}/CHANGELOG.md

@@ -3,7 +3,72 @@
 All notable changes to `sendly-python` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.0.0] - 2026-09-02
+
+The default send moves to the versioned API. Everything else in this release is
+additive: the operations an API key can actually reach that the SDK did not yet
+expose.
+
+### Breaking
+
+- **`emails.send()` now posts to `POST /api/v1/emails`** and returns the bare
+  `202` receipt, `{id, status, to, from}`, where `status` is a real delivery
+  state. Before 1.0 it posted to the legacy `POST /api/emails`, which answered
+  with row ids and **no** delivery status, and fanned an array `to` out to
+  several recipients. What changes for a caller:
+  - one recipient in `to`, with `cc` / `bcc` to copy others (an array `to` is
+    no longer accepted);
+  - the result is the receipt, not `{emails, timestamp}` — read
+    `receipt["id"]` and `receipt["status"]` instead of
+    `result["emails"][0]["email"]`;
+  - failures arrive as RFC 9457 problem documents, raised as the **same**
+    exception classes, so `except` blocks are unchanged; `err.error_code` is now
+    the lowercase v1 registry value (`validation_error`, not
+    `VALIDATION_ERROR`) and `err.request_id` / `err.field_errors` are populated.
+
+  The pre-1.0 behaviour is kept, unchanged, as **`emails.send_legacy()`** — the
+  escape hatch for a caller that depends on the fan-out or the envelope.
+  Renaming a call from `send` to `send_legacy` is a complete migration; adopting
+  the new default means reading the receipt instead of the envelope.
+
+  Why now: the legacy send cannot tell a caller whether a message went anywhere,
+  and the versioned one can. Nothing is published against 0.x, so the cost of
+  the move is lowest today and only rises.
+
+### Added
+
+- **`emails.send_legacy()`** — the pre-1.0 `send()`, byte for byte. See Breaking.
+- **`emails.send_test()`** — sandbox test send. The sandbox address is the
+  *sender*; the mail lands in the project owner's own verified inbox. Naming a
+  `from` is refused rather than ignored. Takes no `idempotency_key`.
+- **`mailboxes` resource, reads only** — `list()`, `get(id)` (which carries the
+  IMAP/SMTP `settings` a mail client needs) and `list_app_passwords(id)`
+  (metadata only; the secret is never returned). The mailbox *writes* are not
+  missing but unreachable — see Notes.
+- **`projects.get()`** — the project the credential resolves to. Takes no id.
+  Carries `sandbox_address`, which no public route published before.
+- **`domains.start_setup(id)`** — begins the guided DNS hand-off and returns the
+  route's own `{token, connectUrl, expiresAt}`. Finishing setup means a person
+  opening `connectUrl`, so the SDK hands back the link rather than modelling the
+  flow behind it.
+
+### Notes
+
+- **`send_v1` and `send_test_v1` never shipped.** They existed briefly on `main`
+  between 0.2.0 and this release as the additive step before the repoint, and
+  are folded into `send` and `send_test` here. If you installed from GitHub in
+  that window, rename the calls.
+- **Some operations are permanently not SDK-callable.** Creating and deleting a
+  mailbox, creating and revoking an app password, the API-key operations, and
+  creating a project all resolve the acting user from a session and answer `401`
+  to any API key. They are recorded in `tests/test_contract.py`'s
+  `NOT_SDK_CALLABLE`, which the suite asserts equals the set the contract itself
+  declares — in both directions. Use the dashboard or an OAuth connection.
+- **A project is capped at 10 mailboxes**, counting only ``PROVISIONING``,
+  ``ACTIVE`` and ``SUSPENDED``. ``FAILED`` rows are excluded from the cap but
+  are still returned by ``mailboxes.list()``, so a project that has had failed
+  provisions can list more than 10 — the ``list()`` docstring said "at most 10"
+  without that distinction and now states it.
 
 ## [0.2.0]
 

{sendly_python-0.2.0 → sendly_python-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendly-python
-Version: 0.2.0
+Version: 1.0.0
 Summary: Official Sendly Python SDK
 Project-URL: Homepage, https://sendly.now
 Project-URL: Documentation, https://docs.sendly.now
@@ -33,8 +33,8 @@ Description-Content-Type: text/markdown
 # Sendly Python SDK
 
 Official Python SDK for the [Sendly](https://sendly.now) REST API — transactional
-email, contacts, events, domains, templates, email verification, webhooks, and
-suppression.
+email, contacts, events, domains, templates, email verification, webhooks,
+suppression, and mailbox and project reads.
 
 [![CI](https://github.com/DevinoSolutions/sendly-python/actions/workflows/ci.yml/badge.svg)](https://github.com/DevinoSolutions/sendly-python/actions/workflows/ci.yml)
 
@@ -90,7 +90,7 @@ from sendly import Sendly
 
 sendly = Sendly()  # reads SENDLY_API_KEY
 
-result = sendly.emails.send(
+receipt = sendly.emails.send(
     {
         "from": "hello@yourdomain.com",
         "to": "customer@example.com",
@@ -98,9 +98,35 @@ result = sendly.emails.send(
         "body": "<h1>Thanks for signing up!</h1>",
     }
 )
-print(result["id"])
+
+# `status` is a real delivery state; poll `emails.get(receipt["id"])` for the
+# events behind it.
+print(receipt["id"], receipt["status"])
 ```
 
+### Upgrading from 0.x
+
+**1.0 repoints `emails.send` to the versioned `POST /api/v1/emails`.** It now
+takes one recipient (`cc`/`bcc` copy others) and returns the `202` receipt
+`{id, status, to, from}`, where `status` is a real delivery state. Before 1.0 it
+posted to the legacy `POST /api/emails`, fanned an array `to` out to several
+recipients, and returned `{emails, timestamp}` with no delivery status.
+
+The old behaviour is kept, unchanged, as `emails.send_legacy`. Two ways to
+upgrade:
+
+- **Keep the old shapes:** rename the call. `send(...)` → `send_legacy(...)`.
+  Done.
+- **Take the new default:** read the receipt instead of the envelope
+  (`receipt["id"]` / `receipt["status"]` in place of
+  `result["emails"][0]["email"]`), send to one recipient per call, and note that
+  failures now carry the v1 error fields (`err.error_code` is lowercase,
+  `err.request_id` and `err.field_errors` are set) — the exception classes are
+  the same, so `except` blocks stand.
+
+Nothing else changed shape. See [CHANGELOG.md](./CHANGELOG.md) for the full
+1.0.0 entry.
+
 Or pass the key explicitly:
 
 ```python
@@ -134,9 +160,15 @@ with Sendly() as sendly:
 ### Emails
 
 ```python
-# Single send (pass idempotency_key to dedupe replays for 24h)
-sendly.emails.send({"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"},
-                   idempotency_key="order-42-receipt")
+# Single send on /api/v1 (pass idempotency_key to dedupe replays for 24h).
+# One recipient in `to`; `cc` / `bcc` copy others. Returns {id, status, to, from}.
+receipt = sendly.emails.send({"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"},
+                             idempotency_key="order-42-receipt")
+
+# The pre-1.0 send: legacy /api/emails, an array `to` fans out, answers
+# {emails, timestamp} with no delivery status.
+sendly.emails.send_legacy({"from": "a@you.com", "to": ["b@them.com", "c@them.com"],
+                           "subject": "Hi", "body": "<p>Hi</p>"})
 
 # Batch send (up to 100)
 sendly.emails.batch({"emails": [{"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"}]})
@@ -180,9 +212,45 @@ sendly.domains.list()
 sendly.domains.get("d_123")
 sendly.domains.verify("d_123")
 sendly.domains.get_verification("d_123")
+sendly.domains.start_setup("d_123")  # -> {"token", "connectUrl", "expiresAt"}
 sendly.domains.delete("d_123")
 ```
 
+`start_setup` returns the hand-off as the API returns it. Open `connectUrl` in a
+browser to finish DNS setup at the registrar.
+
+### Mailboxes
+
+Reads only — see [What the SDK does not expose](#what-the-sdk-does-not-expose).
+
+```python
+sendly.mailboxes.list()          # -> [mailbox, ...], not paginated
+detail = sendly.mailboxes.get("mb_123")
+
+# `settings` carries the IMAP and SMTP host, port, security and username.
+print(detail["settings"]["imap"]["host"], detail["settings"]["imap"]["port"])
+
+# Metadata only — `lastFour` is the one fragment of the secret that survives
+# creation, so a credential can be identified but not rebuilt.
+for pw in sendly.mailboxes.list_app_passwords("mb_123"):
+    print(pw["name"], pw["lastFour"], pw["lastUsedAt"])
+```
+
+This lists the mailboxes themselves, never their contents — received messages
+are not part of the public API. The mailbox **password** is never returned by
+any of these reads; mailbox credentials are app passwords, created from the
+dashboard and shown once. `list_app_passwords` returns only the passwords that
+are still active — a revoked one drops out, so this is not an audit history.
+
+**The per-project cap is 10 mailboxes.** It counts only those holding, or
+mid-way to holding, a real account — `PROVISIONING`, `ACTIVE` and `SUSPENDED`.
+`FAILED` rows are excluded on purpose, so that a burst of failed provisions
+cannot eat a project's allowance and turn an outage into "you have reached your
+mailbox limit"; they are still returned by `list()`, so a project that has had
+failures can list more than 10. Exceeding the cap is a `409`
+(`SendlyConflictError`) from whatever creates the mailbox — which is not this
+SDK, since mailbox creation needs a signed-in user.
+
 ### Templates
 
 ```python
@@ -316,7 +384,7 @@ Available on the six cursor-paginated listings: `campaigns.iter_list`,
 `events.list_names` / `events.stats` return a bounded aggregate rather than a
 cursor, so they have no iterator.
 
-### Segments, workflows, events, analytics, usage
+### Segments, workflows, events, analytics, usage, projects
 
 ```python
 segment = sendly.segments.create({"name": "Power users", "type": "DYNAMIC",
@@ -343,8 +411,71 @@ sendly.analytics.top_campaigns({"limit": 5})
 
 usage = sendly.usage.get()
 print(usage["plan"], usage["monthly"])
+
+project = sendly.projects.get()
+print(project["sandbox_address"])
+```
+
+### Emails: `send` vs `send_legacy`
+
+The same split as `events.track` / `events.record`, resolved the other way
+round: since 1.0, `emails.send` IS the versioned send. It posts to
+`/api/v1/emails` and answers `202` with `{id, status, to, from}`, where `status`
+is a real delivery state you can poll on. It takes one recipient — use
+`cc`/`bcc` to copy others — instead of fanning an array out.
+`emails.send_legacy` is the pre-1.0 send on `POST /api/emails`, unchanged: row
+ids, **no delivery status**, array `to` fanned out. See
+[Upgrading from 0.x](#upgrading-from-0x).
+
+```python
+receipt = sendly.emails.send(
+    {"to": "user@example.com", "subject": "hi", "body": "<p>hi</p>"},
+    idempotency_key="order-42",
+)
+print(receipt["status"])
 ```
 
+### Test sends
+
+`emails.send_test` proves the send path works without touching a live
+recipient. Two things about it are easy to get backwards:
+
+- **The sandbox address is the *sender*, not the destination.** It is resolved
+  server-side, and naming a `from` yourself is **refused** rather than ignored —
+  so a request expecting a different sender never gets a success it would
+  misread. `projects.get()["sandbox_address"]` tells you what it sends *from*;
+  the response's `from` says the same thing.
+- **It lands in the project owner's own inbox.** `to` is optional and defaults
+  to the project owner's verified account email, which is the only address a
+  sandbox send may reach — any other value is refused.
+
+```python
+test = sendly.emails.send_test({"subject": "hi", "body": "<p>hi</p>"})
+print(test["to"], test["from"], test["sandbox"])  # sandbox is always True here
+```
+
+Everything else applies unchanged: the same rendering, the same content scan,
+and the same daily and trust-tier caps as a real send. It takes no
+`idempotency_key` — the recipient is the caller's own inbox, a daily cap already
+bounds it, and "send me another one" is the normal second call rather than a
+mistake worth deduplicating.
+
+### What the SDK does not expose
+
+An API key resolves no user, and a handful of routes resolve the acting project
+admin from the session before reading any scope — so they answer `401` to any
+key, however broad its scopes. The contract states this: those operations publish
+`SessionAuth` without `ApiKeyAuth`.
+
+Rather than ship methods that could never succeed, they are listed in
+`tests/test_contract.py`'s `NOT_SDK_CALLABLE` and checked against the spec's own
+declarations, in both directions. They are: creating and deleting a mailbox,
+creating and revoking an app password, all four API-key operations, and creating
+a project. Use the dashboard or an OAuth connection for those.
+
+Mailbox **reads** are exposed — their membership check is conditional, so a key
+really can call them.
+
 ## Error handling
 
 Every non-2xx response raises a `SendlyError` subclass carrying `status_code`,
@@ -456,7 +587,7 @@ comparison and reject a stale or non-numeric timestamp.
 
 ## Async
 
-Only a synchronous client ships in v0.1. An `httpx.AsyncClient`-backed async
+Only a synchronous client ships today. An `httpx.AsyncClient`-backed async
 variant is planned.
 
 ## Development
@@ -474,6 +605,45 @@ pytest
 
 Tests are fully hermetic (httpx `MockTransport`) and hit no network.
 
+### Refreshing the vendored OpenAPI spec
+
+`tests/fixtures/openapi.json` is a committed snapshot of Sendly's OpenAPI
+contract; the contract suite (`tests/test_contract.py`) verifies the SDK surface
+against it and never touches the network.
+
+`scripts/sync_spec.py` requires `SENDLY_OPENAPI_URL`. There is **no default**,
+and in particular it does not default to production:
+
+```bash
+SENDLY_OPENAPI_URL=/path/to/sendly/apps/web/openapi/openapi.json \
+    python scripts/sync_spec.py
+
+SENDLY_OPENAPI_URL=... python scripts/sync_spec.py --check   # is the copy stale?
+```
+
+`SENDLY_OPENAPI_URL` accepts a filesystem path (the normal case — the committed
+contract in the Sendly platform monorepo at `apps/web/openapi/openapi.json`) or
+an `http(s)://` URL of a local or staging API. Running the script with it unset
+exits non-zero and prints what to set.
+
+**Do not point it at `https://api.sendly.now`.** Vendoring the spec from the
+deployed API makes the SDK mirror what is *running* rather than what the repo
+*declares*, so any drift between the platform's code and its committed contract
+is laundered into "correct" on the way in — the SDK re-vendors to match the
+deployment and the mismatch vanishes silently. That destroys the vendored spec's
+only job: it is the fixed reference `tests/test_contract.py` compares against, so
+an SDK synced from production can no longer detect the very drift it exists to
+catch. It is also unreproducible and unreviewable.
+
+This is not hard-blocked — "what does production actually serve?" is a legitimate
+one-off. Doing it prints an unmissable warning (and a CI annotation), because
+*quiet* is what made the old default dangerous, not the host. Never commit the
+result, and never wire that host into CI or any unattended job.
+
+`--check` is the exception to the fail-loud rule: it never runs unattended
+against an unknown source, so with `SENDLY_OPENAPI_URL` unset it skips with a
+notice and exits 0, keeping CI and fork pull requests green.
+
 ## Documentation
 
 Full API reference: <https://docs.sendly.now>

{sendly_python-0.2.0 → sendly_python-1.0.0}/README.md

@@ -1,8 +1,8 @@
 # Sendly Python SDK
 
 Official Python SDK for the [Sendly](https://sendly.now) REST API — transactional
-email, contacts, events, domains, templates, email verification, webhooks, and
-suppression.
+email, contacts, events, domains, templates, email verification, webhooks,
+suppression, and mailbox and project reads.
 
 [![CI](https://github.com/DevinoSolutions/sendly-python/actions/workflows/ci.yml/badge.svg)](https://github.com/DevinoSolutions/sendly-python/actions/workflows/ci.yml)
 
@@ -58,7 +58,7 @@ from sendly import Sendly
 
 sendly = Sendly()  # reads SENDLY_API_KEY
 
-result = sendly.emails.send(
+receipt = sendly.emails.send(
     {
         "from": "hello@yourdomain.com",
         "to": "customer@example.com",
@@ -66,9 +66,35 @@ result = sendly.emails.send(
         "body": "<h1>Thanks for signing up!</h1>",
     }
 )
-print(result["id"])
+
+# `status` is a real delivery state; poll `emails.get(receipt["id"])` for the
+# events behind it.
+print(receipt["id"], receipt["status"])
 ```
 
+### Upgrading from 0.x
+
+**1.0 repoints `emails.send` to the versioned `POST /api/v1/emails`.** It now
+takes one recipient (`cc`/`bcc` copy others) and returns the `202` receipt
+`{id, status, to, from}`, where `status` is a real delivery state. Before 1.0 it
+posted to the legacy `POST /api/emails`, fanned an array `to` out to several
+recipients, and returned `{emails, timestamp}` with no delivery status.
+
+The old behaviour is kept, unchanged, as `emails.send_legacy`. Two ways to
+upgrade:
+
+- **Keep the old shapes:** rename the call. `send(...)` → `send_legacy(...)`.
+  Done.
+- **Take the new default:** read the receipt instead of the envelope
+  (`receipt["id"]` / `receipt["status"]` in place of
+  `result["emails"][0]["email"]`), send to one recipient per call, and note that
+  failures now carry the v1 error fields (`err.error_code` is lowercase,
+  `err.request_id` and `err.field_errors` are set) — the exception classes are
+  the same, so `except` blocks stand.
+
+Nothing else changed shape. See [CHANGELOG.md](./CHANGELOG.md) for the full
+1.0.0 entry.
+
 Or pass the key explicitly:
 
 ```python
@@ -102,9 +128,15 @@ with Sendly() as sendly:
 ### Emails
 
 ```python
-# Single send (pass idempotency_key to dedupe replays for 24h)
-sendly.emails.send({"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"},
-                   idempotency_key="order-42-receipt")
+# Single send on /api/v1 (pass idempotency_key to dedupe replays for 24h).
+# One recipient in `to`; `cc` / `bcc` copy others. Returns {id, status, to, from}.
+receipt = sendly.emails.send({"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"},
+                             idempotency_key="order-42-receipt")
+
+# The pre-1.0 send: legacy /api/emails, an array `to` fans out, answers
+# {emails, timestamp} with no delivery status.
+sendly.emails.send_legacy({"from": "a@you.com", "to": ["b@them.com", "c@them.com"],
+                           "subject": "Hi", "body": "<p>Hi</p>"})
 
 # Batch send (up to 100)
 sendly.emails.batch({"emails": [{"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"}]})
@@ -148,9 +180,45 @@ sendly.domains.list()
 sendly.domains.get("d_123")
 sendly.domains.verify("d_123")
 sendly.domains.get_verification("d_123")
+sendly.domains.start_setup("d_123")  # -> {"token", "connectUrl", "expiresAt"}
 sendly.domains.delete("d_123")
 ```
 
+`start_setup` returns the hand-off as the API returns it. Open `connectUrl` in a
+browser to finish DNS setup at the registrar.
+
+### Mailboxes
+
+Reads only — see [What the SDK does not expose](#what-the-sdk-does-not-expose).
+
+```python
+sendly.mailboxes.list()          # -> [mailbox, ...], not paginated
+detail = sendly.mailboxes.get("mb_123")
+
+# `settings` carries the IMAP and SMTP host, port, security and username.
+print(detail["settings"]["imap"]["host"], detail["settings"]["imap"]["port"])
+
+# Metadata only — `lastFour` is the one fragment of the secret that survives
+# creation, so a credential can be identified but not rebuilt.
+for pw in sendly.mailboxes.list_app_passwords("mb_123"):
+    print(pw["name"], pw["lastFour"], pw["lastUsedAt"])
+```
+
+This lists the mailboxes themselves, never their contents — received messages
+are not part of the public API. The mailbox **password** is never returned by
+any of these reads; mailbox credentials are app passwords, created from the
+dashboard and shown once. `list_app_passwords` returns only the passwords that
+are still active — a revoked one drops out, so this is not an audit history.
+
+**The per-project cap is 10 mailboxes.** It counts only those holding, or
+mid-way to holding, a real account — `PROVISIONING`, `ACTIVE` and `SUSPENDED`.
+`FAILED` rows are excluded on purpose, so that a burst of failed provisions
+cannot eat a project's allowance and turn an outage into "you have reached your
+mailbox limit"; they are still returned by `list()`, so a project that has had
+failures can list more than 10. Exceeding the cap is a `409`
+(`SendlyConflictError`) from whatever creates the mailbox — which is not this
+SDK, since mailbox creation needs a signed-in user.
+
 ### Templates
 
 ```python
@@ -284,7 +352,7 @@ Available on the six cursor-paginated listings: `campaigns.iter_list`,
 `events.list_names` / `events.stats` return a bounded aggregate rather than a
 cursor, so they have no iterator.
 
-### Segments, workflows, events, analytics, usage
+### Segments, workflows, events, analytics, usage, projects
 
 ```python
 segment = sendly.segments.create({"name": "Power users", "type": "DYNAMIC",
@@ -311,8 +379,71 @@ sendly.analytics.top_campaigns({"limit": 5})
 
 usage = sendly.usage.get()
 print(usage["plan"], usage["monthly"])
+
+project = sendly.projects.get()
+print(project["sandbox_address"])
+```
+
+### Emails: `send` vs `send_legacy`
+
+The same split as `events.track` / `events.record`, resolved the other way
+round: since 1.0, `emails.send` IS the versioned send. It posts to
+`/api/v1/emails` and answers `202` with `{id, status, to, from}`, where `status`
+is a real delivery state you can poll on. It takes one recipient — use
+`cc`/`bcc` to copy others — instead of fanning an array out.
+`emails.send_legacy` is the pre-1.0 send on `POST /api/emails`, unchanged: row
+ids, **no delivery status**, array `to` fanned out. See
+[Upgrading from 0.x](#upgrading-from-0x).
+
+```python
+receipt = sendly.emails.send(
+    {"to": "user@example.com", "subject": "hi", "body": "<p>hi</p>"},
+    idempotency_key="order-42",
+)
+print(receipt["status"])
 ```
 
+### Test sends
+
+`emails.send_test` proves the send path works without touching a live
+recipient. Two things about it are easy to get backwards:
+
+- **The sandbox address is the *sender*, not the destination.** It is resolved
+  server-side, and naming a `from` yourself is **refused** rather than ignored —
+  so a request expecting a different sender never gets a success it would
+  misread. `projects.get()["sandbox_address"]` tells you what it sends *from*;
+  the response's `from` says the same thing.
+- **It lands in the project owner's own inbox.** `to` is optional and defaults
+  to the project owner's verified account email, which is the only address a
+  sandbox send may reach — any other value is refused.
+
+```python
+test = sendly.emails.send_test({"subject": "hi", "body": "<p>hi</p>"})
+print(test["to"], test["from"], test["sandbox"])  # sandbox is always True here
+```
+
+Everything else applies unchanged: the same rendering, the same content scan,
+and the same daily and trust-tier caps as a real send. It takes no
+`idempotency_key` — the recipient is the caller's own inbox, a daily cap already
+bounds it, and "send me another one" is the normal second call rather than a
+mistake worth deduplicating.
+
+### What the SDK does not expose
+
+An API key resolves no user, and a handful of routes resolve the acting project
+admin from the session before reading any scope — so they answer `401` to any
+key, however broad its scopes. The contract states this: those operations publish
+`SessionAuth` without `ApiKeyAuth`.
+
+Rather than ship methods that could never succeed, they are listed in
+`tests/test_contract.py`'s `NOT_SDK_CALLABLE` and checked against the spec's own
+declarations, in both directions. They are: creating and deleting a mailbox,
+creating and revoking an app password, all four API-key operations, and creating
+a project. Use the dashboard or an OAuth connection for those.
+
+Mailbox **reads** are exposed — their membership check is conditional, so a key
+really can call them.
+
 ## Error handling
 
 Every non-2xx response raises a `SendlyError` subclass carrying `status_code`,
@@ -424,7 +555,7 @@ comparison and reject a stale or non-numeric timestamp.
 
 ## Async
 
-Only a synchronous client ships in v0.1. An `httpx.AsyncClient`-backed async
+Only a synchronous client ships today. An `httpx.AsyncClient`-backed async
 variant is planned.
 
 ## Development
@@ -442,6 +573,45 @@ pytest
 
 Tests are fully hermetic (httpx `MockTransport`) and hit no network.
 
+### Refreshing the vendored OpenAPI spec
+
+`tests/fixtures/openapi.json` is a committed snapshot of Sendly's OpenAPI
+contract; the contract suite (`tests/test_contract.py`) verifies the SDK surface
+against it and never touches the network.
+
+`scripts/sync_spec.py` requires `SENDLY_OPENAPI_URL`. There is **no default**,
+and in particular it does not default to production:
+
+```bash
+SENDLY_OPENAPI_URL=/path/to/sendly/apps/web/openapi/openapi.json \
+    python scripts/sync_spec.py
+
+SENDLY_OPENAPI_URL=... python scripts/sync_spec.py --check   # is the copy stale?
+```
+
+`SENDLY_OPENAPI_URL` accepts a filesystem path (the normal case — the committed
+contract in the Sendly platform monorepo at `apps/web/openapi/openapi.json`) or
+an `http(s)://` URL of a local or staging API. Running the script with it unset
+exits non-zero and prints what to set.
+
+**Do not point it at `https://api.sendly.now`.** Vendoring the spec from the
+deployed API makes the SDK mirror what is *running* rather than what the repo
+*declares*, so any drift between the platform's code and its committed contract
+is laundered into "correct" on the way in — the SDK re-vendors to match the
+deployment and the mismatch vanishes silently. That destroys the vendored spec's
+only job: it is the fixed reference `tests/test_contract.py` compares against, so
+an SDK synced from production can no longer detect the very drift it exists to
+catch. It is also unreproducible and unreviewable.
+
+This is not hard-blocked — "what does production actually serve?" is a legitimate
+one-off. Doing it prints an unmissable warning (and a CI annotation), because
+*quiet* is what made the old default dangerous, not the host. Never commit the
+result, and never wire that host into CI or any unattended job.
+
+`--check` is the exception to the fail-loud rule: it never runs unattended
+against an unknown source, so with `SENDLY_OPENAPI_URL` unset it skips with a
+notice and exits 0, keeping CI and fork pull requests green.
+
 ## Documentation
 
 Full API reference: <https://docs.sendly.now>

{sendly_python-0.2.0 → sendly_python-1.0.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 # the PyPI trusted-publisher configuration). The import package is
 # unchanged (`import sendly`) — see [tool.hatch.build.targets.wheel] below.
 name = "sendly-python"
-version = "0.2.0"
+version = "1.0.0"
 description = "Official Sendly Python SDK"
 readme = "README.md"
 requires-python = ">=3.10"