parcelwing 0.1.0__py3-none-any.whl

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",
+]

parcelwing/_http.py

@@ -0,0 +1,176 @@
+"""Internal HTTP transport for the Parcel Wing SDK."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from .errors import ParcelWingError, ParcelWingErrorType
+
+SDK_VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://parcelwing.com"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("ParcelWing client requires a non-empty api_key.")
+
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.headers = dict(headers or {})
+        self._client = http_client
+        self._owns_client = http_client is None
+
+        if self._client is None:
+            self._client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        if self._owns_client and self._client is not None:
+            self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        if self._client is None:
+            raise RuntimeError("Parcel Wing HTTP client is closed.")
+
+        url = f"{self.base_url}{path}"
+        if params:
+            query = to_query_string(params)
+            if query:
+                url = f"{url}?{query}"
+
+        request_headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+            "X-ParcelWing-SDK": f"python/{SDK_VERSION}",
+            **self.headers,
+            **dict(headers or {}),
+        }
+        if json_body is not None:
+            request_headers["Content-Type"] = "application/json"
+
+        try:
+            response = self._client.request(
+                method,
+                url,
+                headers=request_headers,
+                json=json_body,
+                timeout=self.timeout,
+            )
+        except httpx.TimeoutException as exc:
+            raise ParcelWingError(
+                f"Request timed out after {self.timeout}s.",
+                status=408,
+                type="api_error",
+                code="request_timeout",
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise ParcelWingError(
+                str(exc),
+                status=0,
+                type="api_error",
+                code="network_error",
+            ) from exc
+
+        text = response.text
+        parsed = _safe_json_parse(text)
+
+        if response.status_code < 200 or response.status_code >= 300:
+            raise _to_parcelwing_error(response.status_code, parsed, text)
+
+        return parsed
+
+
+def to_query_string(params: Mapping[str, Any]) -> str:
+    clean: Dict[str, str] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            clean[key] = "true" if value else "false"
+        else:
+            clean[key] = str(value)
+    return urlencode(clean)
+
+
+def unwrap_resource(response: Mapping[str, Any]) -> Any:
+    return response.get("data")
+
+
+def _safe_json_parse(value: str) -> Any:
+    if not value:
+        return None
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        return None
+
+
+def _to_parcelwing_error(status: int, parsed: Any, fallback_text: str) -> ParcelWingError:
+    if isinstance(parsed, Mapping) and isinstance(parsed.get("error"), Mapping):
+        error = parsed["error"]
+        message = str(error.get("message") or fallback_text or "Parcel Wing API error.")
+        error_type = str(error.get("type") or "api_error")
+        allowed_types = {
+            "authentication_error",
+            "validation_error",
+            "invalid_request_error",
+            "not_found_error",
+            "conflict_error",
+            "rate_limit_error",
+            "reputation_error",
+            "suppression_error",
+            "api_error",
+        }
+        if error_type not in allowed_types:
+            error_type = "api_error"
+
+        metadata = {
+            str(key): value
+            for key, value in error.items()
+            if key not in {"type", "code", "message", "details", "request_id"}
+        }
+        return ParcelWingError(
+            message,
+            status=status,
+            type=error_type,  # type: ignore[arg-type]
+            code=error.get("code") if isinstance(error.get("code"), str) else None,
+            request_id=error.get("request_id")
+            if isinstance(error.get("request_id"), str)
+            else None,
+            details=error.get("details"),
+            metadata=metadata,
+        )
+
+    return ParcelWingError(
+        fallback_text or f"Parcel Wing API request failed with status {status}.",
+        status=status,
+        type="api_error",
+        code="http_error",
+    )

parcelwing/client.py

@@ -0,0 +1,51 @@
+"""Parcel Wing API client."""
+
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+import httpx
+
+from ._http import DEFAULT_BASE_URL, HttpClient
+from .resources import (
+    AutomationsResource,
+    ContactsResource,
+    EmailsResource,
+    SegmentsResource,
+    TopicsResource,
+)
+
+
+class ParcelWing:
+    """Client for the Parcel Wing API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            http_client=http_client,
+        )
+        self.emails = EmailsResource(self.http)
+        self.contacts = ContactsResource(self.http)
+        self.segments = SegmentsResource(self.http)
+        self.topics = TopicsResource(self.http)
+        self.automations = AutomationsResource(self.http)
+
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> "ParcelWing":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

parcelwing/errors.py

@@ -0,0 +1,54 @@
+"""Parcel Wing SDK exceptions."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Literal, Optional
+
+ParcelWingErrorType = Literal[
+    "authentication_error",
+    "validation_error",
+    "invalid_request_error",
+    "not_found_error",
+    "conflict_error",
+    "rate_limit_error",
+    "reputation_error",
+    "suppression_error",
+    "api_error",
+]
+
+
+class ParcelWingError(Exception):
+    """Raised when a Parcel Wing API request fails."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        type: ParcelWingErrorType = "api_error",
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        details: Any = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.type = type
+        self.code = code
+        self.request_id = request_id
+        self.details = details
+        self.metadata = metadata or {}
+
+    def __repr__(self) -> str:
+        return (
+            "ParcelWingError("
+            f"status={self.status!r}, type={self.type!r}, "
+            f"code={self.code!r}, message={self.message!r})"
+        )
+
+
+def is_parcelwing_error(error: BaseException) -> bool:
+    """Return True when *error* is a ParcelWingError."""
+
+    return isinstance(error, ParcelWingError)

parcelwing/resources/__init__.py

@@ -0,0 +1,13 @@
+from .automations import AutomationsResource
+from .contacts import ContactsResource
+from .emails import EmailsResource
+from .segments import SegmentsResource
+from .topics import TopicsResource
+
+__all__ = [
+    "AutomationsResource",
+    "ContactsResource",
+    "EmailsResource",
+    "SegmentsResource",
+    "TopicsResource",
+]

parcelwing/resources/automations.py

@@ -0,0 +1,18 @@
+"""Automation events resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+
+from .._http import HttpClient
+
+
+class AutomationsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def track(self, event: Mapping[str, Any]) -> Dict[str, Any]:
+        response = self._http.request(
+            "POST", "/api/automations/events", json_body=dict(event)
+        )
+        return dict(response.get("data", {}))

parcelwing/resources/contacts.py

@@ -0,0 +1,47 @@
+"""Contacts resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Sequence, Union
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class ContactsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, **params: Any) -> Dict[str, Any]:
+        return dict(self._http.request("GET", "/api/contacts", params=params))
+
+    def create(
+        self, contact: Union[Mapping[str, Any], Sequence[Mapping[str, Any]]]
+    ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        body: Any
+        if isinstance(contact, Mapping):
+            body = dict(contact)
+        else:
+            body = [dict(item) for item in contact]
+
+        response = self._http.request("POST", "/api/contacts", json_body=body)
+        return response.get("data")
+
+    def get(self, contact_id: str) -> Dict[str, Any]:
+        response = self._http.request(
+            "GET", f"/api/contacts/{quote(contact_id, safe='')}"
+        )
+        return dict(response.get("data", {}))
+
+    def update(self, contact_id: str, contact: Mapping[str, Any]) -> Dict[str, Any]:
+        response = self._http.request(
+            "PATCH",
+            f"/api/contacts/{quote(contact_id, safe='')}",
+            json_body=dict(contact),
+        )
+        return dict(response.get("data", {}))
+
+    def delete(self, contact_id: str) -> Dict[str, Any]:
+        return dict(
+            self._http.request("DELETE", f"/api/contacts/{quote(contact_id, safe='')}")
+        )

parcelwing/resources/emails.py

@@ -0,0 +1,65 @@
+"""Email sending resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+from .._http import HttpClient
+
+EmailRecipient = Union[str, Sequence[str]]
+
+
+class EmailsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def send(
+        self,
+        email: Optional[Mapping[str, Any]] = None,
+        *,
+        from_: Optional[str] = None,
+        to: Optional[EmailRecipient] = None,
+        subject: Optional[str] = None,
+        text: Optional[str] = None,
+        html: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        tags: Optional[Mapping[str, str]] = None,
+        template_id: Optional[str] = None,
+        template_alias: Optional[str] = None,
+        template_params: Optional[Mapping[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Queue one email request.
+
+        Pass either a raw request dict using API field names, or keyword arguments.
+        Because ``from`` is a Python keyword, use ``from_`` with keyword arguments.
+        """
+
+        payload: Dict[str, Any]
+        if email is not None:
+            payload = dict(email)
+        else:
+            payload = {}
+
+        if from_ is not None:
+            payload["from"] = from_
+        if to is not None:
+            payload["to"] = list(to) if not isinstance(to, str) else to
+        if subject is not None:
+            payload["subject"] = subject
+        if text is not None:
+            payload["text"] = text
+        if html is not None:
+            payload["html"] = html
+        if reply_to is not None:
+            payload["reply_to"] = reply_to
+        if tags is not None:
+            payload["tags"] = dict(tags)
+        if template_id is not None:
+            payload["template_id"] = template_id
+        if template_alias is not None:
+            payload["template_alias"] = template_alias
+        if template_params is not None:
+            payload["template_params"] = dict(template_params)
+
+        response = self._http.request("POST", "/api/emails", json_body=payload)
+        return list(response.get("data", []))

parcelwing/resources/segments.py

@@ -0,0 +1,39 @@
+"""Segments resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class SegmentsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, **params: Any) -> Dict[str, Any]:
+        return dict(self._http.request("GET", "/api/segments", params=params))
+
+    def create(self, segment: Mapping[str, Any]) -> Dict[str, Any]:
+        response = self._http.request("POST", "/api/segments", json_body=dict(segment))
+        return dict(response.get("data", {}))
+
+    def get(self, segment_id: str) -> Dict[str, Any]:
+        response = self._http.request(
+            "GET", f"/api/segments/{quote(segment_id, safe='')}"
+        )
+        return dict(response.get("data", {}))
+
+    def update(self, segment_id: str, segment: Mapping[str, Any]) -> Dict[str, Any]:
+        response = self._http.request(
+            "PATCH",
+            f"/api/segments/{quote(segment_id, safe='')}",
+            json_body=dict(segment),
+        )
+        return dict(response.get("data", {}))
+
+    def delete(self, segment_id: str) -> Dict[str, Any]:
+        return dict(
+            self._http.request("DELETE", f"/api/segments/{quote(segment_id, safe='')}")
+        )

parcelwing/resources/topics.py

@@ -0,0 +1,37 @@
+"""Topics resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+from urllib.parse import quote
+
+from .._http import HttpClient
+
+
+class TopicsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, **params: Any) -> Dict[str, Any]:
+        return dict(self._http.request("GET", "/api/topics", params=params))
+
+    def create(self, topic: Mapping[str, Any]) -> Dict[str, Any]:
+        response = self._http.request("POST", "/api/topics", json_body=dict(topic))
+        return dict(response.get("data", {}))
+
+    def get(self, topic_id: str) -> Dict[str, Any]:
+        response = self._http.request("GET", f"/api/topics/{quote(topic_id, safe='')}")
+        return dict(response.get("data", {}))
+
+    def update(self, topic_id: str, topic: Mapping[str, Any]) -> Dict[str, Any]:
+        response = self._http.request(
+            "PATCH",
+            f"/api/topics/{quote(topic_id, safe='')}",
+            json_body=dict(topic),
+        )
+        return dict(response.get("data", {}))
+
+    def delete(self, topic_id: str) -> Dict[str, Any]:
+        return dict(
+            self._http.request("DELETE", f"/api/topics/{quote(topic_id, safe='')}")
+        )

parcelwing/types.py

@@ -0,0 +1,245 @@
+"""Type definitions for the Parcel Wing API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+NullablePrimitive = Union[str, int, float, bool, None]
+JsonObject = Dict[str, Any]
+
+
+class Pagination(TypedDict):
+    page: int
+    limit: int
+    total: int
+    total_pages: int
+    has_next: bool
+    has_prev: bool
+
+
+class ListResponse(TypedDict, total=False):
+    object: Literal["list"]
+    data: List[Any]
+    pagination: Pagination
+
+
+class DeletionResponse(TypedDict):
+    object: str
+    id: str
+    deleted: Literal[True]
+
+
+class ApiErrorPayload(TypedDict, total=False):
+    type: str
+    code: str
+    message: str
+    details: Any
+    request_id: str
+
+
+ContactStatus = Literal[
+    "active", "unsubscribed", "bounced", "spam_complaint", "inactive"
+]
+
+
+class Contact(TypedDict, total=False):
+    object: Literal["contact"]
+    id: str
+    email: str
+    first_name: Optional[str]
+    last_name: Optional[str]
+    full_name: Optional[str]
+    attributes: Dict[str, NullablePrimitive]
+    status: ContactStatus
+    source: Optional[str]
+    external_id: Optional[str]
+    metadata: JsonObject
+    created_at: str
+    updated_at: str
+    subscribed_at: Optional[str]
+    unsubscribed_at: Optional[str]
+
+
+class ContactCreateRequest(TypedDict, total=False):
+    email: str
+    first_name: str
+    last_name: str
+    attributes: Dict[str, NullablePrimitive]
+    status: ContactStatus
+    external_id: str
+    metadata: JsonObject
+
+
+ContactUpdateRequest = ContactCreateRequest
+
+
+class ContactListParams(TypedDict, total=False):
+    page: int
+    limit: int
+    status: ContactStatus
+    search: str
+    external_id: str
+    sort_by: Literal["created_at", "updated_at", "email", "first_name", "last_name"]
+    sort_order: Literal["asc", "desc"]
+
+
+class BatchCreateContactsResult(TypedDict):
+    created: List[Contact]
+    failed: List[Dict[str, str]]
+
+
+SegmentFilterField = Literal[
+    "email",
+    "first_name",
+    "last_name",
+    "full_name",
+    "status",
+    "source",
+    "external_id",
+    "created_at",
+    "updated_at",
+    "subscribed_at",
+    "unsubscribed_at",
+    "attribute",
+]
+SegmentFilterOperator = Literal[
+    "equals",
+    "not_equals",
+    "contains",
+    "not_contains",
+    "starts_with",
+    "ends_with",
+    "is_empty",
+    "is_not_empty",
+    "before",
+    "after",
+    "on_or_before",
+    "on_or_after",
+]
+
+
+class SegmentFilterCondition(TypedDict, total=False):
+    id: str
+    field: SegmentFilterField
+    operator: SegmentFilterOperator
+    value: Union[str, int, float, bool]
+    attribute_key: str
+
+
+class SegmentFilterCriteria(TypedDict):
+    version: Literal[1]
+    match: Literal["all", "any"]
+    conditions: List[SegmentFilterCondition]
+
+
+class Segment(TypedDict, total=False):
+    object: Literal["segment"]
+    id: str
+    name: str
+    description: Optional[str]
+    filter_criteria: SegmentFilterCriteria
+    type: Optional[str]
+    contact_count: int
+    is_active: bool
+    metadata: Optional[JsonObject]
+    created_at: str
+    updated_at: str
+
+
+class SegmentCreateRequest(TypedDict, total=False):
+    name: str
+    description: str
+    filter_criteria: SegmentFilterCriteria
+    is_active: bool
+
+
+SegmentUpdateRequest = SegmentCreateRequest
+
+
+class SegmentListParams(TypedDict, total=False):
+    page: int
+    limit: int
+    search: str
+    active: bool
+    include_counts: bool
+    sort_by: Literal["created_at", "updated_at", "name"]
+    sort_order: Literal["asc", "desc"]
+
+
+TopicDefaultSubscription = Literal["opt_in", "opt_out"]
+TopicVisibility = Literal["public", "private"]
+
+
+class Topic(TypedDict, total=False):
+    object: Literal["topic"]
+    id: str
+    name: str
+    description: Optional[str]
+    default_subscription: TopicDefaultSubscription
+    visibility: TopicVisibility
+    is_active: bool
+    subscriber_count: int
+    explicit_subscriber_count: int
+    explicit_unsubscriber_count: int
+    created_at: str
+    updated_at: str
+
+
+class TopicCreateRequest(TypedDict, total=False):
+    name: str
+    description: str
+    default_subscription: TopicDefaultSubscription
+    visibility: TopicVisibility
+    is_active: bool
+
+
+class TopicUpdateRequest(TypedDict, total=False):
+    name: str
+    description: str
+    visibility: TopicVisibility
+    is_active: bool
+
+
+class TopicListParams(TypedDict, total=False):
+    page: int
+    limit: int
+    search: str
+    active: bool
+    visibility: TopicVisibility
+    sort_by: Literal["created_at", "updated_at", "name"]
+    sort_order: Literal["asc", "desc"]
+
+
+class EmailSendRequest(TypedDict, total=False):
+    from_: str
+    to: Union[str, List[str]]
+    subject: str
+    text: str
+    html: str
+    reply_to: str
+    tags: Dict[str, str]
+    template_id: str
+    template_alias: str
+    template_params: Dict[str, NullablePrimitive]
+
+
+class QueuedEmail(TypedDict):
+    object: Literal["email"]
+    id: str
+    to: str
+    status: Literal["queued"]
+
+
+class AutomationTrackRequest(TypedDict, total=False):
+    event_name: str
+    contact_id: Optional[str]
+    payload: Dict[str, Any]
+    event_id: str
+
+
+class AutomationEvent(TypedDict, total=False):
+    object: Literal["automation_event"]
+    event_id: str
+    event_name: str
+    contact_id: Optional[str]
+    queued_runs: int

parcelwing-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+parcelwing/__init__.py,sha256=kbRrVfQSHzGO8W-GhrhUFJZvi0LXWwUK1yytsJLTpwo,263
+parcelwing/_http.py,sha256=mf64ArNP_GUpD9wnUSalVMsPhnktvDMQhmkvzi2SjYY,5314
+parcelwing/client.py,sha256=yXolYUijbfErKqmm6wEm3rmeg8Fv_fxjvwINmmVSOsg,1266
+parcelwing/errors.py,sha256=G2V2EuK9JUz6RD4rWtwz0R0kzfQJ5iicytiybuS03-g,1392
+parcelwing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+parcelwing/types.py,sha256=vb1l56UTjqb5LlCC-74I6tcfDLsCV-BIr13Jgba9Huk,5243
+parcelwing/resources/__init__.py,sha256=ZoOtWbQO-lu1_B5HW9iB0HsgizaM5DXLzX9lavs9e2I,327
+parcelwing/resources/automations.py,sha256=5pHuuqr_mFJbjf3H6vRWxT4-4ezHVTUk1_sWcolg6LA,476
+parcelwing/resources/contacts.py,sha256=azN3T3lvxEoEyGytK7u-CZ5c85_S3uwsNzoUG3VZNKI,1533
+parcelwing/resources/emails.py,sha256=vQhar2lNwdW7mM6NqkP3gKps93rftM4atxc9_iSBALo,2144
+parcelwing/resources/segments.py,sha256=p9ioLihAYvw3AEHvWXdYBnUm-oZMHMqiajOfAvpxIW4,1291
+parcelwing/resources/topics.py,sha256=fe9rr4L1YI4owtcQXdaLb8PCY64y6yBU2MaMOzFOlxY,1235
+parcelwing-0.1.0.dist-info/METADATA,sha256=wGQKNMa204vDnjwwaRkRemQzgC3iK6MvFy1oQcVZTuo,5238
+parcelwing-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+parcelwing-0.1.0.dist-info/licenses/LICENSE,sha256=HLzFoQHltRqtbycfmymCfS1PZvXDeOF0gRdPK6jF0wU,1068
+parcelwing-0.1.0.dist-info/RECORD,,

parcelwing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

parcelwing-0.1.0.dist-info/licenses/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.