# Persolz API-Dokumentation
> REST-API v1.1.0 · Basis-URL `https://persolz.com/api/v1` · 127 Endpunkte · 17 Webhook-Ereignisse
> Online-Version mit Code-Beispielen in cURL, PHP, JavaScript und Python sowie API-Konsole: https://persolz.com/api-docs
> OpenAPI 3.1: https://persolz.com/api/v1/openapi.json
> Diese Datei wird aus `app/Lib/ApiSpec.php` und den Anleitungen der Online-Doku erzeugt (Stand 15.10.2026). Die aktuelle Fassung gibt es immer unter https://persolz.com/api-docs/markdown.
## Inhalt
- [Einführung](#einfuehrung)
- [Schnellstart in 5 Minuten](#schnellstart)
- [Authentifizierung](#authentifizierung)
- [Fehler](#fehler)
- [Rate-Limits](#rate-limits)
- [Paginierung](#paginierung)
- [Idempotenz](#idempotenz)
- [CORS & Browser](#cors)
- [Platzhalter](#platzhalter)
- [Webhooks](#webhooks)
- [Funnel-Integration (z. B. kartenherz.com)](#funnel)
- [Transaktionale E-Mails per API mit Platzhaltern](#transaktional)
- [Seinfeld-Mails per API planen](#seinfeld-planen)
- [Posteingang per API](#posteingang)
- [Fehlerbehandlung & Wiederholungen](#wiederholungen)
- [API-Referenz](#api-referenz)
- [System](#ref-system)
- [Konto & Tarif](#ref-account)
- [E-Mail-Listen](#ref-lists)
- [Kontakte](#ref-contacts)
- [Abmeldungen](#ref-unsubscribes)
- [E-Mails](#ref-emails)
- [Newsletter](#ref-newsletters)
- [Seinfeld-Mails](#ref-seinfeld)
- [Seifenopern](#ref-sequences)
- [Vorlagen](#ref-templates)
- [Anhänge](#ref-attachments)
- [SMTP-Server](#ref-smtp)
- [Kampagnen & Analytics](#ref-campaigns)
- [A/B-Tests](#ref-ab-tests)
- [Termine](#ref-appointments)
- [Posteingang](#ref-inbox)
- [KI](#ref-ai)
- [Webhooks](#ref-webhooks)
- [Protokolle](#ref-logs)
- [Öffentliche Anmeldung](#ref-public)
- [Integrationen](#ref-integrations)
- [Fehlercodes](#fehlercodes)
- [OpenAPI & Markdown](#downloads)
- [Changelog](#changelog)
Hallo {{vorname|Freund}},
dieser Newsletter kommt direkt aus meinem Code.
",
"list_ids": [3]
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'API-Test',
'subject' => 'Hallo {{vorname|Freund}}, das ist mein erster API-Newsletter',
'html' => 'Hallo {{vorname|Freund}},
dieser Newsletter kommt direkt aus meinem Code.
',
'list_ids' => [3],
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/newsletters', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'API-Test',
subject: 'Hallo {{vorname|Freund}}, das ist mein erster API-Newsletter',
html: 'Hallo {{vorname|Freund}},
dieser Newsletter kommt direkt aus meinem Code.
',
list_ids: [3]
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/newsletters",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
},
json={
"name": "API-Test",
"subject": "Hallo {{vorname|Freund}}, das ist mein erster API-Newsletter",
"html": "Hallo {{vorname|Freund}},
dieser Newsletter kommt direkt aus meinem Code.
",
"list_ids": [3],
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
### 5. Testmail an Dich senden
Prüfe den Newsletter, bevor er rausgeht: `POST /newsletters/{id}/test` schickt ihn mit „[TEST]“ im Betreff an bis zu fünf Adressen – ohne Tracking, personalisiert mit einem Beispielkontakt.
**Testmail**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/newsletters/812/test \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"to": "du@beispiel.de"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'to' => 'du@beispiel.de',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/newsletters/812/test', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
to: 'du@beispiel.de'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/newsletters/812/test",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"to": "du@beispiel.de",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
### 6. Newsletter senden
Alles gut? Dann löst `POST /newsletters/{id}/send` den Versand aus. Persolz prüft Betreff, Inhalt, Empfänger und SMTP-Konto, verschickt einen ersten Schwung sofort und den Rest automatisch im Hintergrund. Die Antwort kommt mit `202 Accepted`.
Lieber später? `POST /newsletters/{id}/schedule` mit `scheduled_at` plant den Versand. **Geschafft!** Als Nächstes lohnt sich ein Blick auf [Webhooks](#webhooks) und die [Funnel-Integration](#funnel).
**Jetzt senden**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/newsletters/812/send \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)"
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/newsletters/812/send', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Idempotency-Key': crypto.randomUUID()
}
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/newsletters/812/send",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**Antwort**
```json
{
"data": {
"id": 812,
"status": "sending",
"queued": 1250,
"sent": 150,
"failed": 0,
"message": "Versand gestartet: 150 von 1.250 E-Mails sind raus, der Rest folgt automatisch."
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
&sort=updated_asc` nur geänderte Kontakte.
**Alle Seiten laden**
*PHP*
```php
3, 'per_page' => 100, 'page' => $page]);
$ch = curl_init('https://persolz.com/api/v1/contacts?' . $query);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$json = json_decode((string) curl_exec($ch), true);
curl_close($ch);
foreach ($json['data'] as $contact) {
echo $contact['email'], PHP_EOL;
}
$pages = $json['meta']['pagination']['pages'];
$page++;
} while ($page <= $pages);
```
*JavaScript*
```javascript
// Alle Kontakte einer Liste seitenweise abrufen (Node.js 18+)
const headers = { 'Authorization': `Bearer ${process.env.PERSOLZ_API_KEY}` };
let page = 1;
let pages = 1;
do {
const params = new URLSearchParams({ list_id: '3', per_page: '100', page: String(page) });
const response = await fetch('https://persolz.com/api/v1/contacts?' + params, { headers });
const json = await response.json();
json.data.forEach((contact) => console.log(contact.email));
pages = json.meta.pagination.pages;
page++;
} while (page <= pages);
```
*Python*
```python
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['PERSOLZ_API_KEY']}"}
page, pages = 1, 1
while page <= pages:
result = requests.get(
"https://persolz.com/api/v1/contacts",
headers=headers,
params={"list_id": 3, "per_page": 100, "page": page},
timeout=30,
).json()
for contact in result["data"]:
print(contact["email"])
pages = result["meta"]["pagination"]["pages"]
page += 1
```
**Antwort (gekürzt)**
```json
{
"data": [
{
"id": 42,
"email": "anna@beispiel.de",
"…": "…"
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 100,
"total": 1250,
"pages": 13
},
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Danke für Deine Bestellung!
"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: bestellung-4711-bestaetigung',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => 'anna@beispiel.de',
'subject' => 'Deine Bestellung #4711',
'html' => 'Danke für Deine Bestellung!
',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/emails/send', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': 'bestellung-4711-bestaetigung'
},
body: JSON.stringify({
to: 'anna@beispiel.de',
subject: 'Deine Bestellung #4711',
html: 'Danke für Deine Bestellung!
'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/emails/send",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": "bestellung-4711-bestaetigung",
},
json={
"to": "anna@beispiel.de",
"subject": "Deine Bestellung #4711",
"html": "Danke für Deine Bestellung!
",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**Wiederholung**
```http
# Zweiter Aufruf mit demselben Idempotency-Key:
HTTP/1.1 202 Accepted
Idempotent-Replayed: true
Content-Type: application/json; charset=utf-8
{"data":{"campaign_id":813,"status":"sending", …}}
```
Hallo {{vorname|Freund}},
Dein Kartenset ist unterwegs nach {{ort}}.
Zum Kundenkonto
→ an Anna Schmidt (Berlin, custom_fields.kundennummer = K-1001), placeholders = {"bestellnummer": "4711"}
Betreff: Deine Bestellung #4711, Anna
HTML: Hallo Anna,
Dein Kartenset ist unterwegs nach Berlin.
Zum Kundenkonto
```
### Eigene Platzhalter per API
Bei `POST /emails/send` kannst Du zusätzlich ein Objekt **`placeholders`** mitsenden, z. B. `{"bestellnummer": "4711"}` – dann wird `{{bestellnummer}}` für **alle Empfänger dieser Anfrage** gleich ersetzt. Brauchst Du je Empfänger andere Werte (Bestellnummer, Liefertermin), sende **eine Anfrage pro Empfänger** – siehe [Transaktionale E-Mails](#transaktional).
Gut zu wissen:
- Namen: `a–z`, `0–9`, `_` und `-`, max. 50 eigene Platzhalter pro Anfrage. Eingebaute Namen (`vorname`, `email` …) werden immer je Empfänger befüllt und lassen sich nicht überschreiben.
- Werte werden im HTML automatisch maskiert – HTML-Code in Werten erscheint als Text. In Links werden Werte URL-kodiert.
- **Unbekannte Platzhalter bleiben stehen** (z. B. Tippfehler wie `{{vorame}}`). Schicke vor großen Versänden eine Testmail.
**E-Mail mit eigenem Platzhalter**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/emails/send \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"to": ["anna@beispiel.de"],
"subject": "Deine Bestellung #{{bestellnummer}}",
"html": "Hallo {{vorname|Freund}},
Deine Bestellung {{bestellnummer}} ist unterwegs.
",
"placeholders": {
"bestellnummer": "4711"
}
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'to' => ['anna@beispiel.de'],
'subject' => 'Deine Bestellung #{{bestellnummer}}',
'html' => 'Hallo {{vorname|Freund}},
Deine Bestellung {{bestellnummer}} ist unterwegs.
',
'placeholders' => [
'bestellnummer' => '4711',
],
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/emails/send', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
to: ['anna@beispiel.de'],
subject: 'Deine Bestellung #{{bestellnummer}}',
html: 'Hallo {{vorname|Freund}},
Deine Bestellung {{bestellnummer}} ist unterwegs.
',
placeholders: {
bestellnummer: '4711'
}
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/emails/send",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"to": ["anna@beispiel.de"],
"subject": "Deine Bestellung #{{bestellnummer}}",
"html": "Hallo {{vorname|Freund}},
Deine Bestellung {{bestellnummer}} ist unterwegs.
",
"placeholders": {
"bestellnummer": "4711",
},
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
,v1= |
**Webhook anlegen**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/webhooks \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"url": "https://kartenherz.com/hooks/persolz",
"events": ["contact.created", "contact.unsubscribed", "email.clicked"],
"description": "Shop-Synchronisation"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://kartenherz.com/hooks/persolz',
'events' => ['contact.created', 'contact.unsubscribed', 'email.clicked'],
'description' => 'Shop-Synchronisation',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/webhooks', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://kartenherz.com/hooks/persolz',
events: ['contact.created', 'contact.unsubscribed', 'email.clicked'],
description: 'Shop-Synchronisation'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/webhooks",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
},
json={
"url": "https://kartenherz.com/hooks/persolz",
"events": ["contact.created", "contact.unsubscribed", "email.clicked"],
"description": "Shop-Synchronisation",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**So kommt ein Ereignis bei Dir an**
```http
POST /hooks/persolz HTTP/1.1
Host: kartenherz.com
Content-Type: application/json; charset=utf-8
User-Agent: Persolz-Webhooks/1.0
X-Persolz-Event: contact.created
X-Persolz-Delivery: 9001
X-Persolz-Event-Id: evt_3f9a1c2b4d5e6f708192a3b4
X-Persolz-Signature: t=1791560735,v1=5f3a8c1e9b2d7f6a4c0e8b1d3f5a7c9e2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a
{"id":"evt_3f9a1c2b4d5e6f708192a3b4","event":"contact.created","created_at":"2026-10-09T14:05:00+02:00","data":{"contact":{"id":42,"email":"anna@beispiel.de", …}}}
```
` | Namen der geänderten Felder. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "contact.updated",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"contact": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
},
"changed": ["first_name", "lists"]
}
}
```
#### `contact.deleted` – Kontakt gelöscht
Ein Kontakt wurde gelöscht.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.contact` | `Kontakt-Objekt` | Der Kontakt. Siehe [Kontakt-Objekt](#obj-contact). |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "contact.deleted",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"contact": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
}
}
}
```
#### `contact.unsubscribed` – Kontakt abgemeldet
Ein Kontakt hat sich abgemeldet (Abmeldelink, Ein-Klick-Abmeldung, manuell oder per API).
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.contact` | `Kontakt-Objekt` | Der Kontakt. Siehe [Kontakt-Objekt](#obj-contact). |
| `data.email` | `string` | E-Mail-Adresse des Kontakts. |
| `data.source` | `string` | Quelle bzw. Auslöser (bei inbox.replied: user, ai oder rule). |
| `data.reason` | `string · null` | Grund (optional). |
| `data.campaign_id` | `integer` | ID der Kampagne. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "contact.unsubscribed",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"contact": {
"status": "unsubscribed",
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
},
"email": "anna@beispiel.de",
"source": "link",
"reason": null,
"campaign_id": 812
}
}
```
#### `list.joined` – Liste beigetreten
Ein aktiver Kontakt wurde in eine Liste aufgenommen.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.list` | `object` | Die Liste. |
| `data.list.id` | `integer` | ID der Liste. |
| `data.list.name` | `string` | Name der Liste. |
| `data.contact` | `Kontakt-Objekt` | Der Kontakt. Siehe [Kontakt-Objekt](#obj-contact). |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "list.joined",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"list": {
"id": 3,
"name": "Kartenherz Funnel"
},
"contact": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
}
}
}
```
#### `email.opened` – E-Mail geöffnet
Ein Empfänger hat eine E-Mail zum ersten Mal geöffnet (Bots werden herausgefiltert).
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.campaign` | `object` | Die Kampagne der E-Mail. |
| `data.campaign.id` | `integer` | ID der Kampagne. |
| `data.campaign.type` | `string` | Versandart: email, newsletter, seinfeld oder soap. |
| `data.campaign.name` | `string` | Interner Name der Kampagne. |
| `data.campaign.subject` | `string` | Betreff. |
| `data.campaign.ref_id` | `integer · null` | Bei Seinfeld-Mails die ID der Seinfeld-Mail, bei Seifenopern die ID des Tages, sonst null. |
| `data.contact_id` | `integer` | ID des Kontakts. |
| `data.email` | `string` | E-Mail-Adresse des Kontakts. |
| `data.variant` | `string · null` | A/B-Variante (A oder B) oder null. |
| `data.message_id` | `string` | ID der versendeten Nachricht. |
| `data.device` | `string` | Gerät: desktop, mobile oder tablet. |
| `data.implied` | `boolean` | true, wenn die Öffnung aus einem Klick abgeleitet wurde (Bilder waren blockiert). |
| `data.opened_at` | `string (Datum/Zeit)` | Zeitpunkt der ersten Öffnung. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "email.opened",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"campaign": {
"id": 812,
"type": "newsletter",
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"ref_id": null
},
"contact_id": 42,
"email": "anna@beispiel.de",
"variant": null,
"message_id": "6f1c0d9a2b7e4c1f8a3d5e6f7a8b9c0d",
"device": "mobile",
"implied": false,
"opened_at": "2026-10-09T14:05:00+02:00"
}
}
```
#### `email.clicked` – Link geklickt
Ein Empfänger hat einen Link zum ersten Mal geklickt (je Link, Bots werden herausgefiltert).
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.campaign` | `object` | Die Kampagne der E-Mail. |
| `data.campaign.id` | `integer` | ID der Kampagne. |
| `data.campaign.type` | `string` | Versandart: email, newsletter, seinfeld oder soap. |
| `data.campaign.name` | `string` | Interner Name der Kampagne. |
| `data.campaign.subject` | `string` | Betreff. |
| `data.campaign.ref_id` | `integer · null` | Bei Seinfeld-Mails die ID der Seinfeld-Mail, bei Seifenopern die ID des Tages, sonst null. |
| `data.contact_id` | `integer` | ID des Kontakts. |
| `data.email` | `string` | E-Mail-Adresse des Kontakts. |
| `data.variant` | `string` | A/B-Variante (A oder B) oder null. |
| `data.message_id` | `string` | ID der versendeten Nachricht. |
| `data.link` | `object` | Der geklickte Link. |
| `data.link.id` | `integer` | ID des Links. |
| `data.link.url` | `string` | Ziel-URL. |
| `data.link.label` | `string` | Linktext. |
| `data.device` | `string` | Gerät: desktop, mobile oder tablet. |
| `data.clicked_at` | `string (Datum/Zeit)` | Zeitpunkt des ersten Klicks auf diesen Link. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "email.clicked",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"campaign": {
"id": 812,
"type": "newsletter",
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"ref_id": null
},
"contact_id": 42,
"email": "anna@beispiel.de",
"variant": "B",
"message_id": "6f1c0d9a2b7e4c1f8a3d5e6f7a8b9c0d",
"link": {
"id": 77,
"url": "https://kartenherz.com/angebot",
"label": "Jetzt ansehen"
},
"device": "desktop",
"clicked_at": "2026-10-09T14:06:12+02:00"
}
}
```
#### `campaign.sent` – Kampagne versendet
Ein Newsletter, eine E-Mail oder eine Seinfeld-Mail wurde vollständig versendet.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.campaign_id` | `integer` | ID der Kampagne. |
| `data.type` | `string` | Versandart: email, newsletter oder seinfeld. |
| `data.name` | `string` | Interner Name der Kampagne. |
| `data.subject` | `string` | Betreff. |
| `data.status` | `string` | Status der Kampagne nach Abschluss (in der Regel sent). |
| `data.recipients` | `integer` | Empfänger gesamt. |
| `data.sent` | `integer` | Erfolgreich versendet. |
| `data.failed` | `integer` | Fehlgeschlagen. |
| `data.started_at` | `string (Datum/Zeit)` | Beginn des Versands oder null. |
| `data.finished_at` | `string (Datum/Zeit)` | Ende des Versands oder null. |
| `data.ref_id` | `integer · null` | Bei Seinfeld-Mails die ID der Seinfeld-Mail, bei Seifenopern die ID des Tages, sonst null. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "campaign.sent",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"campaign_id": 812,
"type": "newsletter",
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"status": "sent",
"recipients": 1250,
"sent": 1248,
"failed": 2,
"started_at": "2026-10-09T09:00:00+02:00",
"finished_at": "2026-10-09T09:04:31+02:00",
"ref_id": null
}
}
```
#### `soap.enrolled` – Seifenoper gestartet
Ein Kontakt wurde in eine Seifenoper aufgenommen.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.enrollment_id` | `integer` | ID der Teilnahme an der Seifenoper. |
| `data.sequence_id` | `integer` | ID der Seifenoper. |
| `data.sequence_name` | `string` | Name der Seifenoper. |
| `data.contact_id` | `integer` | ID des Kontakts. |
| `data.email` | `string` | E-Mail-Adresse des Kontakts. |
| `data.source` | `string` | Quelle bzw. Auslöser (bei inbox.replied: user, ai oder rule). |
| `data.start_date` | `string (Datum)` | Startdatum der Teilnahme. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "soap.enrolled",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"enrollment_id": 501,
"sequence_id": 7,
"sequence_name": "Willkommen bei Kartenherz",
"contact_id": 42,
"email": "anna@beispiel.de",
"source": "api",
"start_date": "2026-10-10"
}
}
```
#### `soap.completed` – Seifenoper abgeschlossen
Ein Kontakt hat alle Mails einer Seifenoper erhalten.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.enrollment_id` | `integer` | ID der Teilnahme an der Seifenoper. |
| `data.sequence_id` | `integer` | ID der Seifenoper. |
| `data.sequence_name` | `string` | Name der Seifenoper. |
| `data.contact_id` | `integer` | ID des Kontakts. |
| `data.email` | `string` | E-Mail-Adresse des Kontakts. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "soap.completed",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"enrollment_id": 501,
"sequence_id": 7,
"sequence_name": "Willkommen bei Kartenherz",
"contact_id": 42,
"email": "anna@beispiel.de"
}
}
```
#### `appointment.created` – Termin angelegt
Ein Termin wurde im Terminbuch angelegt.
`data` ist ein [Termin-Objekt](#obj-appointment).
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "appointment.created",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"id": 55,
"title": "Erstgespräch Anna Schmidt",
"description": "Kennenlernen per Video",
"location": "Zoom",
"start_at": "2026-10-14T10:00:00+02:00",
"end_at": "2026-10-14T10:30:00+02:00",
"all_day": false,
"contact_id": 42,
"contact": {
"id": 42,
"name": "Anna Schmidt",
"email": "anna@beispiel.de",
"phone": "+49 30 1234567"
},
"attendees": ["anna@beispiel.de"],
"phone": "",
"color": "violet",
"status": "planned",
"status_label": "Geplant",
"reminder_minutes": 60,
"remind_attendees": true,
"source": "api",
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00"
}
}
```
#### `appointment.updated` – Termin geändert
Ein Termin wurde geändert, verschoben oder abgesagt.
`data` ist ein [Termin-Objekt](#obj-appointment), zusätzlich:
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.changed` | `array` | Namen der geänderten Felder. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "appointment.updated",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"id": 55,
"title": "Erstgespräch Anna Schmidt",
"description": "Kennenlernen per Video",
"location": "Zoom",
"start_at": "2026-10-14T10:00:00+02:00",
"end_at": "2026-10-14T10:30:00+02:00",
"all_day": false,
"contact_id": 42,
"contact": {
"id": 42,
"name": "Anna Schmidt",
"email": "anna@beispiel.de",
"phone": "+49 30 1234567"
},
"attendees": ["anna@beispiel.de"],
"phone": "",
"color": "violet",
"status": "planned",
"status_label": "Geplant",
"reminder_minutes": 60,
"remind_attendees": true,
"source": "api",
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"changed": ["start_at", "end_at"]
}
}
```
#### `inbox.received` – Neue Mail im Posteingang
In einem verbundenen Postfach ist eine neue Mail eingegangen (ohne Newsletter, Abwesenheitsnotizen, Unzustellbarkeitsmeldungen und Spam-Verdacht).
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.message` | `Mail-Objekt (Posteingang)` | Testnachricht (test.ping) bzw. die Mail im Posteingang (inbox.*). Siehe [Mail-Objekt (Posteingang)](#obj-inbox-message). |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "inbox.received",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"message": {
"id": 9120,
"mailbox_id": 2,
"mailbox_email": "hallo@kartenherz.com",
"folder": "Posteingang",
"folder_role": "inbox",
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"message_id": "",
"direction": "in",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"to": [
{
"email": "hallo@kartenherz.com",
"name": "Kartenherz"
}
],
"cc": [],
"subject": "Frage zu Hochzeitskarten",
"snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …",
"received_at": "2026-10-09T14:05:00+02:00",
"is_seen": false,
"is_flagged": false,
"is_answered": false,
"has_attachments": false,
"has_calendar": false,
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"sentiment": "positive",
"intent": "Angebot für 80 Hochzeitskarten",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"needs_reply": true,
"contact_id": 42,
"campaign_id": null,
"labels": ["Hochzeit"],
"snoozed_until": null,
"follow_up_at": null,
"replied_at": null
}
}
}
```
#### `inbox.replied` – Mail aus dem Posteingang gesendet
Eine Antwort, Weiterleitung oder neue Mail wurde aus dem Posteingang verschickt – von Dir, nach Deiner Freigabe oder vom KI-Autopiloten.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.draft` | `integer` | Der KI-Entwurf (inbox.approval_needed, inbox.auto_replied) – bei inbox.replied nur seine ID (= draft_id). |
| `data.draft_id` | `integer` | ID der gesendeten Mail (GET /inbox/drafts/{id}). |
| `data.mailbox_id` | `integer` | ID des Postfachs. |
| `data.kind` | `string` | reply, reply_all, forward, new oder auto. |
| `data.source` | `string` | Quelle bzw. Auslöser (bei inbox.replied: user, ai oder rule). |
| `data.auto` | `boolean` | true, wenn der KI-Autopilot die Antwort gesendet hat. |
| `data.to` | `array` | Empfänger (To und Cc, E-Mail-Adressen). |
| `data.subject` | `string` | Betreff. |
| `data.message_id` | `string` | ID der versendeten Nachricht. |
| `data.sent_at` | `string (Datum/Zeit)` | Zeitpunkt des Versands oder null. |
| `data.in_reply_to_message` | `integer` | ID der beantworteten Mail (GET /inbox/messages/{id}) oder null. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "inbox.replied",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"draft": 5501,
"draft_id": 5501,
"mailbox_id": 2,
"kind": "reply",
"source": "ai",
"auto": false,
"to": ["anna@beispiel.de"],
"subject": "Re: Frage zu Hochzeitskarten",
"message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>",
"sent_at": "2026-10-09T14:21:04+02:00",
"in_reply_to_message": 9120
}
}
```
#### `inbox.approval_needed` – KI-Entwurf wartet auf Freigabe
Die KI hat eine Antwort entworfen, die Du freigeben musst (Modus „Mit Freigabe“ oder der Autopilot hat eine Sicherheitsprüfung nicht bestanden).
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.draft` | `object` | Der KI-Entwurf (inbox.approval_needed, inbox.auto_replied) – bei inbox.replied nur seine ID (= draft_id). |
| `data.draft.id` | `integer` | Eindeutige ID. |
| `data.draft.mailbox_id` | `integer` | ID des Postfachs. |
| `data.draft.subject` | `string` | Betreff der Antwort. |
| `data.draft.to` | `array` | Empfänger (Liste aus {email, name}). |
| `data.draft.to[].email` | `string` | E-Mail-Adresse. |
| `data.draft.to[].name` | `string` | Name (kann leer sein). |
| `data.draft.ai_confidence` | `integer` | Selbsteinschätzung der KI (0–100) oder null. |
| `data.draft.ai_reason` | `string` | Begründung der KI bzw. warum der Autopilot nicht selbst gesendet hat. |
| `data.draft.ai_flags` | `array` | Risiken: legal, money, medical, threat, prompt_injection, personal_data, unclear. |
| `data.draft.send_at` | `string · null` | Geplanter Versand (Autopilot: nach der Wartezeit) oder null. |
| `data.message` | `Mail-Objekt (Posteingang)` | Testnachricht (test.ping) bzw. die Mail im Posteingang (inbox.*). Siehe [Mail-Objekt (Posteingang)](#obj-inbox-message). |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "inbox.approval_needed",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"draft": {
"id": 5502,
"mailbox_id": 2,
"subject": "Re: Rechnung doppelt abgebucht?",
"to": [
{
"email": "ben@beispiel.de",
"name": "Ben Krüger"
}
],
"ai_confidence": 64,
"ai_reason": "Nicht automatisch gesendet:\n- Kategorie „Beschwerde“ beantwortest Du immer selbst.\n- KI-Risiko: Geld/Erstattung.\nKI-Einschätzung: Ben bittet um Erstattung einer doppelten Abbuchung.",
"ai_flags": ["money"],
"send_at": null
},
"message": {
"id": 9133,
"mailbox_id": 2,
"mailbox_email": "hallo@kartenherz.com",
"folder": "Posteingang",
"folder_role": "inbox",
"thread_key": "8d2e4b6f0a1c3e5d7f9b1a2c4e6d8f0a1b3c5d7e",
"message_id": "",
"direction": "in",
"from": {
"email": "ben@beispiel.de",
"name": "Ben Krüger"
},
"to": [
{
"email": "hallo@kartenherz.com",
"name": "Kartenherz"
}
],
"cc": [],
"subject": "Rechnung doppelt abgebucht?",
"snippet": "Hallo, mir wurde die Rechnung 2026-1042 zweimal abgebucht. Bitte erstattet mir den Betrag …",
"received_at": "2026-10-09T14:05:00+02:00",
"is_seen": false,
"is_flagged": false,
"is_answered": false,
"has_attachments": false,
"has_calendar": false,
"category": "complaint",
"category_label": "Beschwerde",
"priority": "high",
"sentiment": "negative",
"intent": "Erstattung einer doppelten Abbuchung",
"summary": "Ben wurde die Rechnung doppelt abgebucht und bittet um Erstattung.",
"needs_reply": true,
"contact_id": 57,
"campaign_id": null,
"labels": [],
"snoozed_until": null,
"follow_up_at": null,
"replied_at": null
}
}
}
```
#### `inbox.auto_replied` – Autopilot-Antwort geplant
Der KI-Autopilot hat eine Antwort automatisch eingeplant. Sie geht nach der eingestellten Verzögerung raus und kann bis dahin gestoppt werden.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.draft` | `object` | Der KI-Entwurf (inbox.approval_needed, inbox.auto_replied) – bei inbox.replied nur seine ID (= draft_id). |
| `data.draft.id` | `integer` | Eindeutige ID. |
| `data.draft.mailbox_id` | `integer` | ID des Postfachs. |
| `data.draft.subject` | `string` | Betreff der Antwort. |
| `data.draft.to` | `array` | Empfänger (Liste aus {email, name}). |
| `data.draft.to[].email` | `string` | E-Mail-Adresse. |
| `data.draft.to[].name` | `string` | Name (kann leer sein). |
| `data.draft.ai_confidence` | `integer` | Selbsteinschätzung der KI (0–100) oder null. |
| `data.draft.ai_reason` | `string` | Begründung der KI bzw. warum der Autopilot nicht selbst gesendet hat. |
| `data.draft.ai_flags` | `array` | Risiken: legal, money, medical, threat, prompt_injection, personal_data, unclear. |
| `data.draft.send_at` | `string (Datum/Zeit)` | Geplanter Versand (Autopilot: nach der Wartezeit) oder null. |
| `data.message` | `Mail-Objekt (Posteingang)` | Testnachricht (test.ping) bzw. die Mail im Posteingang (inbox.*). Siehe [Mail-Objekt (Posteingang)](#obj-inbox-message). |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "inbox.auto_replied",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"draft": {
"id": 5503,
"mailbox_id": 2,
"subject": "Re: Frage zu Hochzeitskarten",
"to": [
{
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
}
],
"ai_confidence": 91,
"ai_reason": "Alle Sicherheitsprüfungen bestanden – wird automatisch beantwortet.\nKI-Einschätzung: Preis und Lieferzeit stehen im Wissen für die KI.",
"ai_flags": [],
"send_at": "2026-10-09T14:20:00+02:00"
},
"message": {
"id": 9120,
"mailbox_id": 2,
"mailbox_email": "hallo@kartenherz.com",
"folder": "Posteingang",
"folder_role": "inbox",
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"message_id": "",
"direction": "in",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"to": [
{
"email": "hallo@kartenherz.com",
"name": "Kartenherz"
}
],
"cc": [],
"subject": "Frage zu Hochzeitskarten",
"snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …",
"received_at": "2026-10-09T14:05:00+02:00",
"is_seen": false,
"is_flagged": false,
"is_answered": false,
"has_attachments": false,
"has_calendar": false,
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"sentiment": "positive",
"intent": "Angebot für 80 Hochzeitskarten",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"needs_reply": true,
"contact_id": 42,
"campaign_id": null,
"labels": ["Hochzeit"],
"snoozed_until": null,
"follow_up_at": null,
"replied_at": null
}
}
}
```
#### `test.ping` – Test-Ping
Test-Ereignis, das Du auf der Entwickler-Seite oder per API auslöst.
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.message` | `string` | Testnachricht (test.ping) bzw. die Mail im Posteingang (inbox.*). |
| `data.webhook_id` | `integer` | ID des getesteten Webhooks. |
| `data.account` | `object` | Konto, zu dem der Webhook gehört. |
| `data.account.id` | `integer` | ID des Kontos. |
| `data.account.email` | `string` | E-Mail-Adresse des Kontos. |
```json
{
"id": "evt_3f9a1c2b4d5e6f708192a3b4",
"event": "test.ping",
"created_at": "2026-10-09T14:05:00+02:00",
"data": {
"message": "Hallo von Persolz! Dieser Test zeigt, dass Dein Endpunkt Webhooks empfängt.",
"webhook_id": 4,
"account": {
"id": 2,
"email": "du@beispiel.de"
}
}
}
```
."`, als Hex-String.
4. **Zeitkonstant vergleichen** (`hash_equals`, `timingSafeEqual`, `compare_digest`) und Zeitstempel ablehnen, die älter als **5 Minuten** sind (Schutz vor Wiederholungsangriffen).
5. **Schnell antworten** (`200`) und aufwendige Arbeit danach erledigen. Entdopple über `X-Persolz-Event-Id` – bei Wiederholungen bleibt sie gleich.
Zum Testen schickt der Button **„Test senden“** auf der Entwickler-Seite (oder `POST /webhooks/{id}/test`) ein Ereignis `test.ping`. Nach einem Secret-Wechsel (`rotate_secret`) ist das alte Secret sofort ungültig.
**Signatur prüfen**
*PHP*
```php
300) {
http_response_code(400);
exit('Ungültige Signatur');
}
// 5. Schnell bestätigen, dann verarbeiten
$event = json_decode($body, true);
http_response_code(200);
echo 'ok';
// Doppelte Zustellungen erkennen (gleiche Event-ID bei Wiederholungen)
$eventId = $_SERVER['HTTP_X_PERSOLZ_EVENT_ID'] ?? $event['id'];
// if (bereitsVerarbeitet($eventId)) return;
switch ($event['event']) {
case 'contact.created':
// $event['data']['contact']['email'] …
break;
case 'contact.unsubscribed':
// Kunde im Shop als „keine Werbung“ markieren
break;
}
```
*Node.js*
```javascript
// webhook.js – Node.js 18+ ohne weitere Pakete
const http = require('node:http');
const crypto = require('node:crypto');
const SECRET = process.env.PERSOLZ_WEBHOOK_SECRET; // whsec_…
function verify(rawBody, header) {
const parts = Object.fromEntries(
header.split(',').map((p) => p.trim().split('=', 2))
);
const t = Number(parts.t);
if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto.createHmac('sha256', SECRET)
.update(`${t}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
http.createServer((req, res) => {
let raw = '';
req.setEncoding('utf8');
req.on('data', (chunk) => { raw += chunk; });
req.on('end', () => {
// Wichtig: den ROHEN Body prüfen – nicht JSON.stringify(JSON.parse(raw))
if (!verify(raw, req.headers['x-persolz-signature'] || '')) {
res.writeHead(400).end('Ungültige Signatur');
return;
}
res.writeHead(200).end('ok'); // sofort bestätigen (max. 4 Sekunden)
const event = JSON.parse(raw);
console.log(event.event, req.headers['x-persolz-event-id'], event.data);
});
}).listen(3000);
```
*Python*
```python
# webhook.py – mit Flask (pip install flask)
import hashlib, hmac, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["PERSOLZ_WEBHOOK_SECRET"].encode()
@app.post("/hooks/persolz")
def persolz_webhook():
raw = request.get_data() # roher Body (bytes)
parts = dict(p.strip().split("=", 1) for p in
request.headers.get("X-Persolz-Signature", "").split(",") if "=" in p)
t = int(parts.get("t", 0))
expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts.get("v1", "")) or abs(time.time() - t) > 300:
abort(400)
event = request.get_json()
print(event["event"], request.headers.get("X-Persolz-Event-Id"))
return "ok", 200
```
**Test-Ping auslösen**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/webhooks/4/test \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL"
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/webhooks/4/test', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL'
}
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/webhooks/4/test",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
' + json.data.message + '
';
} else {
alert(json.error.message); // z. B. „Bitte prüfe Deine E-Mail-Adresse …“
}
});
```
Hallo {{vorname|Du}},
Deine Bestellung #{{bestellnummer}} über {{betrag}} ist eingegangen.
Lieferung voraussichtlich am {{lieferdatum}}.
",
"placeholders": {
"bestellnummer": "4711",
"betrag": "24,90 €",
"lieferdatum": "14.10.2026"
},
"from_name": "Kartenherz",
"reply_to": "hallo@kartenherz.com",
"track_opens": false
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: shop-bestellung-4711',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => 'anna@beispiel.de',
'subject' => 'Danke für Deine Bestellung #{{bestellnummer}}, {{vorname|Du}}!',
'html' => 'Hallo {{vorname|Du}},
Deine Bestellung #{{bestellnummer}} über {{betrag}} ist eingegangen.
Lieferung voraussichtlich am {{lieferdatum}}.
',
'placeholders' => [
'bestellnummer' => '4711',
'betrag' => '24,90 €',
'lieferdatum' => '14.10.2026',
],
'from_name' => 'Kartenherz',
'reply_to' => 'hallo@kartenherz.com',
'track_opens' => false,
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/emails/send', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': 'shop-bestellung-4711'
},
body: JSON.stringify({
to: 'anna@beispiel.de',
subject: 'Danke für Deine Bestellung #{{bestellnummer}}, {{vorname|Du}}!',
html: 'Hallo {{vorname|Du}},
Deine Bestellung #{{bestellnummer}} über {{betrag}} ist eingegangen.
Lieferung voraussichtlich am {{lieferdatum}}.
',
placeholders: {
bestellnummer: '4711',
betrag: '24,90 €',
lieferdatum: '14.10.2026'
},
from_name: 'Kartenherz',
reply_to: 'hallo@kartenherz.com',
track_opens: false
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/emails/send",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": "shop-bestellung-4711",
},
json={
"to": "anna@beispiel.de",
"subject": "Danke für Deine Bestellung #{{bestellnummer}}, {{vorname|Du}}!",
"html": "Hallo {{vorname|Du}},
Deine Bestellung #{{bestellnummer}} über {{betrag}} ist eingegangen.
Lieferung voraussichtlich am {{lieferdatum}}.
",
"placeholders": {
"bestellnummer": "4711",
"betrag": "24,90 €",
"lieferdatum": "14.10.2026",
},
"from_name": "Kartenherz",
"reply_to": "hallo@kartenherz.com",
"track_opens": False,
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**Antwort (202)**
```json
{
"data": {
"campaign_id": 813,
"status": "sending",
"scheduled_at": null,
"recipients": 1,
"queued": 1,
"sent": 1,
"failed": 0,
"message": "Versand abgeschlossen: 1 E-Mail verschickt."
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
### Mit Vorlage und Anhang
Statt eigenem HTML kannst Du eine Vorlage verwenden: `template_key` für die Bibliothek (Übersicht: `GET /templates?category=email`) oder `template_id` für eigene Vorlagen. Betreff und Vorschautext kommen aus der Vorlage, wenn Du keine angibst.
Anhänge lädst Du einmal hoch (`POST /attachments`, max. 10 MB) und gibst danach nur noch die ID in `attachment_ids` mit – z. B. Rechnung, AGB oder ein Gutschein als PDF.
Bilder (JPG, PNG, GIF, WebP) aus der Anhang-Cloud baust Du direkt ins HTML ein: `POST /attachments` und `GET /attachments/{id}` liefern dafür `image_url` (die Liste `GET /attachments` zeigt nur bereits vorhandene Links) – eine öffentliche, nicht erratbare Adresse für `Heute Morgen ist mir mein Kaffeebecher …
",
"topic_id": 15,
"story_title": "Der Kaffeebecher"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'subject' => 'Was mein Kaffeebecher über Marketing weiß',
'html' => 'Heute Morgen ist mir mein Kaffeebecher …
',
'topic_id' => 15,
'story_title' => 'Der Kaffeebecher',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/seinfeld/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json'
},
body: JSON.stringify({
subject: 'Was mein Kaffeebecher über Marketing weiß',
html: 'Heute Morgen ist mir mein Kaffeebecher …
',
topic_id: 15,
story_title: 'Der Kaffeebecher'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/seinfeld/emails",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
},
json={
"subject": "Was mein Kaffeebecher über Marketing weiß",
"html": "Heute Morgen ist mir mein Kaffeebecher …
",
"topic_id": 15,
"story_title": "Der Kaffeebecher",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**Mit KI generieren**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/seinfeld/generate \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"source": "next_topic",
"model": "sonnet",
"persist": true
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'source' => 'next_topic',
'model' => 'sonnet',
'persist' => true,
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/seinfeld/generate', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
source: 'next_topic',
model: 'sonnet',
persist: true
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/seinfeld/generate",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"source": "next_topic",
"model": "sonnet",
"persist": True,
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
### 5. Freigeben und planen
`POST /seinfeld/emails/{id}/schedule` gibt die Mail frei und plant sie – zum angegebenen `scheduled_at` oder, ohne Angabe, zum **nächsten freien Termin** im Rhythmus. Persolz versendet pünktlich; danach meldet der Webhook `campaign.sent` (Typ `seinfeld`, `ref_id` = ID der Seinfeld-Mail).
Geplant, aber doch nicht? `POST /seinfeld/emails/{id}/unschedule` macht sie wieder zum Entwurf. Alle geplanten Mails liefert `GET /seinfeld/emails?status=planned`.
**Mail planen**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/seinfeld/emails/120/schedule \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"scheduled_at": "2026-10-12T09:00:00+02:00"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'scheduled_at' => '2026-10-12T09:00:00+02:00',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/seinfeld/emails/120/schedule', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
scheduled_at: '2026-10-12T09:00:00+02:00'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/seinfeld/emails/120/schedule",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"scheduled_at": "2026-10-12T09:00:00+02:00",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**Antwort (gekürzt)**
```json
{
"data": {
"id": 120,
"subject": "Was mein Kaffeebecher über Marketing weiß",
"status": "scheduled",
"status_label": "Geplant",
"scheduled_at": "2026-10-12T09:00:00+02:00",
"campaign_id": 901
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Hallo Anna,
herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € und sind in 10 Tagen bei Dir.
"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: crm-antwort-9120',
],
CURLOPT_POSTFIELDS => json_encode([
'html' => 'Hallo Anna,
herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € und sind in 10 Tagen bei Dir.
',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/inbox/messages/9120/reply', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': 'crm-antwort-9120'
},
body: JSON.stringify({
html: 'Hallo Anna,
herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € und sind in 10 Tagen bei Dir.
'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
response = requests.post(
"https://persolz.com/api/v1/inbox/messages/9120/reply",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": "crm-antwort-9120",
},
json={
"html": "Hallo Anna,
herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € und sind in 10 Tagen bei Dir.
",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
### 4. KI-Entwürfe freigeben
`POST /inbox/messages/{id}/ai-draft` lässt die KI eine Antwort im Stil Deines Postfachs schreiben – mit Selbsteinschätzung (`confidence`), Risiken und Begründung (Scope `ai`, verbraucht KI-Guthaben). Mit `save: "approval"` landet sie in den Freigaben.
Im Modus „Mit Freigabe“ oder wenn der Autopilot eine Sicherheitsprüfung nicht besteht, meldet der Webhook **`inbox.approval_needed`** den Entwurf. `GET /inbox/approvals` zeigt alle wartenden Entwürfe mit den Gründen; `POST /inbox/approvals/{id}/approve` sendet (optional mit Änderungen), `…/reject` lehnt ab – beides fließt als Erkenntnis in künftige Entwürfe ein.
**Entwurf in die Freigaben**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/inbox/messages/9120/ai-draft \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"tone": "herzlich",
"save": "approval"
}'
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'tone' => 'herzlich',
'save' => 'approval',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/inbox/messages/9120/ai-draft', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
tone: 'herzlich',
save: 'approval'
})
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/inbox/messages/9120/ai-draft",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"tone": "herzlich",
"save": "approval",
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
**Freigeben und senden**
*cURL*
```bash
curl -X POST https://persolz.com/api/v1/inbox/approvals/5502/approve \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)"
```
*PHP*
```php
'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$body = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status >= 400) {
exit('Fehler ' . $status . ': ' . ($json['error']['message'] ?? $body));
}
print_r($json['data']);
```
*JavaScript*
```javascript
const response = await fetch('https://persolz.com/api/v1/inbox/approvals/5502/approve', {
method: 'POST',
headers: {
'Authorization': 'Bearer pz_live_DEIN_API_SCHLUESSEL',
'Idempotency-Key': crypto.randomUUID()
}
});
const json = await response.json();
if (!response.ok) {
throw new Error(`Fehler ${response.status}: ${json.error.message}`);
}
console.log(json.data);
```
*Python*
```python
import requests
import uuid
response = requests.post(
"https://persolz.com/api/v1/inbox/approvals/5502/approve",
headers={
"Authorization": "Bearer pz_live_DEIN_API_SCHLUESSEL",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=30,
)
result = response.json()
if not response.ok:
raise SystemExit(f"Fehler {response.status_code}: {result['error']['message']}")
print(result["data"])
```
### 5. Webhooks des Posteingangs
| Ereignis | Wann | Typische Verwendung |
|---|---|---|
| `inbox.received` | neue Mail im Posteingang | Lead ins CRM, Ticket anlegen |
| `inbox.approval_needed` | KI-Entwurf wartet auf Freigabe | Hinweis in Slack/Teams |
| `inbox.auto_replied` | Autopilot hat eine Antwort eingeplant | Protokoll, Stichproben |
| `inbox.replied` | Antwort/Mail aus dem Posteingang gesendet | Status im CRM setzen |
Die Payloads enthalten das [Mail-Objekt](#obj-inbox-message) – nie den Inhalt der Mail. Den holst Du bei Bedarf mit `GET /inbox/messages/{id}?include_body=true`.
` | Berechtigungen (["*"] = alle). |
| `data.api_key.rate_limit` | `integer` | Erlaubte Anfragen pro Minute. |
```json
{
"data": {
"account": {
"id": 2,
"email": "du@beispiel.de",
"first_name": "Daniel",
"last_name": "Scholz",
"company": "Kartenherz",
"timezone": "Europe/Berlin",
"email_verified": true,
"created_at": "2026-09-01T10:00:00+02:00"
},
"plan": {
"key": "pro",
"label": "Pro",
"trial_days_left": 0,
"trial_ends_at": null,
"subscription_status": "active"
},
"features": {
"ai": true,
"api": true,
"seinfeld": true,
"soap": true,
"newsletter": true,
"email": true,
"ab_tests": true,
"calendar": true
},
"limits": {
"max_lists": -1,
"max_contacts": -1,
"emails_per_day": -1,
"storage_mb": 2000
},
"usage": {
"contacts": 1250,
"lists": 3,
"soap_sequences": 2,
"smtp_accounts": 1,
"custom_templates": 4,
"storage_bytes": 5242880,
"active_ab_tests": 1,
"today": {
"email": 3,
"newsletter": 1,
"seinfeld": 1
}
},
"ai": {
"credit": 10.0,
"used": 2.31,
"remaining": 7.69,
"requests": 12,
"limit": 0,
"period": "2026-10",
"allowed": true
},
"api_key": {
"id": 5,
"name": "Funnel kartenherz.com",
"prefix": "pz_live_AbCdEf",
"scopes": ["*"],
"rate_limit": 120
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 429 `rate_limited`.
` | Erlaubte Weiterleitungs-Domains für success_url/error_url des Anmeldeformulars (leer = alle). |
| `public_token` | `string` | Öffentlicher Token für Anmeldeformulare (POST /subscribe/{token}). |
| `subscribe_url` | `string` | Öffentliche Anmelde-URL – ohne API-Schlüssel nutzbar. |
| `form_url` | `string` | Fertiges HTML-Anmeldeformular zum Verlinken oder Einbetten (iframe). |
| `counts` | `object` | Mitglieder nach Status. |
| `counts.subscribed` | `integer` | Aktive Mitglieder. |
| `counts.pending` | `integer` | Noch unbestätigte Anmeldungen (Double-Opt-in). |
| `counts.unsubscribed` | `integer` | Abgemeldete Mitglieder. |
| `counts.bounced` | `integer` | Unzustellbare Adressen. |
| `counts.total` | `integer` | Alle Mitglieder. |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"id": 3,
"name": "Kartenherz Funnel",
"description": "Leads aus dem Funnel auf kartenherz.com",
"color": "#5B3DF5",
"double_optin": true,
"welcome_soap_id": 7,
"doi_redirect_url": "https://kartenherz.com/danke",
"redirect_domains": ["kartenherz.com"],
"public_token": "9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c",
"subscribe_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c",
"form_url": "https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c/form",
"counts": {
"subscribed": 1180,
"pending": 24,
"unsubscribed": 41,
"bounced": 5,
"total": 1250
},
"created_at": "2026-09-01T10:00:00+02:00",
"updated_at": "2026-10-01T08:30:00+02:00"
}
```
` | nein | IDs bestehender Kontakte. |
| `contacts` | `array` | nein | Kontakte als Objekte (email Pflicht, weitere Felder wie bei POST /contacts). |
```bash
curl -X POST https://persolz.com/api/v1/lists/42/contacts \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"contact_ids": [42, 43],
"contacts": [
{
"email": "ben@beispiel.de",
"first_name": "Ben",
"tags": ["messe"]
}
]
}'
```
**Antwort 200** – OK
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.added` | `integer` | Neu in die Liste aufgenommene Kontakte. |
| `data.created` | `integer` | Neu angelegte Kontakte. |
| `data.updated` | `integer` | Aktualisierte bestehende Kontakte. |
| `data.skipped` | `integer` | Übersprungene Einträge (z. B. bereits Mitglied). |
| `data.failed` | `integer` | Fehlgeschlagene Einträge (Details in errors). |
| `data.errors` | `array` | Fehler je Eintrag (leer, wenn alles geklappt hat). |
| `data.list` | `object` | Die Liste mit den neuen Mitgliederzahlen. |
| `data.list.id` | `integer` | ID der Liste. |
| `data.list.counts` | `object` | Mitglieder nach Status. |
| `data.list.counts.subscribed` | `integer` | Aktive Mitglieder. |
| `data.list.counts.pending` | `integer` | Noch unbestätigte Anmeldungen (Double-Opt-in). |
| `data.list.counts.unsubscribed` | `integer` | Abgemeldete Mitglieder. |
| `data.list.counts.bounced` | `integer` | Unzustellbare Adressen. |
| `data.list.counts.total` | `integer` | Alle Mitglieder. |
```json
{
"data": {
"added": 2,
"created": 1,
"updated": 0,
"skipped": 0,
"failed": 0,
"errors": [],
"list": {
"id": 3,
"counts": {
"subscribed": 1182,
"pending": 25,
"unsubscribed": 41,
"bounced": 5,
"total": 1253
}
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | Tags des Kontakts. |
| `status` | `string` | subscribed (aktiv), pending (unbestätigt), unsubscribed (abgemeldet) oder bounced (unzustellbar). |
| `source` | `string` | Herkunft: manual, import, form, api, digistore, copecart … |
| `custom_fields` | `object` | Eigene Felder als Objekt – jeder Schlüssel ist auch als Platzhalter nutzbar ({{kundennummer}}). |
| `custom_fields.kundennummer` | `string` | Wert eines eigenen Feldes (hier ein Beispiel). |
| `doi_confirmed_at` | `string · null` | Zeitpunkt der Double-Opt-in-Bestätigung oder null. |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
| `lists` | `array` | Listen, in denen der Kontakt ist. |
| `lists[].id` | `integer` | ID der Liste. |
| `lists[].name` | `string` | Name der Liste. |
| `lists[].color` | `string` | Farbe der Liste. |
```json
{
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
}
```
` | nein | Tags (Array oder kommagetrennt). Beim Upsert werden Tags ergänzt. |
| `custom_fields` | `object` | nein | Eigene Felder (max. 50 Schlüssel a–z, 0–9, _ und -) – auch als Platzhalter {{schluessel}} nutzbar. |
| `status` | `string` | nein | subscribed \| pending \| unsubscribed. Abgemeldete Adressen werden nur mit consent=true reaktiviert. Werte: `subscribed`, `pending`, `unsubscribed`. |
| `list_ids` | `array` | nein | Listen, in die der Kontakt aufgenommen wird (Double-Opt-in der Liste wird beachtet). Aliase: lists (IDs oder Listen-Objekte wie in der Antwort), list_id. |
| `consent` | `boolean` | nein | Bestätigt eine neue Einwilligung (nötig, um abgemeldete Kontakte wieder anzumelden). |
| `doi` | `boolean` | nein | Erzwingt eine Bestätigungsmail (Double-Opt-in), auch wenn die Liste es nicht verlangt. |
| `soap_sequence_id` | `integer` | nein | Seifenoper, in die der Kontakt aufgenommen wird. |
| `soap_start_date` | `string` | nein | Startdatum der Seifenoper (YYYY-MM-DD, Standard heute). |
```bash
curl -X POST https://persolz.com/api/v1/contacts \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"tags": ["funnel"],
"list_ids": [3],
"custom_fields": {
"kundennummer": "K-1001"
},
"soap_sequence_id": 7
}'
```
**Antwort 201** – Angelegt (200 bei Aktualisierung) · [Kontakt-Objekt](#obj-contact)
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.result` | `object` | Was beim Upsert passiert ist. |
| `data.result.created` | `boolean` | Der Kontakt wurde neu angelegt. |
| `data.result.updated` | `boolean` | Ein bestehender Kontakt wurde aktualisiert. |
| `data.result.status` | `string` | Status des Kontakts nach dem Upsert. |
| `data.result.doi_sent` | `boolean` | Eine Bestätigungsmail (Double-Opt-in) wurde gesendet. |
| `data.result.message` | `string · null` | Hinweis zum Ergebnis oder null. |
| `data.result.soap_enrollment` | `object` | Ergebnis der Aufnahme in die Seifenoper (nur mit soap_sequence_id) oder null. |
| `data.result.soap_enrollment.ok` | `boolean` | Aufnahme erfolgreich. |
| `data.result.soap_enrollment.enrollment_id` | `integer` | ID der Teilnahme. |
| `data.result.soap_enrollment.error` | `string · null` | Grund, falls die Aufnahme nicht möglich war (z. B. Double-Opt-in noch offen). |
```json
{
"data": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
],
"result": {
"created": true,
"updated": false,
"status": "subscribed",
"doi_sent": false,
"message": null,
"soap_enrollment": {
"ok": true,
"enrollment_id": 501,
"error": null
}
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Für upsert: Kontakte (Felder wie POST /contacts). |
| `ids` | `array` | nein | Für delete: Kontakt-IDs. |
| `emails` | `array` | nein | Für delete: E-Mail-Adressen. |
| `list_ids` | `array` | nein | Für upsert: Listen für alle Kontakte. |
| `tags` | `array` | nein | Für upsert: Tags für alle Kontakte. |
| `duplicate` | `string` | nein | Für upsert: update (Standard) oder skip für bestehende Adressen. Werte: `update`, `skip`. |
| `run_automations` | `boolean` | nein | Webhooks und Listen-Automationen auslösen (Standard false). |
```bash
curl -X POST https://persolz.com/api/v1/contacts/bulk \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"action": "upsert",
"list_ids": [3],
"tags": ["messe-2026"],
"contacts": [
{
"email": "a@beispiel.de",
"first_name": "Alex"
},
{
"email": "b@beispiel.de",
"vorname": "Bea"
}
]
}'
```
**Antwort 200** – OK
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.action` | `string` | Ausgeführte Aktion: upsert oder delete. |
| `data.created` | `integer` | Neu angelegte Kontakte. |
| `data.updated` | `integer` | Aktualisierte Kontakte. |
| `data.skipped` | `integer` | Übersprungene Einträge (z. B. duplicate=skip). |
| `data.unchanged` | `integer` | Unverändert (keine neuen Daten). |
| `data.failed` | `integer` | Fehlgeschlagene Einträge (Details in errors). |
| `data.errors` | `array` | Fehler je Eintrag (leer, wenn alles geklappt hat). |
```json
{
"data": {
"action": "upsert",
"created": 2,
"updated": 0,
"skipped": 0,
"unchanged": 0,
"failed": 0,
"errors": []
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 413 `payload_too_large`, 422 `validation_error`, 429 `rate_limited`.
` | Teilnahmen an Seifenopern. |
| `data.soap_enrollments[].id` | `integer` | ID der Teilnahme. |
| `data.soap_enrollments[].sequence_id` | `integer` | ID der Seifenoper. |
| `data.soap_enrollments[].sequence_name` | `string` | Name der Seifenoper. |
| `data.soap_enrollments[].status` | `string` | Status der Teilnahme: active, paused, completed, cancelled, unsubscribed. |
| `data.soap_enrollments[].current_position` | `integer` | Zuletzt erreichter Tag (Position). |
| `data.soap_enrollments[].start_date` | `string (Datum)` | Startdatum. |
```json
{
"data": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
],
"engagement": {
"sent": 14,
"opened": 11,
"clicked": 4,
"failed": 0,
"open_rate": 0.7857,
"click_rate": 0.2857,
"last_activity_at": "2026-10-09T14:06:12+02:00"
},
"soap_enrollments": [
{
"id": 501,
"sequence_id": 7,
"sequence_name": "Willkommen bei Kartenherz",
"status": "active",
"current_position": 2,
"start_date": "2026-10-08"
}
]
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | nein | Tags (Array oder kommagetrennt). Beim Upsert werden Tags ergänzt. |
| `custom_fields` | `object` | nein | Eigene Felder (max. 50 Schlüssel a–z, 0–9, _ und -) – auch als Platzhalter {{schluessel}} nutzbar. |
| `status` | `string` | nein | subscribed \| pending \| unsubscribed. Abgemeldete Adressen werden nur mit consent=true reaktiviert. Werte: `subscribed`, `pending`, `unsubscribed`. |
| `list_ids` | `array` | nein | Listen, in die der Kontakt aufgenommen wird (Double-Opt-in der Liste wird beachtet). Aliase: lists (IDs oder Listen-Objekte wie in der Antwort), list_id. |
| `consent` | `boolean` | nein | Bestätigt eine neue Einwilligung (nötig, um abgemeldete Kontakte wieder anzumelden). |
| `doi` | `boolean` | nein | Erzwingt eine Bestätigungsmail (Double-Opt-in), auch wenn die Liste es nicht verlangt. |
| `add_list_ids` | `array` | nein | Listen hinzufügen. |
| `remove_list_ids` | `array` | nein | Aus Listen entfernen. |
```bash
curl -X PATCH https://persolz.com/api/v1/contacts/42 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Anna-Lena",
"tags": ["funnel", "kundin"],
"add_list_ids": [4]
}'
```
**Antwort 200** – OK · [Kontakt-Objekt](#obj-contact)
```json
{
"data": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Tags (Array oder kommagetrennt). Beim Upsert werden Tags ergänzt. |
| `custom_fields` | `object` | nein | Eigene Felder (max. 50 Schlüssel a–z, 0–9, _ und -) – auch als Platzhalter {{schluessel}} nutzbar. |
| `status` | `string` | nein | subscribed \| pending \| unsubscribed. Abgemeldete Adressen werden nur mit consent=true reaktiviert. Werte: `subscribed`, `pending`, `unsubscribed`. |
| `list_ids` | `array` | nein | Listen, in die der Kontakt aufgenommen wird (Double-Opt-in der Liste wird beachtet). Aliase: lists (IDs oder Listen-Objekte wie in der Antwort), list_id. |
| `consent` | `boolean` | nein | Bestätigt eine neue Einwilligung (nötig, um abgemeldete Kontakte wieder anzumelden). |
| `doi` | `boolean` | nein | Erzwingt eine Bestätigungsmail (Double-Opt-in), auch wenn die Liste es nicht verlangt. |
```bash
curl -X PUT https://persolz.com/api/v1/contacts/42 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt-Berg",
"city": "Hamburg"
}'
```
**Antwort 200** – OK · [Kontakt-Objekt](#obj-contact)
```json
{
"data": {
"id": 42,
"email": "anna@beispiel.de",
"first_name": "Anna",
"last_name": "Schmidt",
"address": "Lindenweg 3",
"zip": "10115",
"city": "Berlin",
"phone": "+49 30 1234567",
"note": "Kam über den Kartenherz-Funnel",
"tags": ["funnel", "kartenherz"],
"status": "subscribed",
"source": "api",
"custom_fields": {
"kundennummer": "K-1001"
},
"doi_confirmed_at": null,
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00",
"lists": [
{
"id": 3,
"name": "Kartenherz Funnel",
"color": "#5B3DF5"
}
]
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`.
` | Einträge, neueste zuerst. |
| `data.items[].type` | `string` | Art: sent, opened, clicked, unsubscribed, soap, appointment, list, doi … |
| `data.items[].title` | `string` | Überschrift des Eintrags. |
| `data.items[].body` | `string` | Details (z. B. Betreff der Mail). |
| `data.items[].time` | `string (Datum/Zeit)` | Zeitpunkt (ISO 8601). |
```json
{
"data": {
"engagement": {
"sent": 14,
"opened": 11,
"clicked": 4,
"failed": 0,
"open_rate": 0.7857,
"click_rate": 0.2857,
"last_activity_at": "2026-10-09T14:06:12+02:00"
},
"items": [
{
"type": "opened",
"title": "E-Mail geöffnet",
"body": "„Was mein Kaffeebecher über Marketing weiß“",
"time": "2026-10-09T14:05:00+02:00"
},
{
"type": "list",
"title": "Zur Liste „Kartenherz Funnel“ hinzugefügt",
"body": "",
"time": "2026-10-01T09:00:00+02:00"
}
]
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | IDs der Empfänger-Listen. |
| `audience.contacts` | `array` | IDs einzelner Kontakte. |
| `audience.emails` | `array` | Einzelne E-Mail-Adressen. |
| `audience_label` | `string` | Empfänger in Worten, z. B. „1 Liste“. |
| `smtp_account_id` | `integer` | SMTP-Konto für den Versand oder null (= Standardkonto des Moduls). |
| `attachment_ids` | `array` | IDs der Anhänge aus der Anhang-Cloud. |
| `include_default_attachments` | `boolean` | Standard-Anhänge werden zusätzlich mitgesendet. |
| `track_opens` | `boolean` | Öffnungen werden gemessen. |
| `track_clicks` | `boolean` | Klicks werden gemessen. |
| `ab_test_id` | `integer · null` | ID des verknüpften A/B-Tests oder null. |
| `scheduled_at` | `string · null` | Geplanter Versandzeitpunkt (ISO 8601) oder null. |
| `started_at` | `string (Datum/Zeit)` | Beginn des Versands oder null. |
| `finished_at` | `string (Datum/Zeit)` | Ende des Versands oder null. |
| `stats` | `object` | Kennzahlen des Versands. |
| `stats.recipients` | `integer` | Empfänger gesamt. |
| `stats.sent` | `integer` | Versendet. |
| `stats.failed` | `integer` | Fehlgeschlagen. |
| `stats.unique_opens` | `integer` | Empfänger mit mindestens einer Öffnung. |
| `stats.unique_clicks` | `integer` | Empfänger mit mindestens einem Klick. |
| `stats.unsubs` | `integer` | Abmeldungen. |
| `stats.open_rate` | `number` | Öffnungsrate von 0 bis 1 (eindeutige Öffnungen / versendet). |
| `stats.click_rate` | `number` | Klickrate von 0 bis 1 (eindeutige Klicks / versendet). |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"id": 812,
"type": "newsletter",
"type_label": "Newsletter",
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"preheader": "Nur bis Sonntag: Dein Herbst-Bonus",
"status": "sent",
"status_label": "Gesendet",
"audience": {
"all": false,
"lists": [3],
"contacts": [],
"emails": []
},
"audience_label": "1 Liste",
"smtp_account_id": 1,
"attachment_ids": [],
"include_default_attachments": false,
"track_opens": true,
"track_clicks": true,
"ab_test_id": null,
"scheduled_at": null,
"started_at": "2026-10-09T09:00:00+02:00",
"finished_at": "2026-10-09T09:04:31+02:00",
"stats": {
"recipients": 1250,
"sent": 1248,
"failed": 2,
"unique_opens": 702,
"unique_clicks": 133,
"unsubs": 3,
"open_rate": 0.5625,
"click_rate": 0.1066
},
"created_at": "2026-10-08T17:20:00+02:00",
"updated_at": "2026-10-09T09:04:31+02:00"
}
```
` | nein | Zusätzlich alle aktiven Mitglieder dieser Listen. |
| `subject` | `string` | ja | Betreff (Pflicht, außer die Vorlage liefert einen). Platzhalter erlaubt. |
| `html` | `string` | nein | HTML-Inhalt (max. 2 MB). |
| `text` | `string` | nein | Alternativ: reiner Text (wird in eine schlichte HTML-Mail verpackt). |
| `template_key` | `string` | nein | Bibliotheks-Vorlage, z. B. email-07. |
| `template_id` | `integer` | nein | Eigene Vorlage. |
| `preheader` | `string` | nein | Vorschautext. |
| `placeholders` | `object` | nein | Eigene Platzhalter für alle Empfänger, z. B. {"bestellnummer":"4711"} → {{bestellnummer}}. |
| `smtp_account_id` | `integer` | nein | SMTP-Konto (Standard: Modul- bzw. Standardkonto). |
| `attachment_ids` | `array` | nein | Anhänge aus der Anhang-Cloud. |
| `include_default_attachments` | `boolean` | nein | Standard-Anhänge mitsenden (Standard false). |
| `scheduled_at` | `string` | nein | Geplanter Versand (ISO 8601, max. 1 Jahr). Leer = sofort. |
| `name` | `string` | nein | Interner Name (Standard: Betreff). |
| `from_name` | `string` | nein | Abweichender Absendername. |
| `reply_to` | `string` | nein | Abweichende Antwort-Adresse. |
| `track_opens` | `boolean` | nein | Öffnungen messen (Standard true). |
| `track_clicks` | `boolean` | nein | Klicks messen (Standard true). |
```bash
curl -X POST https://persolz.com/api/v1/emails/send \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"to": ["anna@beispiel.de"],
"subject": "Deine Bestellung #{{bestellnummer}}",
"html": "Hallo {{vorname|Freund}},
danke für Deine Bestellung {{bestellnummer}}!
",
"placeholders": {
"bestellnummer": "4711"
},
"attachment_ids": [9]
}'
```
**Antwort 202** – In der Warteschlange bzw. geplant
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.campaign_id` | `integer` | ID der E-Mail – damit fragst Du den Status ab (GET /emails/{id}). |
| `data.status` | `string` | sending (wird versendet) oder scheduled (geplant). |
| `data.scheduled_at` | `string · null` | Geplanter Versandzeitpunkt (ISO 8601) oder null. |
| `data.recipients` | `integer` | Empfänger gesamt. |
| `data.queued` | `integer` | In die Warteschlange gestellte E-Mails. |
| `data.sent` | `integer` | Bereits versendet (Rest folgt automatisch). |
| `data.failed` | `integer` | Fehlgeschlagen. |
| `data.message` | `string` | Verständliche Meldung auf Deutsch. |
```json
{
"data": {
"campaign_id": 813,
"status": "sending",
"scheduled_at": null,
"recipients": 1,
"queued": 1,
"sent": 1,
"failed": 0,
"message": "Versand abgeschlossen: 1 E-Mail verschickt."
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
Hallo {{vorname}} …
"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | nein | Kurzform für audience.lists. |
| `smtp_account_id` | `integer` | nein | SMTP-Konto. |
| `attachment_ids` | `array` | nein | Anhänge. |
| `include_default_attachments` | `boolean` | nein | Standard-Anhänge mitsenden. |
| `from_name` | `string` | nein | Abweichender Absendername. |
| `reply_to` | `string` | nein | Abweichende Antwort-Adresse. |
| `track_opens` | `boolean` | nein | Öffnungen messen. |
| `track_clicks` | `boolean` | nein | Klicks messen. |
```bash
curl -X POST https://persolz.com/api/v1/newsletters \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"template_key": "newsletter-01",
"list_ids": [3]
}'
```
**Antwort 201** – Entwurf angelegt · [Kampagnen-Objekt](#obj-campaign)
```json
{
"data": {
"status": "draft",
"status_label": "Entwurf",
"started_at": null,
"finished_at": null,
"id": 812,
"type": "newsletter",
"type_label": "Newsletter",
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"preheader": "Nur bis Sonntag: Dein Herbst-Bonus",
"audience": {
"all": false,
"lists": [3],
"contacts": [],
"emails": []
},
"audience_label": "1 Liste",
"smtp_account_id": 1,
"attachment_ids": [],
"include_default_attachments": false,
"track_opens": true,
"track_clicks": true,
"ab_test_id": null,
"scheduled_at": null,
"stats": {
"recipients": 1250,
"sent": 1248,
"failed": 2,
"unique_opens": 702,
"unique_clicks": 133,
"unsubs": 3,
"open_rate": 0.5625,
"click_rate": 0.1066
},
"created_at": "2026-10-08T17:20:00+02:00",
"updated_at": "2026-10-09T09:04:31+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Kurzform für audience.lists. |
| `smtp_account_id` | `integer` | nein | SMTP-Konto. |
| `attachment_ids` | `array` | nein | Anhänge. |
| `include_default_attachments` | `boolean` | nein | Standard-Anhänge mitsenden. |
| `from_name` | `string` | nein | Abweichender Absendername. |
| `reply_to` | `string` | nein | Abweichende Antwort-Adresse. |
| `track_opens` | `boolean` | nein | Öffnungen messen. |
| `track_clicks` | `boolean` | nein | Klicks messen. |
```bash
curl -X PATCH https://persolz.com/api/v1/newsletters/42 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"subject": "Neuer Betreff",
"list_ids": [3, 4]
}'
```
**Antwort 200** – OK · [Kampagnen-Objekt](#obj-campaign)
```json
{
"data": {
"id": 812,
"type": "newsletter",
"type_label": "Newsletter",
"name": "Herbst-Aktion",
"subject": "Anna, das hier ist nur für Dich",
"preheader": "Nur bis Sonntag: Dein Herbst-Bonus",
"status": "sent",
"status_label": "Gesendet",
"audience": {
"all": false,
"lists": [3],
"contacts": [],
"emails": []
},
"audience_label": "1 Liste",
"smtp_account_id": 1,
"attachment_ids": [],
"include_default_attachments": false,
"track_opens": true,
"track_clicks": true,
"ab_test_id": null,
"scheduled_at": null,
"started_at": "2026-10-09T09:00:00+02:00",
"finished_at": "2026-10-09T09:04:31+02:00",
"stats": {
"recipients": 1250,
"sent": 1248,
"failed": 2,
"unique_opens": 702,
"unique_clicks": 133,
"unsubs": 3,
"open_rate": 0.5625,
"click_rate": 0.1066
},
"created_at": "2026-10-08T17:20:00+02:00",
"updated_at": "2026-10-09T09:04:31+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`.
` | Empfänger der Testmail. |
| `data.message` | `string` | Verständliche Meldung auf Deutsch. |
```json
{
"data": {
"sent_to": ["du@beispiel.de"],
"message": "Testmail an du@beispiel.de gesendet."
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | Meistgeklickte Links. |
| `data.links[].url` | `string` | Ziel-URL des Links. |
| `data.links[].label` | `string` | Linktext. |
| `data.links[].clicks` | `integer` | Klicks gesamt. |
| `data.links[].unique_clicks` | `integer` | Empfänger, die geklickt haben. |
| `data.devices` | `object` | Öffnungen nach Gerät. |
| `data.devices.desktop` | `integer` | Öffnungen am Desktop. |
| `data.devices.mobile` | `integer` | Öffnungen auf dem Smartphone. |
| `data.devices.tablet` | `integer` | Öffnungen auf dem Tablet. |
```json
{
"data": {
"id": 812,
"status": "sent",
"stats": {
"recipients": 1250,
"sent": 1248,
"failed": 2,
"pending": 0,
"held": 0,
"skipped": 0,
"cancelled": 0,
"opens": 980,
"unique_opens": 702,
"clicks": 190,
"unique_clicks": 133,
"unsubs": 3,
"open_rate": 0.5625,
"click_rate": 0.1066,
"ctor": 0.1895,
"unsub_rate": 0.0024,
"bounce_rate": 0.0016,
"failed_rate": 0.0016,
"progress": 1.0
},
"links": [
{
"url": "https://kartenherz.com/angebot",
"label": "Jetzt ansehen",
"clicks": 140,
"unique_clicks": 118
}
],
"devices": {
"desktop": 312,
"mobile": 365,
"tablet": 25
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | Versandtage bei custom: 1 (Mo) bis 7 (So). |
| `every_n_days` | `integer` | Abstand in Tagen bei interval. |
| `anchor` | `string (Datum)` | Startdatum des Rhythmus bei interval. |
| `send_time` | `string` | Versandzeit (HH:MM, Europe/Berlin). |
| `smtp_account_id` | `integer · null` | SMTP-Konto für den Versand oder null (= Standardkonto des Moduls). |
| `audience` | `object` | Empfänger: {all, lists, contacts, emails} oder null. |
| `audience.all` | `boolean` | An alle aktiven Kontakte senden. |
| `audience.lists` | `array` | IDs der Empfänger-Listen. |
| `audience.contacts` | `array` | IDs einzelner Kontakte. |
| `audience.emails` | `array` | Einzelne E-Mail-Adressen. |
| `auto_generate` | `boolean` | Die KI schreibt automatisch Entwürfe für freie Termine. |
| `auto_send` | `boolean` | KI-Entwürfe werden ohne Freigabe automatisch geplant. |
| `plan_ahead_days` | `integer` | So viele Tage im Voraus werden Entwürfe vorbereitet. |
| `ai_model` | `string` | KI-Modell: sonnet (beste Qualität) oder haiku (schnell & günstig). |
| `persona` | `object` | Persona, mit der die KI schreibt. |
| `persona.name` | `string` | Name des Absenders in den Geschichten. |
| `persona.character` | `string` | Charakter. |
| `persona.background` | `string` | Hintergrund. |
| `persona.style` | `string` | Schreibstil. |
| `audience_desc` | `string` | Beschreibung Deiner Zielgruppe (für die KI). |
| `offer_name` | `string` | Name Deines Angebots. |
| `offer_url` | `string` | Link zum Angebot. |
| `offer_desc` | `string` | Kurzbeschreibung des Angebots. |
| `tone` | `string` | Tonalität. |
| `signature` | `string` | Grußformel unter jeder Mail. |
| `template_key` | `string` | Design-Vorlage aus der Vorlagen-Bibliothek (z. B. seinfeld-01) oder null. |
| `continuity_mode` | `string` | Story-Kontinuität: z. B. arcs (zusammenhängende Story-Bögen). |
| `include_default_attachments` | `boolean` | Standard-Anhänge werden zusätzlich mitgesendet. |
| `rhythm` | `string` | Rhythmus in Worten. |
| `streak` | `integer` | Aktuelle Serie: Versandtage in Folge ohne Lücke. |
```json
{
"enabled": true,
"frequency": "weekdays",
"weekdays": [1, 2, 3, 4, 5],
"every_n_days": 2,
"anchor": "2026-10-01",
"send_time": "09:00",
"smtp_account_id": null,
"audience": {
"all": false,
"lists": [3],
"contacts": [],
"emails": []
},
"auto_generate": true,
"auto_send": false,
"plan_ahead_days": 3,
"ai_model": "sonnet",
"persona": {
"name": "Daniel",
"character": "Humorvoller Kartenmacher",
"background": "Seit 10 Jahren Illustrator",
"style": "locker, Du-Form"
},
"audience_desc": "Menschen, die gern Karten verschicken",
"offer_name": "Kartenset-Abo",
"offer_url": "https://kartenherz.com/abo",
"offer_desc": "Jeden Monat 5 handgezeichnete Karten",
"tone": "unterhaltsam",
"signature": "Dein Daniel",
"template_key": "seinfeld-01",
"continuity_mode": "arcs",
"include_default_attachments": false,
"rhythm": "Montag bis Freitag um 09:00 Uhr",
"streak": 12
}
```
` | Stichworte. |
| `template_key` | `string` | Design-Vorlage aus der Vorlagen-Bibliothek (z. B. seinfeld-01) oder null. |
| `scheduled_at` | `string (Datum/Zeit)` | Geplanter Versandzeitpunkt (ISO 8601) oder null. |
| `sent_at` | `string · null` | Zeitpunkt des Versands oder null. |
| `campaign_id` | `integer` | Kampagne des Versands (nach dem Planen) oder null. |
| `smtp_account_id` | `integer · null` | SMTP-Konto für den Versand oder null (= Standardkonto des Moduls). |
| `audience` | `object · null` | Abweichende Empfänger oder null (= Einstellungen). |
| `attachment_ids` | `array` | IDs der Anhänge aus der Anhang-Cloud. |
| `include_default_attachments` | `boolean` | Standard-Anhänge werden zusätzlich mitgesendet. |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"id": 120,
"subject": "Was mein Kaffeebecher über Marketing weiß",
"preheader": "Eine Geschichte über Gewohnheiten",
"html": "…",
"status": "scheduled",
"status_label": "Geplant",
"ai_generated": true,
"ai_model": "claude-sonnet-5-5",
"topic_id": 15,
"arc_id": null,
"episode_no": null,
"story_title": "Der Kaffeebecher",
"story_summary": "Warum kleine Rituale Vertrauen schaffen.",
"keywords": ["kaffee", "gewohnheit"],
"template_key": "seinfeld-01",
"scheduled_at": "2026-10-10T09:00:00+02:00",
"sent_at": null,
"campaign_id": 901,
"smtp_account_id": null,
"audience": null,
"attachment_ids": [],
"include_default_attachments": false,
"created_at": "2026-10-09T07:00:00+02:00",
"updated_at": "2026-10-09T08:12:00+02:00"
}
```
` | nein | Bei custom: Wochentage 1 (Mo) – 7 (So). |
| `every_n_days` | `integer` | nein | Bei interval: Abstand in Tagen (2–30). |
| `send_time` | `string` | nein | Uhrzeit HH:MM. |
| `audience` | `object` | nein | Empfänger {all, lists, contacts, emails}. |
| `auto_generate` | `boolean` | nein | KI schreibt Entwürfe für freie Termine. |
| `auto_send` | `boolean` | nein | KI-Entwürfe ohne Freigabe automatisch planen. |
| `plan_ahead_days` | `integer` | nein | So viele Tage im Voraus vorbereiten (1–14). |
| `ai_model` | `string` | nein | sonnet \| haiku |
| `persona` | `object` | nein | {name, character, background, style}. |
| `offer_name` | `string` | nein | Angebot. |
| `offer_url` | `string` | nein | Link zum Angebot. |
| `tone` | `string` | nein | Tonalität. |
| `signature` | `string` | nein | Grußformel. |
| `template_key` | `string` | nein | Seinfeld-Vorlage. |
| `smtp_account_id` | `integer` | nein | SMTP-Konto. |
```bash
curl -X PUT https://persolz.com/api/v1/seinfeld/settings \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"frequency": "weekdays",
"send_time": "09:00",
"audience": {
"lists": [3]
},
"offer_url": "https://kartenherz.com/abo"
}'
```
**Antwort 200** – OK · [Seinfeld-Einstellungs-Objekt](#obj-seinfeld-settings)
```json
{
"data": {
"enabled": true,
"frequency": "weekdays",
"weekdays": [1, 2, 3, 4, 5],
"every_n_days": 2,
"anchor": "2026-10-01",
"send_time": "09:00",
"smtp_account_id": null,
"audience": {
"all": false,
"lists": [3],
"contacts": [],
"emails": []
},
"auto_generate": true,
"auto_send": false,
"plan_ahead_days": 3,
"ai_model": "sonnet",
"persona": {
"name": "Daniel",
"character": "Humorvoller Kartenmacher",
"background": "Seit 10 Jahren Illustrator",
"style": "locker, Du-Form"
},
"audience_desc": "Menschen, die gern Karten verschicken",
"offer_name": "Kartenset-Abo",
"offer_url": "https://kartenherz.com/abo",
"offer_desc": "Jeden Monat 5 handgezeichnete Karten",
"tone": "unterhaltsam",
"signature": "Dein Daniel",
"template_key": "seinfeld-01",
"continuity_mode": "arcs",
"include_default_attachments": false,
"rhythm": "Montag bis Freitag um 09:00 Uhr",
"streak": 12
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Stichworte. |
| `smtp_account_id` | `integer` | nein | SMTP-Konto (Standard: Einstellungen). |
| `audience` | `object` | nein | Abweichende Empfänger (Standard: Einstellungen). |
| `attachment_ids` | `array` | nein | Anhänge. |
| `template_key` | `string` | nein | Design-Vorlage. |
```bash
curl -X POST https://persolz.com/api/v1/seinfeld/emails \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"subject": "Was mein Kaffeebecher über Marketing weiß",
"html": "Heute Morgen …
",
"topic_id": 15
}'
```
**Antwort 201** – Angelegt · [Seinfeld-Mail-Objekt](#obj-seinfeld-email)
```json
{
"data": {
"status": "draft",
"status_label": "Entwurf",
"campaign_id": null,
"ai_generated": false,
"id": 120,
"subject": "Was mein Kaffeebecher über Marketing weiß",
"preheader": "Eine Geschichte über Gewohnheiten",
"html": "…",
"ai_model": "claude-sonnet-5-5",
"topic_id": 15,
"arc_id": null,
"episode_no": null,
"story_title": "Der Kaffeebecher",
"story_summary": "Warum kleine Rituale Vertrauen schaffen.",
"keywords": ["kaffee", "gewohnheit"],
"template_key": "seinfeld-01",
"scheduled_at": "2026-10-10T09:00:00+02:00",
"sent_at": null,
"smtp_account_id": null,
"audience": null,
"attachment_ids": [],
"include_default_attachments": false,
"created_at": "2026-10-09T07:00:00+02:00",
"updated_at": "2026-10-09T08:12:00+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Stichworte. |
| `smtp_account_id` | `integer` | nein | SMTP-Konto (Standard: Einstellungen). |
| `audience` | `object` | nein | Abweichende Empfänger (Standard: Einstellungen). |
| `attachment_ids` | `array` | nein | Anhänge. |
| `template_key` | `string` | nein | Design-Vorlage. |
```bash
curl -X PATCH https://persolz.com/api/v1/seinfeld/emails/42 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"subject": "Neuer Betreff"
}'
```
**Antwort 200** – OK · [Seinfeld-Mail-Objekt](#obj-seinfeld-email)
```json
{
"data": {
"id": 120,
"subject": "Was mein Kaffeebecher über Marketing weiß",
"preheader": "Eine Geschichte über Gewohnheiten",
"html": "…",
"status": "scheduled",
"status_label": "Geplant",
"ai_generated": true,
"ai_model": "claude-sonnet-5-5",
"topic_id": 15,
"arc_id": null,
"episode_no": null,
"story_title": "Der Kaffeebecher",
"story_summary": "Warum kleine Rituale Vertrauen schaffen.",
"keywords": ["kaffee", "gewohnheit"],
"template_key": "seinfeld-01",
"scheduled_at": "2026-10-10T09:00:00+02:00",
"sent_at": null,
"campaign_id": 901,
"smtp_account_id": null,
"audience": null,
"attachment_ids": [],
"include_default_attachments": false,
"created_at": "2026-10-09T07:00:00+02:00",
"updated_at": "2026-10-09T08:12:00+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`.
` | Stichworte. |
| `data.model` | `string` | Verwendetes KI-Modell. |
| `data.cost_eur` | `number` | Kosten dieser KI-Anfrage in Euro (wird vom KI-Guthaben abgezogen). |
| `data.email_id` | `integer` | ID des gespeicherten Entwurfs (bei persist=true) oder null. |
| `data.warning` | `string · null` | Hinweis (z. B. wenn die KI gekürzt hat) oder null. |
```json
{
"data": {
"subject": "Der Tag, an dem Bruno die Post fraß",
"preheader": "Und warum das gut fürs Geschäft war",
"html": "…",
"story_title": "Bruno und die Post",
"story_summary": "…",
"keywords": ["hund", "post"],
"model": "claude-sonnet-5-5",
"cost_eur": 0.0123,
"email_id": 121,
"warning": null
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
` | Die geplanten Tage. |
| `data.days[].day` | `integer` | Versandtag. |
| `data.days[].stage` | `string` | Etappe. |
| `data.days[].subject` | `string` | Betreffvorschlag. |
| `data.days[].summary` | `string` | Inhalt in Kurzform. |
| `data.days[].hook` | `string` | Cliffhanger zum nächsten Tag. |
| `data.warning` | `string · null` | Hinweis (z. B. wenn die KI gekürzt hat) oder null. |
| `data.cost_eur` | `number` | Kosten dieser KI-Anfrage in Euro (wird vom KI-Guthaben abgezogen). |
| `data.sequence_id` | `integer · null` | ID der angelegten Sequenz (bei create=true) oder null. |
```json
{
"data": {
"title": "Von der leeren Mappe zum Abo",
"days": [
{
"day": 1,
"stage": "buehne",
"subject": "Wie alles mit einer Postkarte begann",
"summary": "…",
"hook": "Morgen erzähle ich Dir, was dann schiefging."
}
],
"warning": null,
"cost_eur": 0.021,
"sequence_id": null
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
` | Tage der Sequenz (ohne HTML). Siehe [Tages-Objekt](#obj-step). |
| `data.stats` | `object` | Kennzahlen. |
| `data.stats.sent` | `integer` | Versendet. |
| `data.stats.opens` | `integer` | Öffnungen gesamt (inkl. mehrfacher Öffnungen). |
| `data.stats.clicks` | `integer` | Klicks gesamt. |
| `data.stats.open_rate` | `number` | Öffnungsrate von 0 bis 1 (eindeutige Öffnungen / versendet). |
| `data.stats.click_rate` | `number` | Klickrate von 0 bis 1 (eindeutige Klicks / versendet). |
| `data.stats.completion_rate` | `number` | Anteil der Teilnehmer, die alle Tage erhalten haben (0 bis 1). |
```json
{
"data": {
"id": 7,
"name": "Willkommen bei Kartenherz",
"description": "5 Tage Story-Sequenz für neue Leads",
"goal": "Verkauf des Kartenset-Abos",
"status": "active",
"status_label": "Aktiv",
"trigger_type": "list_join",
"trigger_list_id": 3,
"trigger_label": "Beim Eintrag in „Kartenherz Funnel“",
"send_time": "09:00",
"skip_weekends": false,
"smtp_account_id": null,
"ai_model": "sonnet",
"template_key": "soap-01",
"include_default_attachments": false,
"step_count": 5,
"enrolled_active": 312,
"enrolled_completed": 845,
"sent": 4980,
"open_rate": 0.61,
"click_rate": 0.14,
"created_at": "2026-09-01T10:00:00+02:00",
"updated_at": "2026-10-01T08:30:00+02:00",
"steps": [
{
"id": 31,
"sequence_id": 7,
"position": 1,
"day": 1,
"is_active": true,
"stage": "buehne",
"stage_label": "Bühne bereiten",
"subject": "Wie alles mit einer Postkarte begann",
"preheader": "Tag 1 von 5",
"attachment_ids": [],
"include_default_attachments": false,
"campaign_id": 950,
"ab_test_id": null,
"stats": {
"sent": 1157,
"opens": 760,
"clicks": 98,
"unsubs": 4,
"open_rate": 0.6569,
"click_rate": 0.0847
},
"created_at": "2026-09-01T10:00:00+02:00",
"updated_at": "2026-09-02T11:00:00+02:00"
}
],
"stats": {
"sent": 4980,
"opens": 3038,
"clicks": 697,
"open_rate": 0.61,
"click_rate": 0.14,
"completion_rate": 0.73
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | nein | Anhänge. |
| `include_default_attachments` | `boolean` | nein | Standard-Anhänge. |
| `after_step_id` | `integer` | nein | Nur beim Anlegen: hinter diesem Tag einfügen (Standard: ans Ende). |
```bash
curl -X POST https://persolz.com/api/v1/sequences/42/steps \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"subject": "Das Drama beginnt",
"html": "Gestern habe ich Dir erzählt …
",
"day": 2,
"stage": "drama"
}'
```
**Antwort 201** – Angelegt · [Tages-Objekt](#obj-step)
```json
{
"data": {
"id": 31,
"sequence_id": 7,
"position": 1,
"day": 1,
"is_active": true,
"stage": "buehne",
"stage_label": "Bühne bereiten",
"subject": "Wie alles mit einer Postkarte begann",
"preheader": "Tag 1 von 5",
"html": "…",
"attachment_ids": [],
"include_default_attachments": false,
"campaign_id": 950,
"ab_test_id": null,
"stats": {
"sent": 1157,
"opens": 760,
"clicks": 98,
"unsubs": 4,
"open_rate": 0.6569,
"click_rate": 0.0847
},
"created_at": "2026-09-01T10:00:00+02:00",
"updated_at": "2026-09-02T11:00:00+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Anhänge. |
| `include_default_attachments` | `boolean` | nein | Standard-Anhänge. |
| `after_step_id` | `integer` | nein | Nur beim Anlegen: hinter diesem Tag einfügen (Standard: ans Ende). |
```bash
curl -X PATCH https://persolz.com/api/v1/sequences/42/steps/31 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"subject": "Neuer Betreff für Tag 1",
"is_active": true
}'
```
**Antwort 200** – OK · [Tages-Objekt](#obj-step)
```json
{
"data": {
"id": 31,
"sequence_id": 7,
"position": 1,
"day": 1,
"is_active": true,
"stage": "buehne",
"stage_label": "Bühne bereiten",
"subject": "Wie alles mit einer Postkarte begann",
"preheader": "Tag 1 von 5",
"html": "…",
"attachment_ids": [],
"include_default_attachments": false,
"campaign_id": 950,
"ab_test_id": null,
"stats": {
"sent": 1157,
"opens": 760,
"clicks": 98,
"unsubs": 4,
"open_rate": 0.6569,
"click_rate": 0.0847
},
"created_at": "2026-09-01T10:00:00+02:00",
"updated_at": "2026-09-02T11:00:00+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Kontakt-IDs. |
| `emails` | `array` | nein | E-Mail-Adressen. |
| `list_id` | `integer` | nein | Alle aktiven Mitglieder dieser Liste. |
| `start_date` | `string` | nein | Startdatum YYYY-MM-DD, „today“ oder „tomorrow“ (Standard heute). Vergangene Daten holen verpasste Tage sofort nach. |
```bash
curl -X POST https://persolz.com/api/v1/sequences/42/enroll \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"contact_ids": [42],
"emails": ["ben@beispiel.de"],
"start_date": "tomorrow"
}'
```
**Antwort 200** – OK
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.enrolled` | `integer` | Neu aufgenommene Kontakte. |
| `data.already` | `integer` | Bereits teilnehmende Kontakte (übersprungen). |
| `data.skipped` | `integer` | Übersprungene Kontakte (abgemeldet oder unbestätigt). |
| `data.created` | `integer` | Neu angelegte Kontakte (unbekannte E-Mail-Adressen). |
| `data.total` | `integer` | Teilnehmer insgesamt nach dem Aufnehmen. |
| `data.message` | `string` | Verständliche Meldung auf Deutsch. |
```json
{
"data": {
"enrolled": 2,
"already": 0,
"skipped": 0,
"created": 1,
"total": 2,
"message": "2 Kontakte aufgenommen. 1 neuer Kontakt wurde angelegt."
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | Tags (Schlagworte). |
| `subject` | `string` | Betreff. |
| `preheader` | `string` | Vorschautext (erscheint im Postfach neben dem Betreff). |
| `theme` | `string` | Farbschema der Vorlage. |
| `is_favorite` | `boolean` | Als Favorit markiert. |
| `updated_at` | `string · null` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"source": "library",
"id": null,
"key": "newsletter-01",
"ref": "lib:newsletter-01",
"name": "Wochen-Digest",
"category": "newsletter",
"category_label": "Newsletter",
"description": "Drei Themen der Woche mit Bild und Button",
"tags": ["digest"],
"subject": "Deine Woche in 3 Minuten",
"preheader": "Das Wichtigste auf einen Blick",
"theme": "persolz",
"is_favorite": false,
"updated_at": null
}
```
` | Meistgeklickte Links. |
| `data.links[].url` | `string` | Ziel-URL des Links. |
| `data.links[].label` | `string` | Linktext. |
| `data.links[].clicks` | `integer` | Klicks gesamt. |
| `data.links[].unique_clicks` | `integer` | Empfänger, die geklickt haben. |
| `data.devices` | `object` | Öffnungen nach Gerät. |
| `data.devices.desktop` | `integer` | Öffnungen am Desktop. |
| `data.devices.mobile` | `integer` | Öffnungen auf dem Smartphone. |
| `data.devices.tablet` | `integer` | Öffnungen auf dem Tablet. |
```json
{
"data": {
"id": 812,
"type": "newsletter",
"status": "sent",
"stats": {
"recipients": 1250,
"sent": 1248,
"failed": 2,
"pending": 0,
"held": 0,
"skipped": 0,
"cancelled": 0,
"opens": 980,
"unique_opens": 702,
"clicks": 190,
"unique_clicks": 133,
"unsubs": 3,
"open_rate": 0.5625,
"click_rate": 0.1066,
"ctor": 0.1895,
"unsub_rate": 0.0024,
"bounce_rate": 0.0016,
"failed_rate": 0.0016,
"progress": 1.0
},
"links": [
{
"url": "https://kartenherz.com/angebot",
"label": "Jetzt ansehen",
"clicks": 140,
"unique_clicks": 118
}
],
"devices": {
"desktop": 312,
"mobile": 365,
"tablet": 25
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | Beschriftungen der Zeitachse. |
| `data.timeline.series` | `array` | Datenreihen. |
| `data.modules` | `array` | Kennzahlen je Modul (Seinfeld, Seifenopern, Newsletter, E-Mails). |
| `data.devices` | `array` | Öffnungen nach Gerät. |
| `data.links` | `array` | Meistgeklickte Links. |
| `data.growth` | `array` | Listenwachstum im Zeitraum. |
```json
{
"data": {
"period": {
"from": "2026-09-10",
"to": "2026-10-09",
"days": 30,
"type": "all",
"label": "letzte 30 Tage (10.09.–09.10.2026)"
},
"kpis": {
"sent": 8420,
"unique_opens": 4630,
"unique_clicks": 912,
"unsubs": 21,
"open_rate": 0.55,
"click_rate": 0.108
},
"timeline": {
"labels": ["10.09.", "11.09."],
"series": []
},
"modules": [],
"devices": [],
"links": [],
"growth": []
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 429 `rate_limited`.
` | Die Varianten. |
| `variants[].variant` | `string` | Variante (A oder B). |
| `variants[].subject` | `string` | Betreff der Variante. |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"id": 21,
"name": "Betreff-Test: Herbst-Aktion",
"target_type": "newsletter",
"target_id": 812,
"test_type": "subject",
"mode": "winner",
"split_a": 50,
"sample_pct": 20,
"wait_hours": 4,
"winner_metric": "clicks",
"status": "running",
"status_label": "Läuft",
"winner": null,
"auto_apply_winner": true,
"variants": [
{
"variant": "A",
"subject": "Anna, das hier ist nur für Dich"
},
{
"variant": "B",
"subject": "Dein Herbst-Bonus wartet"
}
],
"created_at": "2026-10-08T17:30:00+02:00",
"updated_at": "2026-10-09T09:00:00+02:00"
}
```
` | E-Mail-Adressen der Teilnehmer. |
| `phone` | `string` | Telefonnummer für den Termin. |
| `color` | `string` | Farbe im Kalender: violet, coral, mint, gold, blue, pink, green oder lilac. |
| `status` | `string` | planned (geplant), done (erledigt), cancelled (abgesagt) oder no_show (nicht erschienen). |
| `status_label` | `string` | Status in Worten (Deutsch). |
| `reminder_minutes` | `integer` | Erinnerung so viele Minuten vor Beginn (-1 = keine). |
| `remind_attendees` | `boolean` | Teilnehmer werden ebenfalls erinnert. |
| `source` | `string` | Herkunft: app, api, google … |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"id": 55,
"title": "Erstgespräch Anna Schmidt",
"description": "Kennenlernen per Video",
"location": "Zoom",
"start_at": "2026-10-14T10:00:00+02:00",
"end_at": "2026-10-14T10:30:00+02:00",
"all_day": false,
"contact_id": 42,
"contact": {
"id": 42,
"name": "Anna Schmidt",
"email": "anna@beispiel.de",
"phone": "+49 30 1234567"
},
"attendees": ["anna@beispiel.de"],
"phone": "",
"color": "violet",
"status": "planned",
"status_label": "Geplant",
"reminder_minutes": 60,
"remind_attendees": true,
"source": "api",
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00"
}
```
` | nein | Teilnehmer-Adressen. |
| `phone` | `string` | nein | Telefon. |
| `color` | `string` | nein | Farbe: violet, coral, mint, gold, blue, pink, green, lilac. Werte: `violet`, `coral`, `mint`, `gold`, `blue`, `pink`, `green`, `lilac`. |
| `reminder_minutes` | `integer` | nein | Erinnerung x Minuten vorher (-1 = keine, 0 = zum Beginn, max. 40320). |
| `remind_attendees` | `boolean` | nein | Auch Teilnehmer erinnern. |
| `status` | `string` | nein | planned \| done \| cancelled \| no_show Werte: `planned`, `done`, `cancelled`, `no_show`. |
```bash
curl -X POST https://persolz.com/api/v1/appointments \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"title": "Erstgespräch Anna Schmidt",
"start_at": "2026-10-14T10:00:00+02:00",
"end_at": "2026-10-14T10:30:00+02:00",
"contact_id": 42,
"location": "Zoom"
}'
```
**Antwort 201** – Angelegt · [Termin-Objekt](#obj-appointment)
```json
{
"data": {
"id": 55,
"title": "Erstgespräch Anna Schmidt",
"description": "Kennenlernen per Video",
"location": "Zoom",
"start_at": "2026-10-14T10:00:00+02:00",
"end_at": "2026-10-14T10:30:00+02:00",
"all_day": false,
"contact_id": 42,
"contact": {
"id": 42,
"name": "Anna Schmidt",
"email": "anna@beispiel.de",
"phone": "+49 30 1234567"
},
"attendees": ["anna@beispiel.de"],
"phone": "",
"color": "violet",
"status": "planned",
"status_label": "Geplant",
"reminder_minutes": 60,
"remind_attendees": true,
"source": "api",
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Teilnehmer-Adressen. |
| `phone` | `string` | nein | Telefon. |
| `color` | `string` | nein | Farbe: violet, coral, mint, gold, blue, pink, green, lilac. Werte: `violet`, `coral`, `mint`, `gold`, `blue`, `pink`, `green`, `lilac`. |
| `reminder_minutes` | `integer` | nein | Erinnerung x Minuten vorher (-1 = keine, 0 = zum Beginn, max. 40320). |
| `remind_attendees` | `boolean` | nein | Auch Teilnehmer erinnern. |
| `status` | `string` | nein | planned \| done \| cancelled \| no_show Werte: `planned`, `done`, `cancelled`, `no_show`. |
```bash
curl -X PATCH https://persolz.com/api/v1/appointments/42 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"start_at": "2026-10-14T11:00:00+02:00",
"end_at": "2026-10-14T11:30:00+02:00"
}'
```
**Antwort 200** – OK · [Termin-Objekt](#obj-appointment)
```json
{
"data": {
"id": 55,
"title": "Erstgespräch Anna Schmidt",
"description": "Kennenlernen per Video",
"location": "Zoom",
"start_at": "2026-10-14T10:00:00+02:00",
"end_at": "2026-10-14T10:30:00+02:00",
"all_day": false,
"contact_id": 42,
"contact": {
"id": 42,
"name": "Anna Schmidt",
"email": "anna@beispiel.de",
"phone": "+49 30 1234567"
},
"attendees": ["anna@beispiel.de"],
"phone": "",
"color": "violet",
"status": "planned",
"status_label": "Geplant",
"reminder_minutes": 60,
"remind_attendees": true,
"source": "api",
"created_at": "2026-10-09T14:05:00+02:00",
"updated_at": "2026-10-09T14:05:00+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | Kategorien, die der Autopilot selbst beantworten darf. |
| `ai.min_confidence` | `integer` | Mindest-Sicherheit der KI (0–100) für automatische Antworten. |
| `ai.disclosure` | `boolean` | Automatische Antworten tragen einen KI-Hinweis. |
| `ai.reply_delay_minutes` | `integer` | Wartezeit in Minuten, bevor eine Autopilot-Antwort rausgeht – so lange kannst Du sie stoppen. |
| `ai.daily_cap` | `integer` | Max. Autopilot-Antworten pro Tag für dieses Postfach (zusätzlich gilt das Limit Deines Tarifs). |
| `ai.business_hours` | `object` | Geschäftszeiten für automatische Antworten oder null (= jederzeit). |
| `ai.business_hours.days` | `array` | Wochentage (1 = Montag … 7 = Sonntag). |
| `ai.business_hours.from` | `string` | Beginn (HH:MM). |
| `ai.business_hours.to` | `string` | Ende (HH:MM). |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
```json
{
"id": 2,
"label": "Kartenherz Kundenservice",
"email": "hallo@kartenherz.com",
"display_name": "Kartenherz",
"color": "#5B3DF5",
"provider": "strato",
"provider_name": "Strato",
"imap_host": "imap.strato.de",
"imap_port": 993,
"imap_encryption": "ssl",
"imap_username": "hallo@kartenherz.com",
"smtp_account_id": 1,
"sync_enabled": true,
"status": "ok",
"status_label": "Verbunden",
"last_error": null,
"last_error_hint": null,
"last_sync_at": "2026-10-09T14:05:00+02:00",
"unread": 3,
"ai": {
"triage": true,
"mode": "approve",
"mode_label": "Mit Freigabe – KI schreibt Antworten, Du gibst sie frei",
"model": "sonnet",
"auto_categories": ["lead", "customer", "appointment"],
"min_confidence": 85,
"disclosure": true,
"reply_delay_minutes": 15,
"daily_cap": 20,
"business_hours": {
"days": [1, 2, 3, 4, 5],
"from": "08:00",
"to": "18:00"
}
},
"created_at": "2026-10-01T09:00:00+02:00"
}
```
` | Empfänger (Liste aus {email, name}). |
| `to[].email` | `string` | E-Mail-Adresse. |
| `to[].name` | `string` | Name (kann leer sein). |
| `cc` | `array` | Kopie-Empfänger (Liste aus {email, name}). |
| `subject` | `string` | Betreff. |
| `snippet` | `string` | Vorschau (Anfang des Textes). |
| `received_at` | `string (Datum/Zeit)` | Eingang (ISO 8601). |
| `is_seen` | `boolean` | Gelesen. |
| `is_flagged` | `boolean` | Markiert (Stern). |
| `is_answered` | `boolean` | Beantwortet. |
| `has_attachments` | `boolean` | Hat Anhänge. |
| `has_calendar` | `boolean` | Enthält eine Kalendereinladung (.ics). |
| `category` | `string` | KI-Kategorie: lead, customer, appointment, invoice, order, campaign_reply, partner, personal, newsletter, notification, unsubscribe, complaint, spam, other – oder null (noch nicht eingeordnet). |
| `category_label` | `string` | Kategorie in Worten. |
| `priority` | `string` | Priorität laut KI: high, normal oder low – oder null. |
| `sentiment` | `string` | Stimmung laut KI: positive, neutral oder negative – oder null. |
| `intent` | `string` | Anliegen in wenigen Worten (KI) oder null. |
| `summary` | `string` | Zusammenfassung in einem Satz (KI) oder null. |
| `needs_reply` | `boolean` | Die Mail braucht laut KI eine Antwort (null = noch nicht eingeordnet). |
| `contact_id` | `integer` | Zugeordneter Kontakt (Absender ist in Deinen Kontakten) oder null. |
| `campaign_id` | `integer · null` | Kampagne, auf die geantwortet wurde (Leser-Antwort), oder null. |
| `labels` | `array` | Eigene Labels. |
| `snoozed_until` | `string · null` | Zurückgestellt bis (ISO 8601) oder null. |
| `follow_up_at` | `string · null` | Erinnerung, falls bis dahin keine Antwort kommt (ISO 8601), oder null. |
| `replied_at` | `string · null` | Zeitpunkt Deiner Antwort aus Persolz oder null. |
| `has_ai_draft` | `boolean` | Es gibt einen KI-Entwurf zu dieser Mail (zur Freigabe oder als Vorschlag). |
```json
{
"id": 9120,
"mailbox_id": 2,
"mailbox_email": "hallo@kartenherz.com",
"folder": "Posteingang",
"folder_role": "inbox",
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"message_id": "",
"direction": "in",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"to": [
{
"email": "hallo@kartenherz.com",
"name": "Kartenherz"
}
],
"cc": [],
"subject": "Frage zu Hochzeitskarten",
"snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …",
"received_at": "2026-10-09T14:05:00+02:00",
"is_seen": false,
"is_flagged": false,
"is_answered": false,
"has_attachments": false,
"has_calendar": false,
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"sentiment": "positive",
"intent": "Angebot für 80 Hochzeitskarten",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"needs_reply": true,
"contact_id": 42,
"campaign_id": null,
"labels": ["Hochzeit"],
"snoozed_until": null,
"follow_up_at": null,
"replied_at": null,
"has_ai_draft": true
}
```
` | Empfänger (Liste aus {email, name}). |
| `to[].email` | `string` | E-Mail-Adresse. |
| `to[].name` | `string` | Name (kann leer sein). |
| `cc` | `array` | Kopie-Empfänger (Liste aus {email, name}). |
| `bcc` | `array` | Blindkopie-Empfänger (Liste aus {email, name}). |
| `subject` | `string` | Betreff. |
| `html` | `string` | Inhalt als HTML. |
| `text` | `string` | Inhalt als Text. |
| `attachment_ids` | `array` | Anhänge aus der Anhang-Cloud. |
| `mail_attachment_ids` | `array` | Mitgesendete Anhänge der Originalmail (Weiterleitung). |
| `send_at` | `string (Datum/Zeit)` | Geplanter Versand (ISO 8601) oder null. |
| `sent_at` | `string (Datum/Zeit)` | Zeitpunkt des Versands oder null. |
| `sent_message_id` | `string` | Message-ID der gesendeten Mail oder null. |
| `error` | `string · null` | Fehler beim Versand oder null. |
| `ai` | `string · null` | KI-Angaben (nur bei KI-Entwürfen, sonst null). |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string (Datum/Zeit)` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
```json
{
"id": 5502,
"mailbox_id": 2,
"kind": "reply",
"kind_label": "Antwort",
"status": "sent",
"status_label": "Gesendet",
"source": "user",
"reply_to_message_id": 9120,
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"to": [
{
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
}
],
"cc": [],
"bcc": [],
"subject": "Re: Frage zu Hochzeitskarten",
"html": "Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": "2026-10-09T14:21:00+02:00",
"sent_at": "2026-10-09T14:21:04+02:00",
"sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>",
"error": null,
"ai": null,
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00"
}
```
` | Ordner des Postfachs. |
| `data.folders[].id` | `integer` | Eindeutige ID. |
| `data.folders[].name` | `string` | Ordnername auf dem Server. |
| `data.folders[].display_name` | `string` | Ordnername in Worten. |
| `data.folders[].role` | `string` | Rolle: inbox, sent, drafts, archive, trash, junk, all oder null. |
| `data.folders[].is_synced` | `boolean` | Der Ordner wird zwischengespeichert (Liste, Suche, Ansichten). |
| `data.folders[].unread` | `integer` | Ungelesene Mails im Zwischenspeicher. |
| `data.folders[].total` | `integer` | Mails im Zwischenspeicher. |
```json
{
"data": {
"id": 2,
"label": "Kartenherz Kundenservice",
"email": "hallo@kartenherz.com",
"display_name": "Kartenherz",
"color": "#5B3DF5",
"provider": "strato",
"provider_name": "Strato",
"imap_host": "imap.strato.de",
"imap_port": 993,
"imap_encryption": "ssl",
"imap_username": "hallo@kartenherz.com",
"smtp_account_id": 1,
"sync_enabled": true,
"status": "ok",
"status_label": "Verbunden",
"last_error": null,
"last_error_hint": null,
"last_sync_at": "2026-10-09T14:05:00+02:00",
"unread": 3,
"ai": {
"triage": true,
"mode": "approve",
"mode_label": "Mit Freigabe – KI schreibt Antworten, Du gibst sie frei",
"model": "sonnet",
"auto_categories": ["lead", "customer", "appointment"],
"min_confidence": 85,
"disclosure": true,
"reply_delay_minutes": 15,
"daily_cap": 20,
"business_hours": {
"days": [1, 2, 3, 4, 5],
"from": "08:00",
"to": "18:00"
}
},
"created_at": "2026-10-01T09:00:00+02:00",
"folders": [
{
"id": 11,
"name": "INBOX",
"display_name": "Posteingang",
"role": "inbox",
"is_synced": true,
"unread": 3,
"total": 214
},
{
"id": 12,
"name": "Gesendet",
"display_name": "Gesendet",
"role": "sent",
"is_synced": true,
"unread": 0,
"total": 96
}
]
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
",
"direction": "in",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"to": [
{
"email": "hallo@kartenherz.com",
"name": "Kartenherz"
}
],
"cc": [],
"subject": "Frage zu Hochzeitskarten",
"snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …",
"received_at": "2026-10-09T14:05:00+02:00",
"is_seen": false,
"is_flagged": false,
"is_answered": false,
"has_attachments": false,
"has_calendar": false,
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"sentiment": "positive",
"intent": "Angebot für 80 Hochzeitskarten",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"needs_reply": true,
"contact_id": 42,
"campaign_id": null,
"labels": ["Hochzeit"],
"snoozed_until": null,
"follow_up_at": null,
"replied_at": null,
"has_ai_draft": true
}
],
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e",
"pagination": {
"page": 1,
"per_page": 25,
"total": 1,
"pages": 1
}
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 429 `rate_limited`.
` | Vorgeschlagene nächste Schritte. |
| `data.ai.actions[].key` | `string` | Schlüssel der Aktion (z. B. reply, create_contact, book_appointment). |
| `data.ai.actions[].label` | `string` | Aktion in Worten. |
| `data.ai.risk_flags` | `array` | Risiken: legal, money, medical, threat, prompt_injection, personal_data, unclear. |
| `data.ai.risk_flag_labels` | `array` | Risiken in Worten. |
| `data.ai.language` | `string` | Sprache der Mail (z. B. de, en) oder null. |
| `data.ai.confidence` | `integer` | Sicherheit der Einordnung (0–100) oder null. |
| `data.attachments` | `array` | Anhänge (nur Metadaten). |
| `data.attachments[].id` | `integer` | Eindeutige ID. |
| `data.attachments[].filename` | `string` | Dateiname. |
| `data.attachments[].mime` | `string` | MIME-Typ. |
| `data.attachments[].size` | `integer` | Größe in Bytes. |
| `data.attachments[].is_inline` | `boolean` | Eingebettetes Bild (cid:). |
| `data.attachments[].content_id` | `integer · null` | Content-ID eingebetteter Bilder oder null. |
| `data.thread` | `array` | Verlauf: alle Mails dieser Unterhaltung (ältere zuerst). |
| `data.thread[].id` | `integer` | Eindeutige ID. |
| `data.thread[].direction` | `string` | in (empfangen) oder out (gesendet). |
| `data.thread[].subject` | `string` | Betreff. |
| `data.thread[].from` | `object` | Absender. |
| `data.thread[].from.email` | `string` | E-Mail-Adresse des Absenders. |
| `data.thread[].from.name` | `string` | Name des Absenders (kann leer sein). |
| `data.thread[].received_at` | `string (Datum/Zeit)` | Eingang (ISO 8601). |
| `data.thread[].snippet` | `string` | Vorschau (Anfang des Textes). |
| `data.drafts` | `array` | Entwürfe und ausgehende Mails zu dieser Mail (neueste zuerst). |
| `data.drafts[].id` | `integer` | Eindeutige ID. |
| `data.drafts[].kind` | `string` | reply, reply_all, forward, new oder auto. |
| `data.drafts[].status` | `string` | draft, pending, scheduled, sending, sent, failed, rejected oder cancelled. |
| `data.drafts[].source` | `string` | user (von Dir), ai (KI) oder rule (Regel). |
| `data.drafts[].subject` | `string` | Betreff. |
| `data.drafts[].send_at` | `string · null` | Geplanter Versand oder null. |
| `data.body` | `object` | Inhalt (nur mit include_body=true). |
| `data.body.text` | `string` | Inhalt als Text. |
| `data.body.html` | `string` | Inhalt als bereinigtes HTML (ohne Skripte; externe Bilder blockiert, solange images nicht true ist). |
| `data.body.has_remote_images` | `boolean` | Die Mail lädt externe Bilder (Tracking möglich). |
| `data.body.missing` | `boolean` | Der Inhalt ist auf dem Server nicht mehr vorhanden. |
| `data.body.error` | `string · null` | Fehler beim Nachladen vom Server oder null. |
```json
{
"data": {
"id": 9120,
"mailbox_id": 2,
"mailbox_email": "hallo@kartenherz.com",
"folder": "Posteingang",
"folder_role": "inbox",
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"message_id": "",
"direction": "in",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"to": [
{
"email": "hallo@kartenherz.com",
"name": "Kartenherz"
}
],
"cc": [],
"subject": "Frage zu Hochzeitskarten",
"snippet": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …",
"received_at": "2026-10-09T14:05:00+02:00",
"is_seen": false,
"is_flagged": false,
"is_answered": false,
"has_attachments": false,
"has_calendar": false,
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"sentiment": "positive",
"intent": "Angebot für 80 Hochzeitskarten",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"needs_reply": true,
"contact_id": 42,
"campaign_id": null,
"labels": ["Hochzeit"],
"snoozed_until": null,
"follow_up_at": null,
"replied_at": null,
"ai": {
"status": "done",
"actions": [
{
"key": "reply",
"label": "Antwort entwerfen"
},
{
"key": "create_contact",
"label": "Kontakt anlegen"
}
],
"risk_flags": [],
"risk_flag_labels": [],
"language": "de",
"confidence": 92
},
"attachments": [
{
"id": 301,
"filename": "Wunschmotiv.jpg",
"mime": "image/jpeg",
"size": 184220,
"is_inline": false,
"content_id": null
}
],
"thread": [
{
"id": 9120,
"direction": "in",
"subject": "Frage zu Hochzeitskarten",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"received_at": "2026-10-09T14:05:00+02:00",
"snippet": "Hallo, wir heiraten im Mai …"
}
],
"drafts": [
{
"id": 5502,
"kind": "reply",
"status": "pending",
"source": "ai",
"subject": "Re: Frage zu Hochzeitskarten",
"send_at": null
}
],
"body": {
"text": "Hallo,\n\nwir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung …",
"html": "Hallo,
wir heiraten im Mai …
",
"has_remote_images": false,
"missing": false,
"error": null
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
` | ja | IDs der Mails (max. 500). |
| `action` | `string` | ja | Aktion. Werte: `read`, `unread`, `flag`, `unflag`, `archive`, `trash`, `spam`, `notspam`, `move`, `restore`, `delete_forever`, `snooze`, `unsnooze`, `follow_up`, `clear_follow_up`, `label`, `set_category`. |
| `params` | `object` | nein | Parameter der Aktion (siehe Beschreibung). |
```bash
curl -X POST https://persolz.com/api/v1/inbox/messages/actions \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"ids": [9120, 9121],
"action": "snooze",
"params": {
"until": "2026-10-12T09:00:00+02:00"
}
}'
```
**Antwort 200** – OK
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.action` | `string` | Ausgeführte Aktion. |
| `data.affected` | `integer` | Geänderte Mails. |
| `data.ids` | `array` | IDs der bearbeiteten Mails. |
| `data.not_found` | `array` | IDs, die es (für Dich) nicht gibt. |
| `data.warning` | `string · null` | Hinweis, wenn der Mailserver die Änderung nicht übernommen hat (der nächste Abruf gleicht ab), sonst null. |
```json
{
"data": {
"action": "snooze",
"affected": 2,
"ids": [9120, 9121],
"not_found": [],
"warning": null
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Anhänge aus der Anhang-Cloud (GET /attachments). |
| `send_at` | `string` | nein | Später senden (ISO 8601, mind. 1 Minute, max. 1 Jahr in der Zukunft). Leer = sofort. |
| `to` | `string|array` | nein | Empfänger: E-Mail, kommagetrennte E-Mails („Name <mail@…>“ erlaubt) oder Liste aus E-Mails bzw. Objekten {email, name}. |
| `cc` | `string|array` | nein | Kopie (wie to). |
| `bcc` | `string|array` | nein | Blindkopie (wie to). |
| `subject` | `string` | nein | Betreff (Standard: „Re: <Betreff>“). |
| `reply_all` | `boolean` | nein | Allen antworten (To + Cc der Mail, ohne Deine eigenen Adressen). |
| `quote` | `boolean` | nein | Original zitieren (Standard true). |
```bash
curl -X POST https://persolz.com/api/v1/inbox/messages/42/reply \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"html": "Hallo Anna,
herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € und sind in 10 Tagen bei Dir.
Viele Grüße
"
}'
```
**Antwort 201** – Gesendet bzw. geplant · [Entwurfs-Objekt (Posteingang)](#obj-inbox-draft)
```json
{
"data": {
"id": 5502,
"mailbox_id": 2,
"kind": "reply",
"kind_label": "Antwort",
"status": "sent",
"status_label": "Gesendet",
"source": "user",
"reply_to_message_id": 9120,
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"to": [
{
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
}
],
"cc": [],
"bcc": [],
"subject": "Re: Frage zu Hochzeitskarten",
"html": "Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": "2026-10-09T14:21:00+02:00",
"sent_at": "2026-10-09T14:21:04+02:00",
"sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>",
"error": null,
"ai": null,
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
Hallo Anna,
herzlichen Glückwunsch! …
",
"text": "Hallo Anna,\n\nherzlichen Glückwunsch! …",
"confidence": 88,
"risk_flags": [],
"risk_flag_labels": [],
"needs_human": false,
"reason": "Preis und Lieferzeit stehen im Wissen für die KI.",
"language": "de",
"form_of_address": "du",
"slots": [],
"model": "claude-sonnet-5-5",
"cost_eur": 0.0041,
"cached": false,
"draft_id": 5502
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
` | nein | Anhänge aus der Anhang-Cloud (GET /attachments). |
| `send_at` | `string` | nein | Später senden (ISO 8601, mind. 1 Minute, max. 1 Jahr in der Zukunft). Leer = sofort. |
| `mail_attachment_ids` | `array` | nein | forward: Anhänge der Originalmail (Standard: alle). |
| `quote` | `boolean` | nein | reply/forward: Original zitieren (Standard true). |
| `send` | `boolean` | nein | false = nur als Entwurf speichern (Standard true). |
```bash
curl -X POST https://persolz.com/api/v1/inbox/drafts \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"mailbox_id": 2,
"to": ["anna@beispiel.de"],
"subject": "Dein Angebot für Hochzeitskarten",
"html": "Hallo Anna,
anbei Dein Angebot …
",
"attachment_ids": [9],
"send_at": "2026-10-10T09:00:00+02:00"
}'
```
**Antwort 201** – Angelegt (gesendet, geplant oder Entwurf) · [Entwurfs-Objekt (Posteingang)](#obj-inbox-draft)
```json
{
"data": {
"id": 5502,
"mailbox_id": 2,
"kind": "new",
"kind_label": "Neue Mail",
"status": "scheduled",
"status_label": "Geplant",
"source": "user",
"reply_to_message_id": null,
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"to": [
{
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
}
],
"cc": [],
"bcc": [],
"subject": "Dein Angebot für Hochzeitskarten",
"html": "Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [9],
"mail_attachment_ids": [],
"send_at": "2026-10-10T09:00:00+02:00",
"sent_at": null,
"sent_message_id": null,
"error": null,
"ai": null,
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": "2026-10-09T14:21:00+02:00",
"sent_at": "2026-10-09T14:21:04+02:00",
"sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>",
"error": null,
"ai": null,
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 429 `rate_limited`.
Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": "2026-10-09T14:21:00+02:00",
"sent_at": "2026-10-09T14:21:04+02:00",
"sent_message_id": "<6f1c0d9a2b7e4c1f@kartenherz.com>",
"error": null,
"ai": null,
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": null,
"sent_at": null,
"sent_message_id": null,
"error": null,
"ai": null,
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 429 `rate_limited`.
Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": null,
"sent_at": null,
"sent_message_id": null,
"error": null,
"ai": {
"model": "claude-sonnet-5-5",
"confidence": 88,
"reason": "Preis und Lieferzeit stehen im Wissen für die KI.",
"flags": [],
"flag_labels": [],
"rating": null,
"edited": false
},
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00",
"reasons": [],
"message": {
"id": 9120,
"subject": "Frage zu Hochzeitskarten",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"received_at": "2026-10-09T14:05:00+02:00",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"excerpt": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung. Was kostet das und wie lange dauert die Lieferung?"
}
}
],
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e",
"pagination": {
"page": 1,
"per_page": 25,
"total": 1,
"pages": 1
}
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 429 `rate_limited`.
` | nein | Anhänge aus der Anhang-Cloud. |
```bash
curl -X POST https://persolz.com/api/v1/inbox/approvals/42/approve \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-H "Content-Type: application/json" \
-d '{
"html": "Hallo Anna,
herzlichen Glückwunsch! Ich schicke Dir gern Muster per Post …
"
}'
```
**Antwort 200** – OK · [Entwurfs-Objekt (Posteingang)](#obj-inbox-draft)
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.reasons` | `array` | Gründe, warum der Autopilot nicht selbst gesendet hat. |
| `data.message` | `object` | Die Originalmail (Auszug). |
| `data.message.id` | `integer` | Eindeutige ID. |
| `data.message.subject` | `string` | Betreff. |
| `data.message.from` | `object` | Absender. |
| `data.message.from.email` | `string` | E-Mail-Adresse des Absenders. |
| `data.message.from.name` | `string` | Name des Absenders (kann leer sein). |
| `data.message.received_at` | `string (Datum/Zeit)` | Eingang (ISO 8601). |
| `data.message.summary` | `string` | Zusammenfassung in einem Satz (KI) oder null. |
| `data.message.category` | `string` | KI-Kategorie: lead, customer, appointment, invoice, order, campaign_reply, partner, personal, newsletter, notification, unsubscribe, complaint, spam, other – oder null (noch nicht eingeordnet). |
| `data.message.category_label` | `string` | Kategorie in Worten. |
| `data.message.priority` | `string` | Priorität laut KI: high, normal oder low – oder null. |
| `data.message.excerpt` | `string` | Auszug aus dem Text der Originalmail. |
```json
{
"data": {
"id": 5502,
"mailbox_id": 2,
"kind": "reply",
"kind_label": "Antwort",
"status": "sent",
"status_label": "Gesendet",
"source": "ai",
"reply_to_message_id": 9120,
"thread_key": "3f1c9a7e5b2d4c8f9e0a1d2b3c4d5e6f70819a2b",
"to": [
{
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
}
],
"cc": [],
"bcc": [],
"subject": "Re: Frage zu Hochzeitskarten",
"html": "Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": "2026-10-09T14:21:00+02:00",
"sent_at": "2026-10-09T14:21:04+02:00",
"sent_message_id": null,
"error": null,
"ai": {
"model": "claude-sonnet-5-5",
"confidence": 88,
"reason": "Preis und Lieferzeit stehen im Wissen für die KI.",
"flags": [],
"flag_labels": [],
"rating": null,
"edited": true
},
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00",
"reasons": [],
"message": {
"id": 9120,
"subject": "Frage zu Hochzeitskarten",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"received_at": "2026-10-09T14:05:00+02:00",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"excerpt": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung. Was kostet das und wie lange dauert die Lieferung?"
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
Hallo Anna,
wie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …
",
"text": "Hallo Anna,\n\nwie schön, herzlichen Glückwunsch! 80 Karten mit Goldprägung kosten 236 € …",
"attachment_ids": [],
"mail_attachment_ids": [],
"send_at": null,
"sent_at": null,
"sent_message_id": null,
"error": null,
"ai": {
"model": "claude-sonnet-5-5",
"confidence": 88,
"reason": "Preis und Lieferzeit stehen im Wissen für die KI.",
"flags": [],
"flag_labels": [],
"rating": null,
"edited": false
},
"created_at": "2026-10-09T14:06:10+02:00",
"updated_at": "2026-10-09T14:06:10+02:00",
"reasons": [],
"message": {
"id": 9120,
"subject": "Frage zu Hochzeitskarten",
"from": {
"email": "anna@beispiel.de",
"name": "Anna Schmidt"
},
"received_at": "2026-10-09T14:05:00+02:00",
"summary": "Anna möchte 80 Einladungskarten für ihre Hochzeit im Mai und fragt nach Preis und Lieferzeit.",
"category": "lead",
"category_label": "Leads & Anfragen",
"priority": "high",
"excerpt": "Hallo, wir heiraten im Mai und suchen 80 Einladungskarten mit Goldprägung. Was kostet das und wie lange dauert die Lieferung?"
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `validation_error`, 429 `rate_limited`.
` | KI-Entwürfe pro Tag. |
| `data.ai.per_day[].date` | `string (Datum)` | Tag. |
| `data.ai.per_day[].drafts` | `integer` | KI-Entwürfe. |
| `data.ai.per_day[].auto` | `integer` | Davon Autopilot. |
```json
{
"data": {
"period": {
"days": 30,
"from": "2026-09-10",
"to": "2026-10-09"
},
"mailboxes": {
"total": 2,
"ok": 2,
"error": 0,
"paused": 0,
"last_sync_at": "2026-10-09T14:05:00+02:00"
},
"views": {
"focus": 7,
"focus_unread": 3,
"all": 214,
"unread": 5,
"flagged": 4,
"waiting": 2,
"snoozed": 1,
"approvals": 2,
"scheduled": 1,
"failed": 0,
"drafts": 1,
"sent": 96,
"archive": 812,
"trash": 12,
"spam": 0
},
"categories": {
"lead": {
"label": "Leads & Anfragen",
"total": 18,
"unread": 2
},
"campaign_reply": {
"label": "Leser-Antworten",
"total": 9,
"unread": 1
}
},
"approvals": 2,
"badge": 5,
"mails": {
"received": 320,
"sent": 104,
"replied": 87
},
"ai": {
"drafts": 41,
"approved": 33,
"edited": 9,
"rejected": 3,
"auto_sent": 12,
"auto_planned": 1,
"pending": 2,
"thumbs_up": 6,
"thumbs_down": 1,
"approval_rate": 0.9167,
"edit_rate": 0.2727,
"avg_confidence": 84,
"triaged": 298,
"minutes_saved": 462,
"hours_saved": 7.7,
"hours_saved_label": "ca. 7,7 Stunden",
"per_day": [
{
"date": "2026-10-08",
"drafts": 3,
"auto": 1
},
{
"date": "2026-10-09",
"drafts": 2,
"auto": 0
}
]
}
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 429 `rate_limited`.
` | Vorschläge (z. B. 8 Betreffzeilen bei subject_ideas). |
| `data.cost_eur` | `number` | Kosten dieser KI-Anfrage in Euro (wird vom KI-Guthaben abgezogen). |
| `data.remaining_eur` | `number` | Verbleibendes KI-Guthaben in Euro. |
| `data.model` | `string` | Verwendetes KI-Modell. |
| `data.provider` | `string` | KI-Anbieter: anthropic oder openai. |
| `data.fallback_used` | `boolean` | Der Ersatz-Anbieter hat geantwortet, weil der Haupt-Anbieter nicht erreichbar war. |
```json
{
"data": {
"action": "subject_ideas",
"text": "Nur 12 Plätze: Dein Herbst-Workshop\n…",
"html": null,
"data": {
"ideas": ["Nur 12 Plätze: Dein Herbst-Workshop", "…"]
},
"cost_eur": 0.0012,
"remaining_eur": 7.68,
"model": "claude-haiku-5-5",
"provider": "anthropic",
"fallback_used": false
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`, 503 `service_unavailable`.
` | Abonnierte Ereignisse (["*"] = alle). |
| `is_active` | `boolean` | Webhook ist aktiv. |
| `failure_count` | `integer` | Fehlschläge in Folge – nach 20 wird der Webhook pausiert. |
| `last_status` | `integer` | Letzter HTTP-Status Deines Endpunkts oder null. |
| `last_error` | `string · null` | Letzte Fehlermeldung oder null. |
| `last_called_at` | `string (Datum/Zeit)` | Letzter Aufruf oder null. |
| `disabled_at` | `string · null` | Zeitpunkt der automatischen Pausierung oder null. |
| `created_at` | `string (Datum/Zeit)` | Zeitpunkt der Anlage (ISO 8601). |
| `updated_at` | `string · null` | Zeitpunkt der letzten Änderung (ISO 8601) oder null. |
| `secret_hint` | `string` | Anfang des Secrets zum Wiedererkennen. |
```json
{
"id": 4,
"url": "https://kartenherz.com/hooks/persolz",
"description": "Shop-Synchronisation",
"events": ["contact.created", "contact.unsubscribed"],
"is_active": true,
"failure_count": 0,
"last_status": 200,
"last_error": null,
"last_called_at": "2026-10-09T14:05:01+02:00",
"disabled_at": null,
"created_at": "2026-10-01T09:00:00+02:00",
"updated_at": null,
"secret_hint": "whsec_3f9a…"
}
```
` | nein | Ereignisse oder ["*"] für alle: contact.created, contact.updated, contact.deleted, contact.unsubscribed, list.joined, email.opened, email.clicked, campaign.sent, soap.enrolled, soap.completed, appointment.created, appointment.updated, inbox.received, inbox.replied, inbox.approval_needed, inbox.auto_replied |
| `description` | `string` | nein | Beschreibung. |
| `is_active` | `boolean` | nein | Aktiv (Reaktivieren setzt den Fehlerzähler zurück). |
```bash
curl -X POST https://persolz.com/api/v1/webhooks \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"url": "https://kartenherz.com/hooks/persolz",
"events": ["contact.created", "contact.unsubscribed"],
"description": "Shop-Synchronisation"
}'
```
**Antwort 201** – Angelegt · [Webhook-Objekt](#obj-webhook)
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.secret` | `string` | Signatur-Secret zum Prüfen der Webhooks – wird nur beim Anlegen bzw. Erneuern ausgegeben. |
```json
{
"data": {
"id": 4,
"url": "https://kartenherz.com/hooks/persolz",
"description": "Shop-Synchronisation",
"events": ["contact.created", "contact.unsubscribed"],
"is_active": true,
"failure_count": 0,
"last_status": 200,
"last_error": null,
"last_called_at": "2026-10-09T14:05:01+02:00",
"disabled_at": null,
"created_at": "2026-10-01T09:00:00+02:00",
"updated_at": null,
"secret_hint": "whsec_3f9a…",
"secret": "whsec_3f9a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 402 `limit_reached`, 403 `forbidden`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Ereignisse oder ["*"] für alle: contact.created, contact.updated, contact.deleted, contact.unsubscribed, list.joined, email.opened, email.clicked, campaign.sent, soap.enrolled, soap.completed, appointment.created, appointment.updated, inbox.received, inbox.replied, inbox.approval_needed, inbox.auto_replied |
| `description` | `string` | nein | Beschreibung. |
| `is_active` | `boolean` | nein | Aktiv (Reaktivieren setzt den Fehlerzähler zurück). |
| `rotate_secret` | `boolean` | nein | Neues Signatur-Secret erzeugen. |
```bash
curl -X PATCH https://persolz.com/api/v1/webhooks/42 \
-H "Authorization: Bearer pz_live_DEIN_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{
"events": ["*"],
"is_active": true
}'
```
**Antwort 200** – OK · [Webhook-Objekt](#obj-webhook)
```json
{
"data": {
"id": 4,
"url": "https://kartenherz.com/hooks/persolz",
"description": "Shop-Synchronisation",
"events": ["contact.created", "contact.unsubscribed"],
"is_active": true,
"failure_count": 0,
"last_status": 200,
"last_error": null,
"last_called_at": "2026-10-09T14:05:01+02:00",
"disabled_at": null,
"created_at": "2026-10-01T09:00:00+02:00",
"updated_at": null,
"secret_hint": "whsec_3f9a…"
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 401 `unauthorized`, 402 `plan_required`, 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.
` | nein | Tags (Array oder kommagetrennt, max. 10). |
| `website` | `string` | nein | Honeypot – muss leer bleiben. |
| `success_url` | `string` | nein | Weiterleitung nach Erfolg (http/https). Hat die Liste „Erlaubte Weiterleitungs-Domains“, werden andere Hosts ignoriert (→ Persolz-Danke-Seite). |
| `error_url` | `string` | nein | Weiterleitung bei Fehlern (?error=… wird angehängt) – nur bei gültigem Listen-Token und erlaubter Domain. |
```bash
curl -X POST https://persolz.com/api/v1/subscribe/9f2c4e6a8b0d1f3e5a7c9e1b3d5f7a9c \
-H "Content-Type: application/json" \
-d '{
"email": "anna@beispiel.de",
"first_name": "Anna",
"tags": ["funnel"],
"website": ""
}'
```
**Antwort 201** – Angemeldet (200 = bereits bekannt / aktualisiert)
| Feld | Typ | Beschreibung |
|---|---|---|
| `data.state` | `string` | subscribed (angemeldet) oder pending (Bestätigung per E-Mail nötig). |
| `data.double_optin` | `boolean` | Die Liste verlangt eine Bestätigung per E-Mail. |
| `data.message` | `string` | Verständliche Meldung auf Deutsch. |
| `data.redirect_url` | `string · null` | Weiterleitungsziel der Liste nach der Anmeldung oder null. |
```json
{
"data": {
"state": "pending",
"double_optin": true,
"message": "Fast geschafft! Wir haben Dir eine E-Mail geschickt – bitte bestätige Deine Anmeldung über den Link darin.",
"redirect_url": null
},
"meta": {
"request_id": "req_2b9f1c7d0e3a4b5c6d7e"
}
}
```
Mögliche Fehler: 403 `forbidden`, 404 `not_found`, 422 `validation_error`, 429 `rate_limited`.