Briefe per API & Schnittstelle versenden: easyNova® digiBrief automatisiert

Mit der digiBrief-API versenden Sie Briefe direkt aus Ihrer eigenen Software: Sie übergeben ein PDF per REST-Schnittstelle — Druck, Kuvertierung, Frankierung und Übergabe an die Zustellung übernimmt easyNova®. Kein Drucker, kein Portohandling, kein Gang zur Post.

Die Schnittstelle ist bewusst schlank: ein Bearer-Token, JSON, zwei Pflichtfelder. Wer schon einmal eine REST-API angebunden hat, ist an einem Arbeitstag fertig. Diese Seite enthält alles, was dafür nötig ist — Endpunkte, Feldgrenzen, Statuscodes, Fehlerverhalten und Codebeispiele in fünf Sprachen.

Auf einen Blick

Die Schnittstelle kennt sieben Endpunkte. Drei davon brauchen Sie für den Regelbetrieb, die übrigen sind optional.

In drei Schritten zur ersten Sendung

1. Anmelden

POST /api/Login
Content-Type: application/json

{ "ekp": "ihr-konto@beispiel.de", "password": "IHR-KENNWORT" }

Die Antwort enthält das Token im Feld token. Es gilt 8 Stunden und wird bei allen weiteren Aufrufen als Kopfzeile mitgegeben: Authorization: Bearer IHR-TOKEN. Einen Verlängerungsendpunkt gibt es nicht — nach Ablauf melden Sie sich erneut an. Falsche Zugangsdaten beantwortet der Endpunkt mit HTTP 400.

Zwei Feldnamen stiften erfahrungsgemäß Verwirrung. ekp ist ein Erbstück aus der Postsprache (Einheitliche Kundennummer) und nimmt schlicht Ihren Benutzernamen entgegen — in aller Regel die E-Mail-Adresse des Kontos. Die Felder vendorId und secret tauchen in der Spezifikation noch auf, werden aber nur aus Kompatibilität zur Vorgängerversion angenommen und nicht ausgewertet. Sie brauchen sie nicht.

2. Brief einliefern

POST /api/letter
Authorization: Bearer IHR-TOKEN
Content-Type: application/json

[
  {
    "fileName": "rechnung_4711.pdf",
    "data": "PDF-INHALT-ALS-BASE64",
    "isColor": false,
    "isDuplex": false,
    "testFlag": true,
    "testEMail": "ihre-adresse@example.com",
    "testShowRestrictedArea": true
  }
]

Der Rumpf ist immer ein Array, auch bei einem einzelnen Brief. Das ist die häufigste Stolperstelle beim ersten Aufruf. Die Antwort liefert je Brief eine dauerhafte Kennung:

[ { "fileName": "rechnung_4711.pdf", "letterID": 100123 } ]

Tipp für den Einstieg: Lassen Sie testFlag auf true, bis Ihre Integration steht. Testsendungen durchlaufen sämtliche Prüfungen, werden aber weder gedruckt noch zugestellt.

3. Status verfolgen

GET /api/letter/100123
Authorization: Bearer IHR-TOKEN

Haben Sie beim Einliefern eine eigene batchID vergeben, fragen Sie den ganzen Stapel auf einmal ab: GET /api/letter/Batch. Mit dem Parameter onlyIssues bekommen Sie ausschließlich die Sendungen zurück, bei denen etwas nicht stimmt — praktisch, wenn Sie täglich vierstellige Stückzahlen einliefern und nur die Ausreißer sehen wollen.

Codebeispiele: Anmelden, Briefe einliefern, Status abfragen

Jedes Beispiel zeigt den vollständigen Ablauf und arbeitet mit testFlag: true — es durchläuft alle Prüfungen, gedruckt wird nichts. Für den Produktivbetrieb setzen Sie testFlag auf false oder lassen das Feld weg; testEMail und testShowRestrictedArea können stehen bleiben — ohne testFlag: true sind sie wirkungslos. Drei Muster stecken bewusst in allen Beispielen: das Token wird wiederverwendet statt vor jedem Aufruf neu geholt, die Zugangsdaten kommen aus Umgebungsvariablen statt aus dem Quelltext, und Fehler werden aus der errorList gelesen — dort steht die Begründung im Klartext. Pflicht sind allein fileName und data — die Empfängeradresse liest easyNova® aus dem PDF. Wollen Sie Adressdaten zur eigenen Zuordnung mitgeben, ergänzen Sie addressLine1, zipCode und city; auf die Zustellung haben sie keinen Einfluss.

# 1. Anmelden – Token gilt 8 Stunden
TOKEN=$(curl -s https://digibrief-api.easynova.de/api/Login \
  -H "Content-Type: application/json" \
  -d "{\"ekp\":\"$DIGIBRIEF_BENUTZER\",\"password\":\"$DIGIBRIEF_KENNWORT\"}" \
  | jq -r .token)

# 2. Testbrief einliefern – der Rumpf ist immer ein ARRAY
PDF_B64=$(base64 -w0 brief.pdf)
curl -s https://digibrief-api.easynova.de/api/letter \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
# Empfängeradresse kommt aus dem PDF – hier sind keine Adressfelder nötig
  -d "[{\"fileName\":\"brief.pdf\",\"data\":\"$PDF_B64\",\"testFlag\":true,\"testEMail\":\"ihre-adresse@example.com\",\"testShowRestrictedArea\":true}]"
# Antwort: [{"fileName":"brief.pdf","letterID":100123}]

# 3. Status abfragen
curl -s https://digibrief-api.easynova.de/api/letter/100123 \
  -H "Authorization: Bearer $TOKEN"

# Windows PowerShell 5.1 braucht die TLS-Zeile, PowerShell 7 nicht.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$basis = 'https://digibrief-api.easynova.de'

# 1. Anmelden – Token 8 Stunden aufheben
$zugang = @{ ekp = $env:DIGIBRIEF_BENUTZER; password = $env:DIGIBRIEF_KENNWORT } | ConvertTo-Json
$login  = Invoke-RestMethod -Method Post -Uri "$basis/api/Login" -ContentType 'application/json' -Body $zugang
$kopf   = @{ Authorization = "Bearer $($login.token)" }

# 2. Testbrief einliefern – das führende Komma erzwingt ein Array
$pdf = [Convert]::ToBase64String([IO.File]::ReadAllBytes('brief.pdf'))
# Empfängeradresse kommt aus dem PDF – hier sind keine Adressfelder nötig
$briefe = ,@{ fileName = 'brief.pdf'; data = $pdf; testFlag = $true; testEMail = 'ihre-adresse@example.com'; testShowRestrictedArea = $true }
$antwort = Invoke-RestMethod -Method Post -Uri "$basis/api/letter" -Headers $kopf -ContentType 'application/json' -Body (ConvertTo-Json $briefe -Depth 5)
$letterId = $antwort[0].letterID

# 3. Status abfragen – bei 99 steht die Begruendung in der errorList
$status = Invoke-RestMethod -Uri "$basis/api/letter/$letterId" -Headers $kopf
"Status $($status.statusID): $($status.statusDetails)"
$status.errorList | ForEach-Object { "  $($_.code): $($_.description)" }

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://digibrief-api.easynova.de") };

// 1. Anmelden – Token 8 Stunden wiederverwenden
var login = await http.PostAsJsonAsync("/api/Login", new
{
    ekp      = Environment.GetEnvironmentVariable("DIGIBRIEF_BENUTZER"),
    password = Environment.GetEnvironmentVariable("DIGIBRIEF_KENNWORT")
});
login.EnsureSuccessStatusCode();
var token = (await login.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("token").GetString();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

// 2. Testbrief einliefern – der Rumpf ist immer ein Array
var pdf = await File.ReadAllBytesAsync("brief.pdf");   // Base64 macht der Serialisierer
var antwort = await http.PostAsJsonAsync("/api/letter", new[]
{
    new
    {
        // Empfängeradresse kommt aus dem PDF – hier sind keine Adressfelder nötig
        fileName = "brief.pdf",
        data     = pdf,
        testFlag = true,
        testEMail              = "ihre-adresse@example.com",
        testShowRestrictedArea = true
    }
});
antwort.EnsureSuccessStatusCode();
var letterId = (await antwort.Content.ReadFromJsonAsync<JsonElement>())[0].GetProperty("letterID").GetInt32();

// 3. Status abfragen – bei 99 steht die Begruendung in der errorList
var status = await http.GetFromJsonAsync<JsonElement>($"/api/letter/{letterId}");
Console.WriteLine($"Status {status.GetProperty("statusID").GetInt32()}: {status.GetProperty("statusDetails").GetString()}");
foreach (var fehler in status.GetProperty("errorList").EnumerateArray())
    Console.WriteLine($"  {fehler.GetProperty("code")}: {fehler.GetProperty("description")}");

import base64, os, requests

BASIS = "https://digibrief-api.easynova.de"

# 1. Anmelden – Token 8 Stunden aufheben
login = requests.post(f"{BASIS}/api/Login", json={
    "ekp": os.environ["DIGIBRIEF_BENUTZER"],
    "password": os.environ["DIGIBRIEF_KENNWORT"],
})
login.raise_for_status()
kopf = {"Authorization": f"Bearer {login.json()['token']}"}

# 2. Testbrief einliefern – der Rumpf ist immer eine LISTE
with open("brief.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode()

antwort = requests.post(f"{BASIS}/api/letter", headers=kopf, json=[{
    # Empfängeradresse kommt aus dem PDF – hier sind keine Adressfelder nötig
    "fileName": "brief.pdf",
    "data": pdf_b64,
    "testFlag": True,
    "testEMail": "ihre-adresse@example.com",
    "testShowRestrictedArea": True,
}])
antwort.raise_for_status()
letter_id = antwort.json()[0]["letterID"]

# 3. Status abfragen – bei 99 steht die Begruendung in der errorList
status = requests.get(f"{BASIS}/api/letter/{letter_id}", headers=kopf).json()
print(f"Status {status['statusID']}: {status['statusDetails']}")
for fehler in status["errorList"]:
    print(f"  {fehler['code']}: {fehler['description']}")

<?php
$basis = 'https://digibrief-api.easynova.de';

function aufruf(string $url, ?string $token = null, ?string $json = null): array {
    $ch   = curl_init($url);
    $kopf = ['Content-Type: application/json'];
    if ($token) $kopf[] = "Authorization: Bearer $token";
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $kopf]);
    if ($json !== null) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
    }
    $antwort = curl_exec($ch);
    $code    = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($code >= 400) throw new RuntimeException("HTTP $code: $antwort");
    return json_decode($antwort, true);
}

// 1. Anmelden – Token 8 Stunden aufheben
$login = aufruf("$basis/api/Login", null, json_encode([
    'ekp'      => getenv('DIGIBRIEF_BENUTZER'),
    'password' => getenv('DIGIBRIEF_KENNWORT'),
]));
$token = $login['token'];

// 2. Testbrief einliefern – der Rumpf ist immer ein ARRAY von Briefen
$briefe = [[
    // Empfängeradresse kommt aus dem PDF – hier sind keine Adressfelder nötig
    'fileName' => 'brief.pdf',
    'data'     => base64_encode(file_get_contents('brief.pdf')),
    'testFlag' => true,
    'testEMail' => 'ihre-adresse@example.com',
    'testShowRestrictedArea' => true,
]];
$antwort  = aufruf("$basis/api/letter", $token, json_encode($briefe));
$letterId = $antwort[0]['letterID'];

// 3. Status abfragen – bei 99 steht die Begruendung in der errorList
$status = aufruf("$basis/api/letter/$letterId", $token);
echo "Status {$status['statusID']}: {$status['statusDetails']}" . PHP_EOL;
foreach ($status['errorList'] as $fehler) {
    echo "  {$fehler['code']}: {$fehler['description']}" . PHP_EOL;
}

Für jede andere Sprache laden Sie die maschinenlesbare Schnittstellenbeschreibung unter https://digibrief-api.easynova.de/swagger/v1/swagger.json in Postman, Insomnia oder einen OpenAPI-Generator — damit erzeugen Sie sich Aufrufbeispiele und Client-Klassen selbst. Ein eigenes SDK brauchen Sie dafür nicht, und Sie sind nicht darauf angewiesen, dass wir eines für Ihre Sprache pflegen.

Das PDF: worauf es ankommt

Die Zustelladresse liest easyNova® aus Ihrem Dokument — aus dem Adressfenster der ersten Seite, bei Bedarf per Texterkennung. Das ist die wichtigste Eigenschaft der Schnittstelle und der häufigste Grund, warum eine erste Integration nicht funktioniert: Wer die Adresse nur im JSON übergibt und im PDF weglässt, bekommt eine Ablehnung.

Diese Entscheidung ist Absicht. Was auf dem Brief steht, wird zugestellt — eine Abweichung zwischen Dokument und Versanddaten kann es damit gar nicht geben. Daraus ergeben sich drei Gestaltungsregeln:

1. Empfängeradresse ins Adressfenster der ersten Seite, positioniert wie bei einem DIN-5008-Geschäftsbrief.
2. Absender ins Absenderfeld. Über dem Adressfenster steht die Absenderzeile — Name, Straße, PLZ und Ort in einer Zeile, wie sie im Fensterumschlag sichtbar ist. Sie ist nicht optional: Ein Brief ohne erkennbaren Absender wird abgelehnt, nicht kommentarlos versendet. Das gilt für alle Konten mit Freimachungszone, und das ist der Regelfall. Wenn Ihr Dokument keinen Absender tragen kann, geben Sie ihn im Feld senderAdressLineComplete mit.
3. Frankierzone freihalten. Der obere Bereich des Adressfensters ist für den Freimachungsvermerk reserviert. Anderer Inhalt in dieser Zone (Logos, Grafiken) führt zur Ablehnung — mit Begründung, nie stillschweigend. Wie eine solche Sperrfläche aussieht, zeigt anschaulich unser Beitrag Sperrflächen-Updates für E-POST Briefe samt Schablone zum Herunterladen. Verbindlich für Ihren Ausgabekanal ist aber der Testmodus: testShowRestrictedArea zeichnet die geltenden Flächen direkt auf Ihr eigenes Dokument.
4. Adresse zu weit oben? Nur auf Anforderung wird korrigiert. Sitzt die Empfängeradresse so, dass sie mit der Freimachungszone kollidiert, kann easyNova® sie für Sie an die zulässige Stelle setzen — aber nicht von selbst. Geben Sie dazu "addressCorrection": "auto" mit. Ihr Layout bleibt unverändert, nur der Adressblock wird neu gesetzt; Briefe mit korrekt sitzender Adresse werden nicht angetastet. Ohne diese Anforderung wird ein Brief mit kollidierender Adresse abgelehnt — die Fehlermeldung nennt dann ausdrücklich auto als Ausweg und listet die für Ihr Konto hinterlegten Korrekturprofile.
5. Format: DIN A4 im Hochformat, maximal 20 MB je Sendung und 300 MB je Aufruf.

Die JSON-Adressfelder (addressLine1, zipCode, city …) sind optional: Sie können sie zur eigenen Zuordnung mitgeben — dann erscheinen sie unverändert in der Statusauskunft —, auf die Zustellung haben sie keinen Einfluss. Maßgeblich ist immer die Adresse im PDF.

Auslandsversand folgt derselben Logik: Steht eine ausländische Empfängeradresse im Adressfenster, wird der Brief dorthin zugestellt. Ein zusätzliches Feld ist dafür nicht nötig. Die Portokosten richten sich nach dem Zielland — die geltenden Sätze finden Sie unter digiBrief-Preise.

Die Felder im Überblick

Eine Sendung kennt 40 Felder. Pflicht sind genau zwei — der Dateiname und das PDF. Mit ihnen allein versenden Sie bereits produktiv; alles Weitere ist Feinsteuerung.

Ein Hinweis zu den Feldern, die es nur aus Kompatibilitätsgründen gibt: custom1 bis custom5, plugInList und costCenter stehen in der Spezifikation, werden von dieser Instanz aber angenommen und nicht verarbeitet. Verlassen Sie sich nicht darauf. Für die Zuordnung eigener Vorgänge nutzen Sie fileName — der Dateiname kommt in der Statusauskunft unverändert zurück und ist damit der verlässliche Anker in Ihr System.

Gefahrlos testen

Der Testmodus ist ein vollwertiger Probelauf, kein Trockenlauf. Mit testFlag: true durchläuft Ihre Sendung sämtliche Prüfungen — Adresserkennung, Flächenprüfung, Aufbereitung — und wird beim Versanddienst als Testsendung registriert. Gedruckt und zugestellt wird nichts.

Das Flag gilt je Sendung: Testbriefe und echte Briefe dürfen im selben Stapel stehen. Sie müssen Ihre Integration also nicht in einem Rutsch scharf schalten, sondern können sie schrittweise umstellen. Der Statusabruf gibt testFlag zurück — Sie sehen jederzeit, ob eine Sendung ein Testbrief war.

Geben Sie zusätzlich testEMail an (bis 100 Zeichen), kommt genau das Dokument per E-Mail zurück, das gedruckt worden wäre — dazu die Sendungsnummer. Das wirkt nur zusammen mit testFlag: true.

testShowRestrictedArea: true ist eine Darstellungsoption dieser Test-E-Mail, keine eigene Funktion: In das zurückgesendete PDF werden die für Ihr Konto geltenden Flächen eingezeichnet — rot die Prüfflächen (Freimachungszone und weitere gesperrte Bereiche), blau die Auslesefenster für Empfängeradresse und Absender, jeweils beschriftet. Damit sehen Sie vor dem ersten echten Brief, ob Ihr Layout sitzt. Ohne testFlag und testEMail bleibt das Flag wirkungslos — es wird ohne Hinweis ignoriert.

Die Test-E-Mail ist ein Zusatzweg, kein Statussignal. Ihr Versand ist vom Ergebnis der Sendung entkoppelt: Kommt die Mail nicht an, sagt das nichts über den Brief aus — maßgeblich ist immer die Statusabfrage. Prüfen Sie in dem Fall Adresse und Spam-Ordner. Ist die Test-E-Mail auf Ihrer Instanz nicht eingerichtet, wird eine Testsendung mit testEMail mit klarer Meldung abgelehnt, statt stillschweigend verschluckt zu werden.

Verbindungsabbrüche: der Idempotency-Key

Was passiert, wenn Ihre Verbindung abbricht, nachdem Sie den Brief gesendet haben, aber bevor die Antwort ankommt? Ohne Absicherung müssten Sie raten: nochmal senden und einen zweiten Brief riskieren — oder nicht senden und vielleicht gar keinen verschicken.

Geben Sie deshalb beim Einliefern eine Kopfzeile mit:

POST /api/letter
Authorization: Bearer IHR-TOKEN
Idempotency-Key: auftrag-2026-08-4711

Wiederholen Sie den Aufruf im Zweifelsfall einfach mit demselben Schlüssel: Sie erhalten die ursprüngliche letterID zurück, und es wird nichts ein zweites Mal gedruckt. Als Schlüssel eignet sich jede Kennung, die in Ihrem System eindeutig ist — Vorgangs-, Auftrags- oder Rechnungsnummer (bis 180 Zeichen).

Liefern Sie mehrere Briefe in einem Aufruf ein, gilt der Schlüssel für den gesamten Aufruf; behalten Sie bei einer Wiederholung dann die Reihenfolge der Briefe bei.

Das Statusmodell

Jede Ablehnung trägt eine verständliche Begründung, etwa „Dokument Seite 1: Inhalt verletzt Sperrfläche DV-Freimachung“. Die errorList ist damit die erste Anlaufstelle bei Problemen — nicht der Support.

Statuswechsel folgen dem Produktionsrhythmus. Eine Abfrage mehrmals täglich genügt; häufigeres Abfragen liefert keine neueren Daten und belastet nur beide Seiten. Für Monitoring-Zwecke gibt es GET /health — der Endpunkt meldet, ob die Schnittstelle und ihre Datenbank erreichbar sind.

Zeitangaben kommen in Ortszeit mit Versatz: Felder wie createdDate lauten 2026-08-21T13:55:03.769854+02:00 — deutsche Ortszeit mit Zeitzonenversatz, im Winter +01:00, nicht UTC. Wer den Versatz mitliest, rechnet richtig; wer ein Z erwartet, liegt um zwei Stunden daneben.

Testsendungen bleiben auf statusID 1. Eine Sendung mit testFlag: true wird geprüft, aber nicht produziert — sie durchläuft die Stufen 2 bis 4 deshalb nicht und behält dauerhaft Status 1. Das ist der Sollzustand und kein Fehler: Warten Sie beim Testen nicht auf Status 4. Ob die Prüfung sauber durchgelaufen ist, sehen Sie an statusID 1 ohne Einträge in errorList — und am zurückgesendeten PDF, wenn Sie testEMail gesetzt haben.

Welche Felder die Statusauskunft füllt

Die Antwort enthält aus historischen Gründen mehr Felder, als easyNova® befüllt. Diese Übersicht erspart Ihnen das Rätselraten:

Alle Felder bleiben dauerhaft Teil der Antwort; Ihre Integration muss also nichts umstellen.

Was kostet ein Brief? Die Preisvorschau

Bevor Sie den ersten echten Brief verschicken, können Sie den Preis abfragen — ohne etwas einzuliefern:

POST /api/pricePreview
Authorization: Bearer IHR-TOKEN
Content-Type: application/json

{ "pagesCount": 2, "isColor": false, "isDuplex": false,
  "countryIso": "DE", "zipCode": "53115" }

Die Antwort:

{ "pagesCount": 2, "priceNet": 0.65, "priceGross": 0.7735,
  "standardNet": 0.65, "standardGross": 0.7735,
  "optimizedNet": null, "optimizedGross": null }

Statt pagesCount können Sie auch data senden, also das PDF als Base64 — dann zählt easyNova® die Seiten selbst. Mit registeredLetter erhalten Sie den Preis inklusive Einschreiben; ist die gewünschte Variante für Ihr Konto nicht freigeschaltet, antwortet die Vorschau mit der Begründung statt mit einem Preis. So erfahren Sie es, bevor eine Sendung abgelehnt wird. Mit optimizePrice: true wird die Portooptimierung einbezogen — sie zählt nur, wenn sie günstiger ist.

Der Wert ist eine Momentaufnahme und keine Zusage: Verbindlich rechnet das Backend bei der Verarbeitung ab.

Konto und Guthaben

Mit GET /api/companyBilling fragen Sie die Abrechnungssicht Ihres Kontos ab: Zahlart, aktuelles Guthaben, im laufenden Zeitraum aufgelaufene Kosten sowie Limit- und Warnschwelle. Bei Prepaid-Konten lohnt sich der Aufruf als Vorabprüfung, bevor Sie einen größeren Stapel einliefern — so scheitert die Einlieferung nicht am Guthaben. Die Werte sind eine Momentaufnahme aus dem Backend und ersetzen keine Rechnungsprüfung.

Wiederholungen sind sicher. Wird derselbe Brief — identisches PDF, gleiche Optionen — innerhalb von 15 Minuten doppelt eingeliefert, erkennt easyNova® das Duplikat. Er wird nicht zweimal gedruckt, auch nicht bei zwei gleichzeitigen Aufrufen.

Zwei Feinheiten, die in der Praxis zählen: Nach Ablauf des Fensters ist derselbe Brief wieder eine neue Sendung — der Mahnlauf nächste Woche geht also durch. Und eine abgelehnte Sendung blockiert nichts: Dort ist kein Porto entstanden, und die erneute Einlieferung nach einer Korrektur ist der normale Weg.

Einschreiben über die Schnittstelle

Varianten im Klartext: Einschreiben, Einschreiben Einwurf, Einschreiben Rückschein, Einschreiben Einwurf Rückschein. Die Wortstellung des ePost-Altsystems (Einwurf Einschreiben) wird ebenfalls verstanden — Bestandsintegrationen müssen hier nichts umbauen.

Varianten als Kürzel: national E---- (Einschreiben), EEW-- (Einwurf), ER--- (Rückschein), EEWR- (Einwurf + Rückschein); international IE--- und IER--.

Nicht mehr verfügbar: Einschreiben Eigenhändig und die Kombination mit Rückschein (Kürzel EEH--, EEHR-, IEEH-). Die Deutsche Post hat die Leistung zum 1. Januar 2026 eingestellt; entsprechende Aufrufe werden abgelehnt.

Welche Varianten für Ihr Konto und das Empfängerland freigeschaltet sind, prüft die Einlieferung. Eine nicht freigeschaltete Variante wird abgelehnt — mit Nennung der für Sie zulässigen Werte und niemals stillschweigend als Normalbrief versendet. Einschreiben sind nur im einseitigen Druck möglich (isDuplex: false) und kostenpflichtig; mit testFlag: true prüfen Sie den Ablauf kostenfrei.

Nicht unterstützt: Deckblätter (coverLetter, coverData) — Sendungen mit diesen Feldern werden mit einer klaren Fehlermeldung abgewiesen. Das ist die wichtigere Zusage dahinter: Ihre Sendung wird nie unbemerkt anders versendet als beauftragt. Eine Schnittstelle, die etwas Unmögliches stillschweigend abändert, ist gefährlicher als eine, die es ablehnt.

Nachweis und Sendungsverfolgung. Bei Einschreiben liefert GET /api/letter/{letterId} die Sendungsnummer der Post (registeredLetterID) sowie den weiterführenden Zustellstatus (registeredLetterStatus) mit Zeitstempel (registeredLetterStatusDate). Die Nummer erscheint in der Nacht nach der Einlieferung, wenn die Sendung an den Druckdienstleister übertragen wird — also vor der eigentlichen Produktion. Ein Zustellergebnis kann Tage später folgen. Geführt wird jeweils die aktuelle Meldung, keine Ereignishistorie. Solange keine Angabe vorliegt, bleiben die Felder leer; im Testmodus bleiben sie dauerhaft leer, weil eine Testsendung nicht eingeliefert wird. Was Sie mit der Sendungsnummer bei der Post abrufen können, richtet sich nach Ihrem Vertrag mit der Post und liegt außerhalb dieser API.

Wohin der Rückschein geht. Die Felder registeredLetterAdressLine1–3, registeredLetterZipCode und registeredLetterCity stammen aus dem ePost-Altvertrag. Sie werden angenommen und in der Statusauskunft zurückgegeben, steuern den Rückschein aber nicht — die Rücksendung richtet sich nach den Absenderdaten des Versands, nicht nach Angaben je Brief. Wenn Sie Rückscheine bestimmten Vorgängen zuordnen müssen, planen Sie das über Ihre eigene Referenz, etwa batchID oder den Dateinamen.

Hinweis für Umsteiger von der alten Schnittstelle. Dort wurde registeredLetter nicht ausgewertet — jede Sendung ging als Normalbrief hinaus, auch wenn das Feld gefüllt war. Auf dieser Schnittstelle wird das Feld erfüllt. Prüfen Sie deshalb vor der Umstellung, was Ihre Integration hineinschreibt: Ein stehengebliebener Beispielwert führt jetzt zu einer Ablehnung, und ein gewolltes Einschreiben erzeugt jetzt echte Einschreiben-Kosten. Wird das Feld leer gelassen, ändert sich nichts.

POST /api/pricePreview
Authorization: Bearer IHR-TOKEN
Content-Type: application/json

{
  "pagesCount": 2,
  "isColor": false,
  "isDuplex": false,
  "registeredLetter": "Einschreiben Einwurf"
}

POST /api/letter
Authorization: Bearer IHR-TOKEN
Content-Type: application/json

[
  {
    "fileName": "kuendigung_4711.pdf",
    "data": "PDF-INHALT-ALS-BASE64",
    "isDuplex": false,
    "registeredLetter": "Einschreiben Einwurf"
  }
]

GET /api/letter/100123
Authorization: Bearer IHR-TOKEN

{
  "letterID": 100123,
  "statusID": 4,
  "registeredLetterID": "RR123456789DE",
  "registeredLetterStatus": "zugestellt",
  "registeredLetterStatusDate": "2026-09-03T19:34:00Z"
}

In fünf Schritten zum ersten Brief

1. Konto einrichten. Sie erhalten Ihre Zugangsdaten.
2. Anmelden über POST /api/Login — Sie erhalten Ihr API-Token.
3. Testbrief einliefern mit testFlag und testEMail. Das zurückgesendete PDF zeigt Ihnen, ob das Layout passt.
4. Guthaben aufladen — bei Prepaid-Konten, dem Regelfall. Den aktuellen Stand fragen Sie jederzeit über GET /api/companyBilling ab.
5. Produktiv gehen: testFlag weglassen. Mehr ist nicht zu tun.

Für wen sich die Schnittstelle eignet

Überall dort, wo Briefe aus einem System heraus entstehen: Rechnungen und Mahnungen aus der Finanzbuchhaltung, Bescheide aus einer Fachanwendung, Vertragsunterlagen aus dem CRM, Serienkorrespondenz aus einem Branchenprogramm. Der Aufwand lohnt ab dem Punkt, an dem jemand regelmäßig PDFs erzeugt, ausdruckt, kuvertiert und frankiert.

Ab 0,65 € netto je Brief im Inland — ohne Grundgebühr, ohne Mindestumsatz, ohne Vertragsbindung. Die Schnittstelle selbst kostet nichts extra; Sie zahlen nur die Sendung. Skaliert von der Einzelsendung bis zu hohen Volumina.

Andere Wege in easyNova®

Nicht jedes System lässt sich programmieren, und nicht jeder Versand braucht eine Schnittstelle. Zwei weitere Wege automatisieren den Versand ohne eine Zeile Code — den Überblick über alle drei gibt die Seite Briefversand automatisieren.

Kein Automatisierungsthema, aber oft gesucht: Wer einfach nur aus einer beliebigen Anwendung heraus drucken oder Serienbriefe aus Word verschicken möchte, nutzt den Windows-Client mit Druckertreiber und Word-Add-in. Serienbriefe gehen außerdem vollständig im Browser — ganz ohne Installation.

Häufige Fragen zur Brief-API

Mehr zum Thema: Hybridpost, Serienbrief aus Word, Einschreiben online und der Überblick Briefversand automatisieren.

Ohne eigene Programmierung lässt sich der Versand ebenfalls automatisieren: Der Hotfolder überwacht einen Ordner und verschickt abgelegte Dokumente automatisch, während das automatische Verschlagworten eingehende Briefe regelbasiert sortiert und kennzeichnet.