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
