agentletter 0.1.0

The physical-mail API for AI agents. Send a real, tracked, compliant letter with one call.

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.

Install

pip install agentletter

Quickstart

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:

export AGENTLETTER_API_KEY="sk_live_..."

Sending content

Provide exactly one of:

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:

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

letter = client.get("ltr_9f2a")
print(letter.status, letter.tracking_number, letter.expected_delivery)

Async

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:

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