parcelwing 0.1.0__tar.gz

parcelwing-0.1.0/.env.example

@@ -0,0 +1 @@
+PARCEL_WING_API_KEY=pw_live_xxxxxxxxxxxxxxxxxxxx

parcelwing-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src/parcelwing
+      - name: Test
+        run: pytest

parcelwing-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+.venv/
+.env
+.env.*
+!.env.example

parcelwing-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Python SDK release.
+- Add email sending, contacts, segments, topics, and automation event resources.
+- Add consistent `ParcelWingError` exception mapping.
+- Add examples and tests.

parcelwing-0.1.0/LICENSE

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

parcelwing-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: parcelwing
+Version: 0.1.0
+Summary: Official Python SDK for the Parcel Wing API.
+Project-URL: Homepage, https://parcelwing.com
+Project-URL: Repository, https://github.com/parcelwing/parcelwing-python
+Project-URL: Issues, https://github.com/parcelwing/parcelwing-python/issues
+Author: Parcel Wing
+License: MIT
+License-File: LICENSE
+Keywords: email,marketing-email,parcel-wing,python,sdk,transactional-email
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Parcel Wing Python SDK
+
+The official Python SDK for the Parcel Wing API.
+
+It is designed for a fast, predictable developer experience:
+
+- resource clients for emails, contacts, segments, topics, and automations
+- consistent `ParcelWingError` exceptions
+- typed package metadata and exported type hints
+- small dependency surface built on `httpx`
+- works with the same public API contract used by Parcel Wing itself
+
+## Installation
+
+```bash
+pip install parcelwing
+```
+
+## Quick start
+
+First you'll need an API key. If you don't have one, sign up and create one at https://parcelwing.com/signup. It's free, with no credit card required.
+
+```python
+import os
+
+from parcelwing import ParcelWing
+
+parcel_wing = ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"])
+
+emails = parcel_wing.emails.send(
+    from_="Acme <hello@yourdomain.com>",
+    to="person@example.com",
+    subject="Hello from Parcel Wing",
+    text="It works.",
+)
+
+print(emails[0]["id"])
+```
+
+`from` is a Python keyword, so the keyword-argument API uses `from_`. You can also pass a raw API dictionary if you prefer exact API field names:
+
+```python
+emails = parcel_wing.emails.send({
+    "from": "Acme <hello@yourdomain.com>",
+    "to": "person@example.com",
+    "subject": "Hello from Parcel Wing",
+    "text": "It works.",
+})
+```
+
+## Using templates
+
+```python
+emails = parcel_wing.emails.send(
+    from_="Acme <hello@yourdomain.com>",
+    to="person@example.com",
+    template_alias="welcome_email",
+    template_params={
+        "first_name": "John",
+    },
+)
+```
+
+## Contacts
+
+```python
+contact = parcel_wing.contacts.create({
+    "email": "person@example.com",
+    "first_name": "John",
+    "attributes": {
+        "plan": "pro",
+    },
+})
+
+page = parcel_wing.contacts.list(page=1, limit=20)
+
+print(len(page["data"]), page.get("pagination", {}).get("total"))
+```
+
+Batch create contacts:
+
+```python
+result = parcel_wing.contacts.create([
+    {"email": "one@example.com", "first_name": "One"},
+    {"email": "two@example.com", "first_name": "Two"},
+])
+
+print(result["created"])
+print(result["failed"])
+```
+
+## Segments
+
+```python
+segment = parcel_wing.segments.create({
+    "name": "Pro plan users",
+    "filter_criteria": {
+        "version": 1,
+        "match": "all",
+        "conditions": [
+            {
+                "field": "attribute",
+                "attribute_key": "plan",
+                "operator": "equals",
+                "value": "pro",
+            },
+        ],
+    },
+})
+```
+
+## Topics
+
+```python
+topic = parcel_wing.topics.create({
+    "name": "Product Updates",
+    "description": "Feature launches and release notes.",
+    "default_subscription": "opt_in",
+    "visibility": "public",
+})
+```
+
+## Automation events
+
+```python
+parcel_wing.automations.track({
+    "event_name": "user.completed_onboarding",
+    "contact_id": "6d9dc8f7-c44e-4f2d-8a4e-d04f32f1744f",
+    "payload": {
+        "plan": "flight",
+    },
+})
+```
+
+## Error handling
+
+```python
+from parcelwing import ParcelWingError
+
+try:
+    parcel_wing.emails.send(
+        from_="Acme <hello@yourdomain.com>",
+        to="person@example.com",
+        subject="Hello",
+        text="Hi there",
+    )
+except ParcelWingError as error:
+    print(error.status, error.type, error.code, error.request_id)
+    print(error.details)
+```
+
+## Configuration
+
+```python
+parcel_wing = ParcelWing(
+    api_key=os.environ["PARCEL_WING_API_KEY"],
+    base_url="https://parcelwing.com",
+    timeout=30.0,
+)
+```
+
+Use the client as a context manager to close the underlying HTTP connection pool automatically:
+
+```python
+with ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"]) as parcel_wing:
+    emails = parcel_wing.emails.send(
+        from_="Acme <hello@yourdomain.com>",
+        to="person@example.com",
+        subject="Hello",
+        text="It works.",
+    )
+```
+
+## Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src/parcelwing
+```
+
+## Publishing
+
+```bash
+python -m pip install build twine
+python -m build
+twine upload dist/*
+```

parcelwing-0.1.0/README.md

@@ -0,0 +1,191 @@
+# Parcel Wing Python SDK
+
+The official Python SDK for the Parcel Wing API.
+
+It is designed for a fast, predictable developer experience:
+
+- resource clients for emails, contacts, segments, topics, and automations
+- consistent `ParcelWingError` exceptions
+- typed package metadata and exported type hints
+- small dependency surface built on `httpx`
+- works with the same public API contract used by Parcel Wing itself
+
+## Installation
+
+```bash
+pip install parcelwing
+```
+
+## Quick start
+
+First you'll need an API key. If you don't have one, sign up and create one at https://parcelwing.com/signup. It's free, with no credit card required.
+
+```python
+import os
+
+from parcelwing import ParcelWing
+
+parcel_wing = ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"])
+
+emails = parcel_wing.emails.send(
+    from_="Acme <hello@yourdomain.com>",
+    to="person@example.com",
+    subject="Hello from Parcel Wing",
+    text="It works.",
+)
+
+print(emails[0]["id"])
+```
+
+`from` is a Python keyword, so the keyword-argument API uses `from_`. You can also pass a raw API dictionary if you prefer exact API field names:
+
+```python
+emails = parcel_wing.emails.send({
+    "from": "Acme <hello@yourdomain.com>",
+    "to": "person@example.com",
+    "subject": "Hello from Parcel Wing",
+    "text": "It works.",
+})
+```
+
+## Using templates
+
+```python
+emails = parcel_wing.emails.send(
+    from_="Acme <hello@yourdomain.com>",
+    to="person@example.com",
+    template_alias="welcome_email",
+    template_params={
+        "first_name": "John",
+    },
+)
+```
+
+## Contacts
+
+```python
+contact = parcel_wing.contacts.create({
+    "email": "person@example.com",
+    "first_name": "John",
+    "attributes": {
+        "plan": "pro",
+    },
+})
+
+page = parcel_wing.contacts.list(page=1, limit=20)
+
+print(len(page["data"]), page.get("pagination", {}).get("total"))
+```
+
+Batch create contacts:
+
+```python
+result = parcel_wing.contacts.create([
+    {"email": "one@example.com", "first_name": "One"},
+    {"email": "two@example.com", "first_name": "Two"},
+])
+
+print(result["created"])
+print(result["failed"])
+```
+
+## Segments
+
+```python
+segment = parcel_wing.segments.create({
+    "name": "Pro plan users",
+    "filter_criteria": {
+        "version": 1,
+        "match": "all",
+        "conditions": [
+            {
+                "field": "attribute",
+                "attribute_key": "plan",
+                "operator": "equals",
+                "value": "pro",
+            },
+        ],
+    },
+})
+```
+
+## Topics
+
+```python
+topic = parcel_wing.topics.create({
+    "name": "Product Updates",
+    "description": "Feature launches and release notes.",
+    "default_subscription": "opt_in",
+    "visibility": "public",
+})
+```
+
+## Automation events
+
+```python
+parcel_wing.automations.track({
+    "event_name": "user.completed_onboarding",
+    "contact_id": "6d9dc8f7-c44e-4f2d-8a4e-d04f32f1744f",
+    "payload": {
+        "plan": "flight",
+    },
+})
+```
+
+## Error handling
+
+```python
+from parcelwing import ParcelWingError
+
+try:
+    parcel_wing.emails.send(
+        from_="Acme <hello@yourdomain.com>",
+        to="person@example.com",
+        subject="Hello",
+        text="Hi there",
+    )
+except ParcelWingError as error:
+    print(error.status, error.type, error.code, error.request_id)
+    print(error.details)
+```
+
+## Configuration
+
+```python
+parcel_wing = ParcelWing(
+    api_key=os.environ["PARCEL_WING_API_KEY"],
+    base_url="https://parcelwing.com",
+    timeout=30.0,
+)
+```
+
+Use the client as a context manager to close the underlying HTTP connection pool automatically:
+
+```python
+with ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"]) as parcel_wing:
+    emails = parcel_wing.emails.send(
+        from_="Acme <hello@yourdomain.com>",
+        to="person@example.com",
+        subject="Hello",
+        text="It works.",
+    )
+```
+
+## Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src/parcelwing
+```
+
+## Publishing
+
+```bash
+python -m pip install build twine
+python -m build
+twine upload dist/*
+```

parcelwing-0.1.0/examples/send_email.py

@@ -0,0 +1,14 @@
+import os
+
+from parcelwing import ParcelWing
+
+parcel_wing = ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"])
+
+emails = parcel_wing.emails.send(
+    from_="Acme <hello@yourdomain.com>",
+    to="person@example.com",
+    subject="Hello from Parcel Wing",
+    text="It works.",
+)
+
+print(emails[0]["id"])

parcelwing-0.1.0/examples/send_template_email.py

@@ -0,0 +1,14 @@
+import os
+
+from parcelwing import ParcelWing
+
+parcel_wing = ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"])
+
+emails = parcel_wing.emails.send(
+    from_="Acme <hello@yourdomain.com>",
+    to="person@example.com",
+    template_alias="welcome_email",
+    template_params={"first_name": "John"},
+)
+
+print(emails[0]["id"])

parcelwing-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "parcelwing"
+version = "0.1.0"
+description = "Official Python SDK for the Parcel Wing API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Parcel Wing" }]
+keywords = ["parcel-wing", "email", "transactional-email", "marketing-email", "sdk", "python"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Email",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://parcelwing.com"
+Repository = "https://github.com/parcelwing/parcelwing-python"
+Issues = "https://github.com/parcelwing/parcelwing-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.8",
+  "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parcelwing"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+packages = ["parcelwing"]

parcelwing-0.1.0/src/parcelwing/__init__.py

@@ -0,0 +1,11 @@
+"""Official Python SDK for Parcel Wing."""
+
+from .client import ParcelWing
+from .errors import ParcelWingError, ParcelWingErrorType, is_parcelwing_error
+
+__all__ = [
+    "ParcelWing",
+    "ParcelWingError",
+    "ParcelWingErrorType",
+    "is_parcelwing_error",
+]