\r \r

AgenticLetters\r

\r Send physical letters anywhere in Germany via the agentic-letters.com API.\r Your PDF gets printed, put in an envelope, and mailed — one API call, one real letter.\r \r

When to use\r

\r

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

Setup\r

\r

mkdir -p ~/.openclaw/secrets\r
echo 'AGENTIC_LETTERS_API_KEY=al_your_api_key' > ~/.openclaw/secrets/agentic_letters.env\r
```\r
\r
## Getting an API key\r
\r
AgenticLetters has no account system and no login. The flow is:\r
\r
1. Go to https://agentic-letters.com/buy\r
2. Enter an email address and pick a credit package\r
3. Pay via Stripe (card)\r
4. The API key (starts with `al_`) is sent to that email immediately\r
\r
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.\r
\r
## Tool\r
\r
`{baseDir}/agentic_letters.py` — a zero-dependency Python CLI (stdlib only).\r
\r
## Send a letter\r
\r
1. Generate an A4 PDF (max 3 pages, max 10 MB, black & white print)\r
2. Run the tool:\r
\r
```bash\r
python3 {baseDir}/agentic_letters.py send \\r
  --pdf letter.pdf \\r
  --name "Max Mustermann" \\r
  --street "Musterstraße 1" \\r
  --zip 10115 \\r
  --city Berlin \\r
  --label "Kündigung Fitnessstudio"\r
```\r
\r
Optional flags:\r
- `--type \x3Ctype>` — letter type (default: `standard`). New types will be added over time; the API rejects unknown types with a list of valid ones.\r
- `--country \x3Ccode>` — country code (default: `DE`). Currently only Germany is supported.\r
\r
Output (JSON to stdout):\r
```json\r
{\r
  "id": "550e8400-e29b-41d4-a716",\r
  "status": "queued",\r
  "type": "standard",\r
  "label": "Kündigung Fitnessstudio",\r
  "created_at": "2026-02-24T19:00:00Z",\r
  "credits_remaining": 4\r
}\r
```\r
\r
## Check letter status\r
\r
```bash\r
python3 {baseDir}/agentic_letters.py status \x3Cletter-id>\r
```\r
\r
Status values: `queued` → `printed` → `sent` → `returned`\r
\r
## Check remaining credits\r
\r
```bash\r
python3 {baseDir}/agentic_letters.py credits\r
```\r
\r
## List all letters\r
\r
```bash\r
python3 {baseDir}/agentic_letters.py list\r
```\r
\r
## Local records\r
\r
Every sent letter is tracked locally in `{baseDir}/records/`. Each file is named `YYYY-MM-DD_\x3Cid-prefix>.json` and contains:\r
\r
```json\r
{\r
  "id": "550e8400-...",\r
  "status": "queued",\r
  "type": "standard",\r
  "label": "Kündigung Fitnessstudio",\r
  "recipient": { "name": "Max Mustermann", "street": "Musterstraße 1", "zip": "10115", "city": "Berlin", "country": "DE" },\r
  "created_at": "2026-02-24T19:00:00Z",\r
  "credits_remaining": 4,\r
  "last_checked": null\r
}\r
```\r
\r
Records are created automatically on `send` and updated on `status`. The date prefix lets agents quickly find recent letters without scanning old files. To check on pending letters, look at recent record files and call `status` for any that aren't `sent` yet.\r
\r
## Generating PDFs\r
\r
If the user doesn't have a PDF ready, generate one:\r
\r
- `pandoc` for markdown → PDF: `echo "Dear Sir..." | pandoc -o letter.pdf`\r
- `wkhtmltopdf` for HTML → PDF: `wkhtmltopdf letter.html letter.pdf`\r
- Python with `fpdf2` or `reportlab` for programmatic generation\r
\r
Always ensure A4 format (210 × 297 mm) with at least 15 mm margins.\r
\r
## Error handling\r
\r
Errors go to stderr with a clear origin tag. The exit code is non-zero on failure.\r
\r
**Origins:**\r
- `[local]` — problem before the request (missing file, no API key)\r
- `[server]` — the API rejected the request (includes error code, HTTP status, detail, and field)\r
- `[network]` — could not reach the API (DNS, timeout, connection refused)\r
\r
Example server error:\r
```\r
[server] Invalid German postal code\r
  code: recipient_zip_invalid\r
  http_status: 400\r
  detail: Expected a 5-digit German PLZ (e.g. "10115"), got "123".\r
  field: recipient.zip\r
```\r
\r
On success, JSON is printed to stdout. On failure, nothing goes to stdout.\r
\r
## Important constraints\r
\r
- **Germany only** — recipient must have a German address\r
- **Max 3 pages** — longer PDFs are rejected by the server\r
- **Max 10 MB** — compress images if needed\r
- **Black & white** — images are printed in grayscale\r
- **1 credit = 1 letter** — check credits before sending\r
- **A4 format** — ensure correct page size\r
- **Do not validate the PDF locally** — the server handles all PDF validation\r
\r
## Typical workflows\r
\r
**Kündigung (cancellation):**\r
Ask for: service name, customer number, recipient address. Generate a formal cancellation letter as PDF, send it.\r
\r
**DSGVO Auskunftsersuchen (data access request):**\r
Ask for: company name, address, user's full name. Generate a DSGVO Art. 15 request letter, send it.\r
\r
**Widerspruch (objection/appeal):**\r
Ask for: authority/company, reference number, reason. Generate a formal objection letter, send it.\r