REST-API Dokumentation

Automatisieren Sie Ihren Briefversand mit unserer dokumentierten REST-API. Einzelbriefe, Serienbriefe und Statusabfragen: alles per HTTP.

Inhaltsverzeichnis

Übersicht
Authentifizierung
Endpunkte
Code-Beispiele
Rate-Limits
Fehler-Codes

Übersicht

Die PDFpost.de API ist eine RESTful JSON-API. Alle Endpunkte sind unter der Basis-URL https://pdfpost.de/api/v1/ erreichbar.

Die API ermöglicht:

Briefe versenden (Einzelbrief und Serienbrief)
Status von Briefen abfragen
Guthabenstand prüfen
Versandhistorie abrufen

Authentifizierung

Alle API-Anfragen erfordern einen gültigen API-Key. Diesen erstellen Sie in Ihrem Kunden-Dashboard unter „API-Keys".

Senden Sie den API-Key als Bearer-Token im Authorization-Header:

Authorization: Bearer Ihr-API-Key

API-Keys sind an Ihr Konto gebunden und können jederzeit widerrufen werden. Geben Sie Ihren API-Key niemals an Dritte weiter.

Endpunkte

POST /api/v1/letters

Brief versenden

Sendet einen einzelnen Brief. Das PDF wird als Multipart-Upload übertragen.

Parameter	Typ	Pflicht	Beschreibung
`document`	file	Ja	PDF-Datei (DIN A4, max. 50 MB)
`color`	boolean	Nein	Farbdruck (Standard: false)
`duplex`	boolean	Nein	Beidseitiger Druck (Standard: false)
`letter_type`	string	Nein	standard, einschreiben_einwurf, einschreiben, einschreiben_rueckschein
`recipient_name`	string	Nein	Überschreibt erkannte Empfängeradresse
`recipient_street`	string	Nein	Straße und Hausnummer
`recipient_zip`	string	Nein	PLZ
`recipient_city`	string	Nein	Ort

GET /api/v1/letters

Briefe auflisten

Gibt eine paginierte Liste aller versendeten Briefe zurück.

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`per_page`	integer	Einträge pro Seite (max. 100)
`status`	string	Filter: queued, processing, sent, delivered, failed

GET /api/v1/letters/{id}

Brief-Status abfragen

Gibt Details und aktuellen Status eines einzelnen Briefs zurück.

GET /api/v1/balance

Guthabenstand abfragen

Gibt den aktuellen Guthabenstand in Cent zurück.

Code-Beispiele

curl

# Brief versenden
curl -X POST https://pdfpost.de/api/v1/letters \
  -H "Authorization: Bearer IHR_API_KEY" \
  -F document=@rechnung.pdf \
  -F color=false \
  -F duplex=false

PHP

// Brief versenden mit PHP (cURL)
$ch = curl_init('https://pdfpost.de/api/v1/letters');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => [
        'document' => new CURLFile('/pfad/zur/rechnung.pdf'),
        'color'    => 'false',
        'duplex'   => 'false',
    ],
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
// $data['id'], $data['status']

Python

# Brief versenden mit Python (requests)
import requests

url = "https://pdfpost.de/api/v1/letters"
headers = {"Authorization": f"Bearer {api_key}"}

with open("rechnung.pdf", "rb") as f:
    response = requests.post(
        url,
        headers=headers,
        files={"document": f},
        data={"color": "false", "duplex": "false"}
    )

result = response.json()
# result["id"], result["status"]

Rate-Limits

Standard-Limits: 60 Anfragen pro Minute, 1.000 Anfragen pro Stunde. Bei Überschreitung erhalten Sie einen 429 Too Many Requests-Status.

Die aktuellen Rate-Limits werden in den Response-Headern mitgeliefert:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1716700800

Benötigen Sie höhere Limits? Kontaktieren Sie uns für individuelle Vereinbarungen.

Fehler-Codes

HTTP-Status	Bedeutung	Lösung
`400`	Ungültige Anfrage (fehlende Parameter, falsches Format)	Prüfen Sie die Parameter und das PDF-Format
`401`	Nicht authentifiziert (fehlender oder ungültiger API-Key)	Prüfen Sie Ihren API-Key
`402`	Unzureichendes Guthaben	Laden Sie Guthaben auf
`404`	Ressource nicht gefunden	Prüfen Sie die ID
`413`	Datei zu groß (max. 50 MB)	Reduzieren Sie die Dateigröße
`422`	Validierungsfehler (z. B. kein DIN-A4-Format)	Prüfen Sie die PDF-Anforderungen
`429`	Rate-Limit überschritten	Warten Sie und wiederholen Sie die Anfrage
`500`	Interner Serverfehler	Wiederholen Sie die Anfrage oder kontaktieren Sie den Support

Registrieren und API-Key erstellen