Briefe – API-Referenz

Brief per Post versenden

POST/api/v1/debts/{id}/letters

Kostenpflichtig: Druck und Versand über Briefdiener (Abo-Kontingent oder eigenes Briefdiener-Konto). Mahnstufen nutzen den Standardtext; custom braucht content. Unbedingt Idempotency-Key senden, damit Wiederholungen keinen zweiten Brief auslösen. Fehler: 402 quota_exceeded/not_available, 422 missing_address.

Berechtigung: letters:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · LetterSend

kind"reminder1" | "reminder2" | "reminder3" | "custom"Pflicht
registeredboolean
subjectstring
max. 300 Zeichen
contentstring
Pflicht bei kind=custom; sonst Standardtext der Mahnstufe
max. 20000 Zeichen

Antwort 201 · Letter

idstringPflicht
object"letter"Pflicht
debtIdstringPflicht
contactIdstringPflicht
contactNamestringPflicht
kind"reminder1" | "reminder2" | "reminder3" | "custom"Pflicht
subjectstringPflicht
status"sending" | "sent" | "failed"Pflicht
deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullPflicht
mode"own" | "central"Pflicht
eigenes Briefdiener-Konto oder Kontingent des Abos
trigger"manual" | "auto"Pflicht
registeredbooleanPflicht
Einschreiben
trackingRefstring | nullPflicht
trackingUrlstring | nullPflicht
pageCountinteger | nullPflicht
-9007199254740991–9007199254740991
priceEurostring | nullPflicht
errorstring | nullPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
sentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 402, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/letters' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "reminder1",
  "registered": false,
  "subject": "string",
  "content": "string"
}'

Antwort 201

{
  "id": "string",
  "object": "letter",
  "debtId": "string",
  "contactId": "string",
  "contactName": "string",
  "kind": "reminder1",
  "subject": "string",
  "status": "sending",
  "deliveryStatus": "pending",
  "mode": "own",
  "trigger": "manual",
  "registered": false,
  "trackingRef": "string",
  "trackingUrl": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "error": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "sentAt": "2026-11-01T09:30:00.000Z"
}

Brief-Vorschau

POST/api/v1/debts/{id}/letters/preview

Liefert Text, Anschriften, Seitenzahl/Preis (falls verfügbar) und Hinderungsgründe – versendet nichts.

Berechtigung: letters:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Body (JSON) · LetterSend

kind"reminder1" | "reminder2" | "reminder3" | "custom"Pflicht
registeredboolean
subjectstring
max. 300 Zeichen
contentstring
Pflicht bei kind=custom; sonst Standardtext der Mahnstufe
max. 20000 Zeichen

Antwort 200 · LetterPreview

subjectstringPflicht
salutationstringPflicht
contentstringPflicht
closingstringPflicht
signatureNamestringPflicht
senderobjectPflicht
- namestringPflicht
- companystring
- addressstringPflicht
recipientobjectPflicht
- namestringPflicht
- companystring
- addressstringPflicht
referencestringPflicht
pageCountinteger | nullPflicht
-9007199254740991–9007199254740991
priceEurostring | nullPflicht
quotaobjectPflicht
- mode"own" | "central" | "none"Pflicht
- usedintegerPflicht
  -9007199254740991–9007199254740991
- limitinteger | nullPflicht
  -9007199254740991–9007199254740991
- periodStartstring | nullPflicht
- periodEndstring | nullPflicht
problemsArray<string>Pflicht
Gründe, warum der Brief so nicht versendet werden kann

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/debts/ID/letters/preview' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "reminder1",
  "registered": false,
  "subject": "string",
  "content": "string"
}'

Antwort 200

{
  "subject": "string",
  "salutation": "string",
  "content": "string",
  "closing": "string",
  "signatureName": "string",
  "sender": {
    "name": "string",
    "company": "string",
    "address": "string"
  },
  "recipient": {
    "name": "string",
    "company": "string",
    "address": "string"
  },
  "reference": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "quota": {
    "mode": "own",
    "used": 0,
    "limit": 0,
    "periodStart": "string",
    "periodEnd": "string"
  },
  "problems": [
    "string"
  ]
}

Briefe auflisten

GET/api/v1/letters

Versendete Briefe mit Versand- und Zustellstatus, neueste zuerst.

Berechtigung: letters:read

Query-Parameter

debtIdstring
max. 128 Zeichen
contactIdstring
max. 128 Zeichen
limitinteger
Anzahl Einträge (1–100)
1–100 · Standard: 25
cursorstring
`nextCursor` der vorherigen Seite
max. 500 Zeichen

Antwort 200

object"list"Pflicht
dataArray<Letter>Pflicht
- idstringPflicht
- object"letter"Pflicht
- debtIdstringPflicht
- contactIdstringPflicht
- contactNamestringPflicht
- kind"reminder1" | "reminder2" | "reminder3" | "custom"Pflicht
- subjectstringPflicht
- status"sending" | "sent" | "failed"Pflicht
- deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullPflicht
- mode"own" | "central"Pflicht
  eigenes Briefdiener-Konto oder Kontingent des Abos
- trigger"manual" | "auto"Pflicht
- registeredbooleanPflicht
  Einschreiben
- trackingRefstring | nullPflicht
- trackingUrlstring | nullPflicht
- pageCountinteger | nullPflicht
  -9007199254740991–9007199254740991
- priceEurostring | nullPflicht
- errorstring | nullPflicht
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- sentAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
hasMorebooleanPflicht
nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/letters' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "letter",
      "debtId": "string",
      "contactId": "string",
      "contactName": "string",
      "kind": "reminder1",
      "subject": "string",
      "status": "sending",
      "deliveryStatus": "pending",
      "mode": "own",
      "trigger": "manual",
      "registered": false,
      "trackingRef": "string",
      "trackingUrl": "string",
      "pageCount": 0,
      "priceEuro": "string",
      "error": "string",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "sentAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Brief und Zustellstatus abrufen

GET/api/v1/letters/{id}

Berechtigung: letters:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · Letter

idstringPflicht
object"letter"Pflicht
debtIdstringPflicht
contactIdstringPflicht
contactNamestringPflicht
kind"reminder1" | "reminder2" | "reminder3" | "custom"Pflicht
subjectstringPflicht
status"sending" | "sent" | "failed"Pflicht
deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullPflicht
mode"own" | "central"Pflicht
eigenes Briefdiener-Konto oder Kontingent des Abos
trigger"manual" | "auto"Pflicht
registeredbooleanPflicht
Einschreiben
trackingRefstring | nullPflicht
trackingUrlstring | nullPflicht
pageCountinteger | nullPflicht
-9007199254740991–9007199254740991
priceEurostring | nullPflicht
errorstring | nullPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
sentAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/letters/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "letter",
  "debtId": "string",
  "contactId": "string",
  "contactName": "string",
  "kind": "reminder1",
  "subject": "string",
  "status": "sending",
  "deliveryStatus": "pending",
  "mode": "own",
  "trigger": "manual",
  "registered": false,
  "trackingRef": "string",
  "trackingUrl": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "error": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "sentAt": "2026-11-01T09:30:00.000Z"
}

Brief-Kontingent abrufen

GET/api/v1/letters/quota

central = Kontingent des Abos (used/limit je Monat), own = eigenes Briefdiener-Konto, none = nicht verfügbar (reason).

Berechtigung: letters:read

Antwort 200 · LetterQuota

mode"own" | "central" | "none"Pflicht
usedintegerPflicht
-9007199254740991–9007199254740991
limitinteger | nullPflicht
-9007199254740991–9007199254740991
periodStartstring | nullPflicht
periodEndstring | nullPflicht
reasonstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/letters/quota' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "mode": "own",
  "used": 0,
  "limit": 0,
  "periodStart": "string",
  "periodEnd": "string",
  "reason": "string"
}