E-Post versenden (Deutsche Post Hybridbrief)

Der Service Task „E-Post versenden“ liefert PDF-Dokumente über die E-POSTBUSINESS API der Deutschen Post als Hybridbrief ein. Der Task übernimmt die PDF/A-Konvertierung, das DVF-Fenster/Overlay sowie das Mapping der Eingabefelder auf die API-Struktur. Login-Daten können optional pro Aufruf überschrieben werden.

Input-Parameter

{
  "letter": {
    "filename": "Rechnung_4711.pdf",
    "pdf_ref": {"...": "file_reference"},
    "iscolor": false,
    "isduplex": true,
    "testflag": false,
    "testemail": "max.mustermann@example.com",
    "testshowrestrictedarea": false,
    "addresslineone": "Max Mustermann",
    "addresslinetwo": "Musterstraße 1",
    "addresslinethree": "1. OG",
    "zipcode": "12345",
    "city": "Musterstadt",
    "country": "DE",
    "senderadresslineone": "Pantarey GmbH",
    "senderstreet": "Hauptstraße 5",
    "senderzipcode": "86150",
    "sendercity": "Augsburg",
    "costcenter": "AB1234",
    "customone": "Auftragsnr. 4711",
    "customtwo": "Kunde-XYZ"
  },
  "login": {
    "vendorID": "OPTIONAL_OVERRIDE",
    "ekp": "OPTIONAL_OVERRIDE",
    "secret": "OPTIONAL_OVERRIDE",
    "password": "OPTIONAL_OVERRIDE",
    "vendorSubID": "OPTIONAL",
    "tokenDuration": 1440
  }
}

Erläuterung:

• letter: Enthält alle Angaben zum zu versendenden Brief.
• filename: Eindeutiger Dateiname (erlaubt: [A-Za-z0-9._-]), dient der Zuordnung in der API.
• pdf_ref: Datei-Referenz; das PDF wird zu PDF/A-1b konvertiert und mit DVF-Overlay versehen.
• iscolor/isduplex: Druckeinstellungen (Farbe bzw. Duplex).
• testflag/testemail/testshowrestrictedarea: Felder für Testsendungen.
• addressline…, zipcode, city, country: Empfängeradresse.
• sender…: Absenderangaben (Absenderzeile mit 8 pt im DVF-Fenster erforderlich).
• costcenter: Maximal 8 alphanumerische Zeichen für Mandantentrennung/Abrechnung.
• customone bis customtwo (bis customfive möglich): Freifelder, die als custom1..5 an die Post übermittelt werden.
• login: Optional; ohne dieses Objekt werden die im Service-Task hinterlegten Zugangsdaten genutzt.

Output

Pro übermitteltem Brief wird das angereicherte Letter-Objekt inklusive Post-ID zurückgegeben:

{
  "letterid": "ab12cd34-ef56-...",
  "filename": "Rechnung_4711.pdf",
  "costcenter": "AB1234",
  "status": {
    "statusid": 0,
    "statusdetails": "Brief erfolgreich an Deutsche Post übermittelt (Pantarey)",
    "createddate": "2025-09-05T11:12:13.000Z",
    "errorlist": [],
    "pluginfeedbacklist": []
  }
}

• letterid: ID des Briefs in der Deutsche-Post-API.
• status: Initialer Briefstatus mit UTC-Zeitstempeln (...Z).

Verhalten und Validierung

• PDF-Konvertierung: Eingabedateien werden zu PDF/A-1b konvertiert, inklusive sRGB-Profil, XMP-Metadaten und DVF-Fenster.
• Dateiname/Zuordnung: Deduplikation erfolgt über filename; die Zuordnung basiert nicht auf der Reihenfolge.
• UTC-Zeitstempel: API-Zeiten werden auf UTC normalisiert; das Backend akzeptiert ausschließlich UTC-ISO.
• Login-Caching: Token werden tenant-spezifisch gecacht; login überschreibt optionale Defaults.

JSON-Beispiele

Minimal

{
  "letter": {
    "filename": "Mahnung_0815.pdf",
    "pdf_ref": {"...": "file_reference"},
    "addresslineone": "Muster GmbH",
    "addresslinetwo": "z. Hd. Buchhaltung",
    "zipcode": "20095",
    "city": "Hamburg",
    "senderadresslineone": "Pantarey GmbH",
    "senderstreet": "Hauptstraße 5",
    "senderzipcode": "86150",
    "sendercity": "Augsburg",
    "iscolor": false,
    "isduplex": true
  }
}

Mit Login-Override

{
  "letter": { "...": "siehe oben" },
  "login": {
    "vendorID": "1234567",
    "ekp": "EKP123456",
    "secret": "****",
    "password": "****",
    "tokenDuration": 60
  }
}

JSONata-Beispiele

{
  "letter": {
    "filename": "Rechnung_" & $.invoice.number & ".pdf",
    "pdf_ref": $.files.invoicePdfRef,
    "addresslineone": $.customer.name,
    "addresslinetwo": $.customer.street & " " & $.customer.houseNo,
    "addresslinethree": $.customer.addressLine3,
    "zipcode": $.customer.zip,
    "city": $.customer.city,
    "country": $.customer.country,
    "senderadresslineone": "Pantarey GmbH",
    "senderstreet": "Hauptstraße 5",
    "senderzipcode": "86150",
    "sendercity": "Augsburg",
    "iscolor": false,
    "isduplex": true,
    "costcenter": $.tenant.costCenter
  }
}

Hinweise

• Adressfenster/DVF: Empfängerblöcke korrekt befüllen; Masken und Texte werden automatisch positioniert.
• Dateiname: Nur API-konforme Dateinamen verwenden; unerlaubte Zeichen werden ersetzt.
• Testmodus: Mit testflag = true und optional testemail lassen sich Sendungen ohne reale Zustellung prüfen.