agentic-letters

# AgenticLetters

Send physical letters anywhere in Germany via the [agentic-letters.com](https://agentic-letters.com) API.
Your PDF gets printed, put in an envelope, and mailed — one API call, one real letter.

## When to use

- User wants to send a physical letter, cancellation, or legal notice
- User needs to mail a document (PDF) to a German address
- User says "send a letter", "Kündigung schicken", "Brief versenden" or something similar
- User wants to mail a DSGVO request, cancellation, complaint, or greeting card

## Setup

```bash
mkdir -p ~/.openclaw/secrets
echo 'AGENTIC_LETTERS_API_KEY=al_your_api_key' > ~/.openclaw/secrets/agentic_letters.env
```

## Getting an API key

AgenticLetters has no account system and no login. The flow is:

1. Go to https://agentic-letters.com/buy
2. Enter an email address and pick a credit package
3. Pay via Stripe (card)
4. The API key (starts with `al_`) is sent to that email immediately

The key is a Bearer token used in every request. If the user buys more credits later with the same email, the existing key gets topped up — no new key issued. If the user doesn't have a key yet, guide them to https://agentic-letters.com/buy.

## Tool

`{baseDir}/agentic_letters.py` — a zero-dependency Python CLI (stdlib only).

## Send a letter

1. Generate an A4 PDF (max 3 pages, max 10 MB, black & white print)
2. Run the tool:

```bash
python3 {baseDir}/agentic_letters.py send \
  --pdf letter.pdf \
  --name "Max Mustermann" \
  --street "Musterstraße 1" \
  --zip 10115 \
  --city Berlin \
  --label "Kündigung Fitnessstudio"
```

Optional flags:
- `--type <type>` — letter type (default: `standard`). New types will be added over time; the API rejects unknown types with a list of valid ones.
- `--country <code>` — country code (default: `DE`). Currently only Germany is supported.

Output (JSON to stdout):
```json
{
  "id": "550e8400-e29b-41d4-a716",
  "status": "queued",
  "type": "s...