agentletter 0.1.0__tar.gz

agentletter-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

agentletter-0.1.0/LICENSE

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

agentletter-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: agentletter
+Version: 0.1.0
+Summary: The physical-mail API for AI agents. Send a real, tracked, compliant letter with one call.
+Project-URL: Homepage, https://agentletter.dev
+Project-URL: Documentation, https://agentletter.dev
+Project-URL: Source, https://github.com/noetiq/agentletter
+Author-email: Falco Schneider <falco@noetiq.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,api,direct-mail,letters,mail,mcp,usps
+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.8
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx<1,>=0.23
+Description-Content-Type: text/markdown
+
+# Agent Letter — Python SDK
+
+The physical-mail API for AI agents. Send a real, tracked, compliant letter with one call — the postal equivalent of giving an agent an email address.
+
+> Private beta. Request access at [agentletter.dev](https://agentletter.dev).
+
+## Install
+
+```bash
+pip install agentletter
+```
+
+## Quickstart
+
+```python
+from agentletter import AgentLetter
+
+client = AgentLetter()  # reads AGENTLETTER_API_KEY from the environment
+
+letter = client.send(
+    to={
+        "name": "Jane Doe",
+        "line1": "1 Market St",
+        "city": "San Francisco",
+        "state": "CA",
+        "zip": "94105",
+    },
+    body=pdf_bytes,     # PDF bytes — or html="..." / template="..."
+    certified=True,     # proof of delivery
+)
+
+print(letter.id, letter.status)  # "ltr_9f2a"  "in_transit"
+```
+
+Set your key once:
+
+```bash
+export AGENTLETTER_API_KEY="sk_live_..."
+```
+
+## Sending content
+
+Provide exactly one of:
+
+```python
+client.send(to=addr, body=pdf_bytes)                       # a PDF
+client.send(to=addr, html="<h1>Notice</h1>...")            # rendered HTML
+client.send(to=addr, template="tmpl_123",
+            variables={"name": "Jane", "amount": "$420"})  # a saved template
+```
+
+Typed addresses are supported too:
+
+```python
+from agentletter import Address
+
+client.send(
+    to=Address(name="Jane Doe", line1="1 Market St",
+               city="San Francisco", state="CA", zip="94105"),
+    body=pdf_bytes,
+)
+```
+
+## Tracking
+
+```python
+letter = client.get("ltr_9f2a")
+print(letter.status, letter.tracking_number, letter.expected_delivery)
+```
+
+## Async
+
+```python
+import asyncio
+from agentletter import AsyncAgentLetter
+
+async def main():
+    async with AsyncAgentLetter() as client:
+        letter = await client.send(to=addr, body=pdf_bytes, certified=True)
+        print(letter.id)
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors subclass `AgentLetterError`:
+
+```python
+from agentletter import AgentLetterError, AuthenticationError, RateLimitError
+
+try:
+    client.send(to=addr, body=pdf_bytes)
+except AuthenticationError:
+    ...   # bad / missing key
+except RateLimitError:
+    ...   # back off and retry
+except AgentLetterError as e:
+    print(e.status_code, e.message)
+```
+
+## License
+
+MIT

agentletter-0.1.0/README.md

@@ -0,0 +1,104 @@
+# Agent Letter — Python SDK
+
+The physical-mail API for AI agents. Send a real, tracked, compliant letter with one call — the postal equivalent of giving an agent an email address.
+
+> Private beta. Request access at [agentletter.dev](https://agentletter.dev).
+
+## Install
+
+```bash
+pip install agentletter
+```
+
+## Quickstart
+
+```python
+from agentletter import AgentLetter
+
+client = AgentLetter()  # reads AGENTLETTER_API_KEY from the environment
+
+letter = client.send(
+    to={
+        "name": "Jane Doe",
+        "line1": "1 Market St",
+        "city": "San Francisco",
+        "state": "CA",
+        "zip": "94105",
+    },
+    body=pdf_bytes,     # PDF bytes — or html="..." / template="..."
+    certified=True,     # proof of delivery
+)
+
+print(letter.id, letter.status)  # "ltr_9f2a"  "in_transit"
+```
+
+Set your key once:
+
+```bash
+export AGENTLETTER_API_KEY="sk_live_..."
+```
+
+## Sending content
+
+Provide exactly one of:
+
+```python
+client.send(to=addr, body=pdf_bytes)                       # a PDF
+client.send(to=addr, html="<h1>Notice</h1>...")            # rendered HTML
+client.send(to=addr, template="tmpl_123",
+            variables={"name": "Jane", "amount": "$420"})  # a saved template
+```
+
+Typed addresses are supported too:
+
+```python
+from agentletter import Address
+
+client.send(
+    to=Address(name="Jane Doe", line1="1 Market St",
+               city="San Francisco", state="CA", zip="94105"),
+    body=pdf_bytes,
+)
+```
+
+## Tracking
+
+```python
+letter = client.get("ltr_9f2a")
+print(letter.status, letter.tracking_number, letter.expected_delivery)
+```
+
+## Async
+
+```python
+import asyncio
+from agentletter import AsyncAgentLetter
+
+async def main():
+    async with AsyncAgentLetter() as client:
+        letter = await client.send(to=addr, body=pdf_bytes, certified=True)
+        print(letter.id)
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors subclass `AgentLetterError`:
+
+```python
+from agentletter import AgentLetterError, AuthenticationError, RateLimitError
+
+try:
+    client.send(to=addr, body=pdf_bytes)
+except AuthenticationError:
+    ...   # bad / missing key
+except RateLimitError:
+    ...   # back off and retry
+except AgentLetterError as e:
+    print(e.status_code, e.message)
+```
+
+## License
+
+MIT

agentletter-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentletter"
+version = "0.1.0"
+description = "The physical-mail API for AI agents. Send a real, tracked, compliant letter with one call."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Falco Schneider", email = "falco@noetiq.com" }]
+keywords = ["ai", "agents", "mail", "direct-mail", "letters", "api", "mcp", "usps"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "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 :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Communications",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.23,<1"]
+
+[project.urls]
+Homepage = "https://agentletter.dev"
+Documentation = "https://agentletter.dev"
+Source = "https://github.com/noetiq/agentletter"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentletter"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/agentletter", "README.md", "LICENSE"]

agentletter-0.1.0/src/agentletter/__init__.py

@@ -0,0 +1,41 @@
+"""Agent Letter — the physical-mail API for AI agents.
+
+Send a real, tracked, compliant letter with one call.
+
+    from agentletter import AgentLetter
+
+    client = AgentLetter()  # reads AGENTLETTER_API_KEY
+    letter = client.send(
+        to={"name": "Jane Doe", "line1": "1 Market St",
+            "city": "San Francisco", "state": "CA", "zip": "94105"},
+        body=pdf_bytes,
+        certified=True,
+    )
+    print(letter.id, letter.status)
+"""
+
+from ._version import __version__
+from .client import AgentLetter, AsyncAgentLetter
+from .errors import (
+    AgentLetterError,
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+)
+from .types import Address, Letter
+
+__all__ = [
+    "__version__",
+    "AgentLetter",
+    "AsyncAgentLetter",
+    "Address",
+    "Letter",
+    "AgentLetterError",
+    "APIError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "RateLimitError",
+]

agentletter-0.1.0/src/agentletter/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agentletter-0.1.0/src/agentletter/client.py

@@ -0,0 +1,262 @@
+"""HTTP client for the Agent Letter API."""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+from typing import Any, Dict, Mapping, Optional, Union
+
+import httpx
+
+from ._version import __version__
+from .errors import APIError, AgentLetterError, error_from_response
+from .types import Address, Letter
+
+DEFAULT_BASE_URL = "https://api.agentletter.dev/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+AddressInput = Union[Address, Mapping[str, Any]]
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("AGENTLETTER_API_KEY")
+    if not key:
+        raise AgentLetterError(
+            "No API key provided. Pass api_key=... or set the "
+            "AGENTLETTER_API_KEY environment variable."
+        )
+    return key
+
+
+def _address_dict(value: AddressInput) -> Dict[str, Any]:
+    if isinstance(value, Address):
+        return value.to_dict()
+    return dict(value)
+
+
+def _build_payload(
+    *,
+    to: AddressInput,
+    body: Optional[bytes],
+    html: Optional[str],
+    template: Optional[str],
+    variables: Optional[Mapping[str, Any]],
+    from_: Optional[AddressInput],
+    certified: bool,
+    color: bool,
+    double_sided: bool,
+    metadata: Optional[Mapping[str, Any]],
+) -> Dict[str, Any]:
+    provided = [name for name, v in (("body", body), ("html", html), ("template", template)) if v is not None]
+    if len(provided) != 1:
+        raise AgentLetterError(
+            "Provide exactly one of: body (PDF bytes), html (str), or template (str). "
+            f"Got: {provided or 'none'}."
+        )
+
+    if body is not None:
+        content: Dict[str, Any] = {"pdf_base64": base64.b64encode(body).decode("ascii")}
+    elif html is not None:
+        content = {"html": html}
+    else:
+        content = {"template": template}
+        if variables:
+            content["variables"] = dict(variables)
+
+    payload: Dict[str, Any] = {
+        "to": _address_dict(to),
+        "body": content,
+        "certified": certified,
+        "color": color,
+        "double_sided": double_sided,
+    }
+    if from_ is not None:
+        payload["from"] = _address_dict(from_)
+    if metadata:
+        payload["metadata"] = dict(metadata)
+    return payload
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    @property
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"agentletter-python/{__version__}",
+        }
+
+    def _parse(self, response: httpx.Response) -> Any:
+        try:
+            data = response.json()
+        except ValueError:
+            data = response.text
+        if response.status_code >= 400:
+            raise error_from_response(response.status_code, data)
+        return data
+
+
+class AgentLetter(_BaseClient):
+    """Synchronous Agent Letter client.
+
+    Example::
+
+        from agentletter import AgentLetter
+
+        client = AgentLetter()  # reads AGENTLETTER_API_KEY
+        letter = client.send(
+            to={"name": "Jane Doe", "line1": "1 Market St",
+                "city": "San Francisco", "state": "CA", "zip": "94105"},
+            body=pdf_bytes,
+            certified=True,
+        )
+        print(letter.id, letter.status)
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client = httpx.Client(base_url=self._base_url, timeout=self._timeout)
+
+    def _request(self, method: str, path: str, *, json: Optional[dict] = None) -> Any:
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, path, headers=self._headers, json=json
+                )
+            except httpx.HTTPError as exc:
+                last_exc = APIError(f"Network error talking to Agent Letter: {exc}")
+                if attempt < self._max_retries:
+                    time.sleep(0.5 * (2**attempt))
+                    continue
+                raise last_exc from exc
+            if response.status_code in (429, 500, 502, 503, 504) and attempt < self._max_retries:
+                time.sleep(0.5 * (2**attempt))
+                continue
+            return self._parse(response)
+        raise last_exc or APIError("Request failed.")
+
+    def send(
+        self,
+        *,
+        to: AddressInput,
+        body: Optional[bytes] = None,
+        html: Optional[str] = None,
+        template: Optional[str] = None,
+        variables: Optional[Mapping[str, Any]] = None,
+        from_: Optional[AddressInput] = None,
+        certified: bool = False,
+        color: bool = False,
+        double_sided: bool = True,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> Letter:
+        """Send a physical letter. Provide one of body / html / template."""
+        payload = _build_payload(
+            to=to, body=body, html=html, template=template, variables=variables,
+            from_=from_, certified=certified, color=color,
+            double_sided=double_sided, metadata=metadata,
+        )
+        data = self._request("POST", "/letters", json=payload)
+        return Letter.from_dict(data)
+
+    def get(self, letter_id: str) -> Letter:
+        """Retrieve a letter by id."""
+        data = self._request("GET", f"/letters/{letter_id}")
+        return Letter.from_dict(data)
+
+    def cancel(self, letter_id: str) -> Letter:
+        """Cancel a letter that has not yet been printed."""
+        data = self._request("POST", f"/letters/{letter_id}/cancel")
+        return Letter.from_dict(data)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "AgentLetter":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncAgentLetter(_BaseClient):
+    """Asynchronous Agent Letter client (same API as :class:`AgentLetter`)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client = httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout)
+
+    async def _request(self, method: str, path: str, *, json: Optional[dict] = None) -> Any:
+        import asyncio
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method, path, headers=self._headers, json=json
+                )
+            except httpx.HTTPError as exc:
+                last_exc = APIError(f"Network error talking to Agent Letter: {exc}")
+                if attempt < self._max_retries:
+                    await asyncio.sleep(0.5 * (2**attempt))
+                    continue
+                raise last_exc from exc
+            if response.status_code in (429, 500, 502, 503, 504) and attempt < self._max_retries:
+                await asyncio.sleep(0.5 * (2**attempt))
+                continue
+            return self._parse(response)
+        raise last_exc or APIError("Request failed.")
+
+    async def send(
+        self,
+        *,
+        to: AddressInput,
+        body: Optional[bytes] = None,
+        html: Optional[str] = None,
+        template: Optional[str] = None,
+        variables: Optional[Mapping[str, Any]] = None,
+        from_: Optional[AddressInput] = None,
+        certified: bool = False,
+        color: bool = False,
+        double_sided: bool = True,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> Letter:
+        payload = _build_payload(
+            to=to, body=body, html=html, template=template, variables=variables,
+            from_=from_, certified=certified, color=color,
+            double_sided=double_sided, metadata=metadata,
+        )
+        data = await self._request("POST", "/letters", json=payload)
+        return Letter.from_dict(data)
+
+    async def get(self, letter_id: str) -> Letter:
+        data = await self._request("GET", f"/letters/{letter_id}")
+        return Letter.from_dict(data)
+
+    async def cancel(self, letter_id: str) -> Letter:
+        data = await self._request("POST", f"/letters/{letter_id}/cancel")
+        return Letter.from_dict(data)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncAgentLetter":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

agentletter-0.1.0/src/agentletter/errors.py

@@ -0,0 +1,67 @@
+"""Exception types raised by the Agent Letter SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class AgentLetterError(Exception):
+    """Base class for all Agent Letter errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+
+
+class AuthenticationError(AgentLetterError):
+    """Raised when the API key is missing or invalid (HTTP 401/403)."""
+
+
+class InvalidRequestError(AgentLetterError):
+    """Raised when the request is malformed or fails validation (HTTP 400/422)."""
+
+
+class NotFoundError(AgentLetterError):
+    """Raised when a resource does not exist (HTTP 404)."""
+
+
+class RateLimitError(AgentLetterError):
+    """Raised when the rate limit is exceeded (HTTP 429)."""
+
+
+class APIError(AgentLetterError):
+    """Raised for unexpected server errors (HTTP 5xx) or transport failures."""
+
+
+def error_from_response(status_code: int, body: Any) -> AgentLetterError:
+    """Map an HTTP status code + parsed body to the right exception type."""
+    message = _extract_message(body) or f"Agent Letter request failed ({status_code})."
+    if status_code in (401, 403):
+        return AuthenticationError(message, status_code=status_code, body=body)
+    if status_code == 404:
+        return NotFoundError(message, status_code=status_code, body=body)
+    if status_code == 429:
+        return RateLimitError(message, status_code=status_code, body=body)
+    if status_code in (400, 422):
+        return InvalidRequestError(message, status_code=status_code, body=body)
+    return APIError(message, status_code=status_code, body=body)
+
+
+def _extract_message(body: Any) -> Optional[str]:
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            return err.get("message")
+        if isinstance(err, str):
+            return err
+        if isinstance(body.get("message"), str):
+            return body["message"]
+    return None

agentletter-0.1.0/src/agentletter/types.py

@@ -0,0 +1,59 @@
+"""Data types for the Agent Letter SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class Address:
+    """A postal recipient or sender address."""
+
+    name: str
+    line1: str
+    city: str
+    state: str
+    zip: str
+    line2: Optional[str] = None
+    country: str = "US"
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = {
+            "name": self.name,
+            "line1": self.line1,
+            "city": self.city,
+            "state": self.state,
+            "zip": self.zip,
+            "country": self.country,
+        }
+        if self.line2:
+            data["line2"] = self.line2
+        return data
+
+
+@dataclass
+class Letter:
+    """A letter created through the API."""
+
+    id: str
+    status: str
+    to: Dict[str, Any] = field(default_factory=dict)
+    certified: bool = False
+    tracking_number: Optional[str] = None
+    expected_delivery: Optional[str] = None
+    created_at: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Letter":
+        return cls(
+            id=data.get("id", ""),
+            status=data.get("status", "unknown"),
+            to=data.get("to", {}) or {},
+            certified=bool(data.get("certified", False)),
+            tracking_number=data.get("tracking_number"),
+            expected_delivery=data.get("expected_delivery"),
+            created_at=data.get("created_at"),
+            raw=data,
+        )