feat: add typed Python SDK (#213)

Author: KMKoushik

.github/workflows/release-python-package.yml

@@ -0,0 +1,43 @@
+name: Publish Python package
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/python-sdk/**" # Trigger only changes within sdk/python
+      - ".github/workflows/release-python-package.yml"
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/python-sdk
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: snok/install-poetry@v1
+        with:
+          version: "1.8.2"
+          virtualenvs-create: false
+
+      - name: Build package with Poetry
+        run: poetry build --no-interaction
+
+      - name: List contents of dist
+        run: ls -la dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.4.2
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages_dir: packages/python-sdk/dist

.gitignore

@@ -40,4 +40,5 @@ yarn-error.log*
 *.pem
 prod_db.tar
 
-bin
+bin
+__pycache__

apps/docs/docs.json

@@ -27,6 +27,7 @@
             "pages": [
               "introduction",
               "get-started/nodejs",
+              "get-started/python",
               "get-started/local",
               "get-started/self-hosting",
               "get-started/smtp"
@@ -138,4 +139,4 @@
       "github": "https://github.com/usesend"
     }
   }
-}
+}

apps/docs/get-started/python.mdx

@@ -0,0 +1,164 @@
+---
+title: Python SDK
+description: Official UseSend Python SDK for sending emails and managing contacts.
+icon: python
+---
+
+This guide shows how to install and use the official `usesend` Python SDK.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install usesend
+```
+
+## Initialize
+
+```python
+from usesend import UseSend, types
+
+
+# Option A: pass values directly (helpful in scripts/tests)
+client = UseSend("us_xxx")
+
+# Option B: custom base URL (self-hosted)
+client = UseSend("us_xxx", url="https://your-domain.example")
+```
+
+## Send an email
+
+`EmailCreate` is a TypedDict for editor hints; at runtime you pass a regular dict. The client accepts `from` or `from_` (it normalizes `from_` to `from`).
+
+```python
+from usesend import UseSend, types
+
+client = UseSend("us_xxx")
+
+payload: types.EmailCreate = {
+    "to": "user@example.com",
+    "from": "no-reply@yourdomain.com",
+    "subject": "Welcome",
+    "html": "<strong>Hello!</strong>",
+}
+
+data, err = client.emails.send(payload)
+print(data or err)
+```
+
+Attachments and scheduling:
+
+```python
+from datetime import datetime, timedelta
+
+payload: types.EmailCreate = {
+    "to": ["user1@example.com", "user2@example.com"],
+    "from": "no-reply@yourdomain.com",
+    "subject": "Report",
+    "text": "See attached.",
+    "attachments": [
+        {"filename": "report.txt", "content": "SGVsbG8gd29ybGQ="},  # base64
+    ],
+    "scheduledAt": datetime.utcnow() + timedelta(minutes=10),
+}
+data, err = client.emails.create(payload)
+```
+
+## Batch send
+
+```python
+items: list[types.EmailBatchItem] = [
+    {"to": "a@example.com", "from": "no-reply@yourdomain.com", "subject": "A", "html": "<p>A</p>"},
+    {"to": "b@example.com", "from": "no-reply@yourdomain.com", "subject": "B", "html": "<p>B</p>"},
+]
+data, err = client.emails.batch(items)
+```
+
+## Retrieve and manage emails
+
+Get an email:
+
+```python
+email, err = client.emails.get("email_123")
+```
+
+Update schedule time:
+
+```python
+from datetime import datetime, timedelta
+
+update: types.EmailUpdate = {"scheduledAt": datetime.utcnow() + timedelta(hours=1)}
+data, err = client.emails.update("email_123", update)
+```
+
+Cancel a scheduled email:
+
+```python
+data, err = client.emails.cancel("email_123")
+```
+
+## Contacts
+
+All contact operations require a contact book ID (`book_id`).
+
+Create a contact:
+
+```python
+create: types.ContactCreate = {
+    "email": "user@example.com",
+    "firstName": "Jane",
+    "properties": {"plan": "pro"},
+}
+data, err = client.contacts.create("book_123", create)
+```
+
+Get a contact:
+
+```python
+contact, err = client.contacts.get("book_123", "contact_456")
+```
+
+Update a contact:
+
+```python
+update: types.ContactUpdate = {"subscribed": False}
+data, err = client.contacts.update("book_123", "contact_456", update)
+```
+
+Upsert a contact:
+
+```python
+upsert: types.ContactUpsert = {
+    "email": "user@example.com",
+    "firstName": "Jane",
+}
+data, err = client.contacts.upsert("book_123", "contact_456", upsert)
+```
+
+Delete a contact:
+
+```python
+data, err = client.contacts.delete(book_id="book_123", contact_id="contact_456")
+```
+
+## Error handling
+
+By default the client raises `UseSendHTTPError` for non-2xx responses. To handle errors as return values, pass `raise_on_error=False`.
+
+```python
+from usesend import UseSend, UseSendHTTPError
+
+# Raises exceptions on errors (default)
+client = UseSend("us_xxx")
+try:
+    data, _ = client.emails.get("email_123")
+except UseSendHTTPError as e:
+    print("request failed:", e)
+
+# Returns (None, error) instead of raising
+client = UseSend("us_xxx", raise_on_error=False)
+data, err = client.emails.get("email_123")
+if err:
+    print("error:", err)
+```

apps/docs/introduction.mdx

@@ -37,6 +37,13 @@ Quicklinks to set up your account and get started
     href="/get-started/nodejs"
   >
     Learn how to use our SDK using NodeJS to send emails programmatically.
+  </Card>
+  <Card
+    title="Python"
+    icon="python"
+    href="/get-started/python"
+  >
+    Learn how to use our SDK using Python to send emails programmatically.
   </Card>
     <Card
     title="SMTP support"

packages/python-sdk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 UseSend
+
+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.

packages/python-sdk/README.md

@@ -0,0 +1,61 @@
+# UseSend Python SDK
+
+A minimal Python SDK for the [UseSend](https://usesend.com) API, mirroring the structure of the JavaScript SDK.
+
+## Installation
+
+Install via pip or Poetry:
+
+```
+pip install usesend
+# or
+poetry add usesend
+```
+
+## Usage
+
+```python
+from usesend import UseSend, types
+
+# By default: raises UseSendHTTPError on non-2xx.
+client = UseSend("us_123")
+
+# 1) TypedDict payload (autocomplete in IDEs). Use dict to pass 'from'.
+payload: types.EmailCreate = {
+    "to": "test@example.com",
+    "from": "no-reply@example.com",
+    "subject": "Hello",
+    "html": "<strong>Hi!</strong>",
+}
+resp, _ = client.emails.send(payload=payload)
+
+# 2) Or pass a plain dict (supports 'from')
+resp, _ = client.emails.send(payload={
+    "to": "test@example.com",
+    "from": "no-reply@example.com",
+    "subject": "Hello",
+    "html": "<strong>Hi!</strong>",
+})
+
+# Toggle behavior if desired:
+# - raise_on_error=False: return (None, error_dict) instead of raising
+# No model parsing occurs; methods return plain dicts following the typed shapes.
+client = UseSend("us_123", raise_on_error=False)
+raw, err = client.emails.get(email_id="email_123")
+if err:
+    print("error:", err)
+else:
+    print("ok:", raw)
+```
+
+## Development
+
+This package is managed with Poetry. Models are maintained in-repo under
+`usesend/types.py` (readable names). Update this file as the API evolves.
+
+It is published as `usesend` on PyPI.
+
+Notes
+
+- Human-friendly models are available under `usesend.types` (e.g., `EmailCreate`, `Contact`, `APIError`).
+- Endpoint methods accept TypedDict payloads or plain dicts via the `payload=` keyword.