Mit den E-POST-Produkten bietet die Deutsche Post AG Services zum hybriden Briefversand. Dieser ermöglicht neben der digitalen Übermittlung der Briefsendungen die physische Produktion (Druck, Kuvertierung, Frankierung) sowie die Zustellung der Sendungen an den Empfänger als klassischen Brief durch den Post-Zusteller. Die E-POSTBUSINESS API ist eine Webservice-Schnittstelle zum Versand von hybriden Briefen direkt aus einer Software-Anwendung. Dies steigert die Attraktivität und den Mehrwert einer individuell entwickelten Softwarelösung durch die API-basierte Integration des hybriden Briefversands und ermöglicht Eigenversendern und/oder deren Endkunden so die transparente Automatisierung des Postausgangs: einfach, günstig und nachhaltig. Man spart Zeit, Material und Ressourcen und die Zustellung erfolgt wie gewohnt zuverlässig mit der Deutschen Post.

Jeder Kunde der Deutschen Post erhält eine Kundenummer, die sogenannte EKP. Diese wird im Rahmen eines Vertragsabschlusses mit der Deutschen Post, z.B. bei einer Produktregistrierung, automatisch generiert.

Die EKP dient der eindeutigen Zuordnung von Leistungen und Services und findet sich daher auch wieder auf unseren Verträgen, Rechnungen oder sonstiger Kommunikation mit der Deutschen Post.

Sollte die EKP nicht mehr bekannt sein, kann man unter Angabe der relevanten Kundenstammdaten diese beim Kundenservice der Deutschen Post (e-post@deutschepost.de) erfragen.

Jeder Anwender, der über E-POST hybride Briefe verschickt, ist ein E-POST Nutzer. Die hierfür erforderliche E-POST Nutzervereinbarung wird jeweils im Rahmen der Registrierung für das E-POST Produkt, z.B. für die E-POSTBUSINESS API, online abgeschlossen.

  Direktlink zur API Registrierung

Bitte beachten Sie, dass aus Sicherheitsgründen eine Registrierung mit eMail-Adressen allgemeiner Provider wie Gmail, GMX, etc. möglicherweise systemisch abgelehnt wird, um unerlaubte Informationsabrufe über bestehende Kundenaccounts zu verhindern.

Als API Nutzer definiert man die Anwender, die die E-POSTBUSINESS API in eine vorhandene Softwarelösung implementieren. Dabei unabhängig ist es, ob man die Lösung als Eigenversender oder als Partner für Endkunden realisiert.

Jeder API Nutzer schließt mit der Deutschen Post einen Vertrag ab. Der API Nutzervertrag wird digital mit DocuSign gezeichnet.

Es ist dabei zu beachten, dass Vertragspartner der Deutschen Post immer der Nutzer der E-POSTBUSINESS API ist. Wird die Implementierung der E-POSTBUSINESS API durch einen Dritten, z.B. einen IT-Dienstleister, im Auftrag des Nutzers durchgeführt, besteht zwischen diesem und der Deutschen Post kein Vertragsverhältnis.

Wichtig: Der Versand von Briefen über die E-POSTBUSINESS API, setzt zwingend zusätzlich zum API-Nutzervertrag eine E-POST Nutzervereinbarung voraus.

Als Partner/Eigenversender benötigt man die eigene EKP sowie eine [vendorID], die der API Support der Deutschen Post zur Verfügung stellt, um auf die Entwicklerumgebung zugreifen zu können.

Für die Freischaltung der Testumgebung sowie die Kommunikation wird eine eMail-Adresse benötigt. Die Adresse wird im System hinterlegt und ist gültig bis eine Änderung über den Client Controller erfolgt.

Aus Sicherheitsgründen wird für die Freischaltung der Entwicklungsumgebung zusätzlich der Freischaltcode per SMS (TAN) versendet. Diese TAN wird im System hinterlegt und ist gültig bis eine Änderung über den Client Controller erfolgt.

Nach der Registrierung und dem Abschluss der E-POST Nutzervereinbarung wird der API Nutzervertrag abgeschlossen. Die erforderliche Zeichnung der Verträge erfolgt elektronisch über DocuSign.

Nach Zeichnung der Verträge wird der E-POSTBUSINESS API Support dem Partner/Eigenversender die [vendorID] per eMail zur Verfügung stellen.

Um das [secret] zu erhalten, gehen Sie wie folgt vor:

1. SMS Code anfordern über die Route [/api/Login/smsRequest] (Verifizierung über die hinterlegte Mobilfunknummer)
2. Passwort vergeben über die Route [/api/Login/setPassword] (hierfür wird der SMS Code benötigt). Hier erhalten sie als Antwort das [secret].

Ab jetzt können sie über die Route [/api/Login] einen Token für ihre Requests anfordern. Dieser ist übrigens 24 Std lang gültig. Sie können diesen also für mehrere Anfragen/Aufträge verwenden.

Nach einem erfolgreichen Login kann man über den Client Controller [TestMail] eine eMail an die hinterlegte eMail Adresse zur Prüfung versenden.

Um die hinterlegte eMail-Adresse zu ändern, muss man sich erfolgreich einloggen und Zugriff auf die hinterlegte mobile Rufnummer haben.

Per Client Controller wird ein Sicherheitscode über [MailRequest] unter Angabe der neuen eMail-Adresse an die hinterlegte mobile Rufnummer gesendet. Dieser Code ist dann zusammen mit der neuen eMail-Adresse für die Aktualisierung über [SetMail] zu übergeben. Zur Bestätigung der er-folgreichen Änderung wird automatisch eine eMail an die neue eMail-Adresse versendet.

Nach einem erfolgreichen Login kann man über den Client Controller [TestMobile] eine SMS Nachricht an die hinterlegte Rufnummer zur Prüfung versenden lassen.

Um die hinterlegte Rufnummer zu ändern, muss man sich erfolgreich einloggen und Zugriff auf die hinterlegte mobile Rufnummer haben.

Per Client Controller wird ein Sicherheitscode über [MobileRequest] unter Angabe der neuen mobilen Rufnummer an die hinterlegte eMail Adresse gesendet. Dieser Code ist dann zusammen mit der neuen Rufnummer für die Aktualisierung über [SetMobile] zu übergeben. Zur Bestätigung der erfolgreichen Änderung wird automatisch eine SMS Nachricht an die neue Rufnummer versendet.

Unabhängig von den technischen Zugangsdaten zur Verwendung der E-POSTBUSINESS API ist es erforderlich, die zentralen Kontaktdaten über [/api/Vendor/SetContactInformations] zu pflegen. Gesetzt werden hierbei Daten wie der technische Ansprechpartner/Kontakt für Wartungsinformationen und Supportthemen. Der geschäftliche Ansprechpartner/Kontakt wird für die Kommunikation zu wichtigen Systemanpassungen und vertraglich/rechtlichen Themen verwendet.

Zu Beginn der Entwicklung arbeitet man im Entwicklungsmodus der E-POSTBUSINESS API und kann alle Funktionen der API ohne Zeitlimit oder Kosten implementieren und nutzen. Im Entwicklungsmodus ist jedoch gewährleistet, dass keine versehentliche Dokumenteneinlieferung erfolgt und kostenpflichtige Briefsendungen produziert werden.

Der Wechsel vom Entwicklungsmodus zum Produktivmodus wird durch den API Support vorgenommen. Wenn die Implementierung der E-POSTBUSINESS API abgeschlossen ist, kontaktiert man unter Angabe von

• Kunde/Unternehmen
• vendorID und
• EKP

den E-POSTBUSINESS API Support über EpostApiSupport@docuguide.com.

Nach Prüfung der Angaben schaltet der API Support die Produktivumgebung frei und gibt dazu eine Rückmeldung. Jetzt können die Dokumente in das Druckzentrum übermittelt werden.

Ein Endkunde oder Eigenversender muss die E-POSTBUSINESS API in der Partnersoftware aktivieren. Dafür wird eine SMS TAN benötigt, um das Kennwort zur Aktivierung der API zu setzen.

Erforderlich sind hierfür die Kundenummer des Endkunden bei der Deutschen Post (EKP), die [vendorID] des Softwareherstellers und der Zugriff auf ein Mobiltelefon, dessen Nummer bei der API Registrierung angegeben bzw. abgefragt wurde.

Auf Basis der EKP des Endkunden/Eigenversenders wird an die in diesem E-POST Account hinterlegte Mobilnummer zeitnah per SMS eine TAN gesendet, die mehrere Minuten gültig ist (siehe swagger Doku: [Login: smsRequest]).

Mit der erhaltenen TAN, der Kundenummer (EKP) des Endkunden und der [vendorID] des Softwarepartners vergibt der Endkunde ein neues Kennwort (siehe swagger Doku: [Login: setPassword]) und erhält einen Sicherheitsschlüssel ([secret]). Diesen Sicherheitsschlüssel benötigt er später zusammen mit seinem Kennwort für den Login.

Als Entwickler/Eigenversender benötigt man für die Anmeldung an der E-POSTBUSINESS API die [vendorID], die der API Support zur Verfügung stellt, die relevante EKP der Deutschen Post, ein individuelles Kennwort und den Sicherheitsschlüssel [secret]. Mit diesen Daten loggt man sich an der API an und erhält ein Laufzeittoken.

Für den Endkunden, als Nutzer der Partnerlösung, hinterlegt der Entwickler/Partner in der Regel in der Software die [vendorID]. Der Endkunde kann sich dann mit seiner EKP, seinem Kennwort und seinem Sicherheitsschlüssel [secret] anmelden und die API in der Partnersoftware nutzen. (Siehe auch: Wie aktiviert ein Endkunde die E-POSTBUSINESS API in der Partnerlösung?)

Voraussetzung für den Erhalt einer SMS zur Aktivierung der E-POSTBUSINESS API ist der Abschluss der erforderlichen Verträge mit der Deutschen Post sowie die Hinterlegung einer mobilen Rufnummer.

Ein Partner/Eigenversender benötigt verpflichtend eine E-POST Nutzervereinbarung sowie einen API Nutzervertrag. Ein Endkunde benötigt eine E-POST Nutzervereinbarung.

Im Rahmen der Vertragsabschlüsse wurde eine relevante mobile Rufnummer abgefragt und im System hinterlegt.

Wurde die SMS angefordert und man erhält innerhalb weniger Minuten keine Rückmeldung, muss man davon ausgehen, dass die Anforderung nicht richtig abgeschlossen wurde. Gegebenenfalls sind die ursprünglich erfassten Daten nicht mehr korrekt.

Um das Problem zu beheben, muss der Endkunde sich an den Partner/Entwickler der Softwarelösung wenden, der den Prozess und den Kontakt zum Kundenservice der Deutschen Post kennt. Dem Eigenversender liegen die Daten selbst vor.

Innerhalb der Servicezeiten kann der Kundenservice anhand der richtigen Daten die Korrektur durchführen und die Anforderung der SMS muss erneut durchgeführt werden.

Wenn man ein gültiges Laufzeittoken hat, stellt man die PDF/A-Dateien (base64 Daten) sowie die Metadaten zusammen und versendet entsprechend der API Einlieferungsmethode. Die genutzten Dateinamen der PDF/A Dateien müssen dabei pro Aufruf eindeutig sein.

Man kann sowohl mehrere Einlieferungen in einem Aufruf ausführen als auch mehrere Aufrufe über eine [batchID] gruppieren. Die erfolgreiche Einlieferung wird jeweils mit einer eindeutigen [letterID] für jeden eindeutigen Dateinamen quittiert. Die [letterID] ist übergreifend eindeutig.

Es gilt zu beachten, dass Einlieferungen direkt in den Verarbeitungsmodus übergehen. Ein Rückruf der Dokumente nach Einlieferung ist nicht mehr möglich.

Man kann das Laufzeittoken zeitlich einschränken oder auch für verteilte Anwendungen über eine mit dem API Support abgestimmten [vendorSubID] individualisierten Laufzeittoken zentral erzeugen und um es dann selbst zur Nutzung in den eigenen Anwendungen zu verteilen.

Als Partner/Eigenversender hat man in der Regel in der Software einen administrativen Bereich eingerichtet, in dem initiale Maßnahmen (bspw. Aktivierung von Schnittstellen) oder Zugangsdaten (Login) abgebildet werden. Für den Versender setzen sich die initialen Maßnahmen aus

• der Anfrage eines SMS Codes und
• der anschließenden Vergabe des Kennworts zusammen (siehe auch Login-Methoden [smsRequest] und [setPassword]).

Der Endkunde als Versender muss dies als Nutzer der Partnersoftware einmalig durchlaufen und zudem für den Versand initial die API Schnittstelle für seine EKP aktivieren (siehe: Wie aktiviert ein Endkunde die E-POSTBUSINESS API in der Partnerlösung?). Die Versandfunktionen und Statusabfragen der API stehen dann zur Verfügung.

Sobald man das PlugIn zum UploadManagement mit den jeweiligen Optionen anspricht, kann man die entsprechenden Funktionen zum Sammelkorb oder Terminversand nutzen. Eine Aktivierung oder ein Upgrade ist nicht notwendig.

Damit man ein Schreiben definitiv an einem Stichtag versenden kann, muss man im Sammelkorb PlugIn [UploadManagement] die Option [useMinimumQuantity = false] setzen und einen entsprechenden Stichtag (bspw. dueDays) angeben. Der Stichtag kann maximal 31 Tage in der Zukunft liegen.

Sendungen mit [testFlag = true] können nicht zum Testen des Terminversandes genutzt werden.

Man kann beim Stichtag entweder die Anzahl der Tage bis zum Versand [dueDays] angeben, wobei dies immer die Standardeinstellung mit einem Tag ist.

Alternativ kann man ein festes Datum [dueDay] angeben, wobei die Uhrzeit ignoriert wird. Eine andere Alternative ist der Wochentag [dueDayofWeek], mit den möglichen Werten: Mo oder Di oder …So, wobei hier dann bis 14:00 der aktuelle Wochentag betrachtet wird und nach 14:00 der kommende Wochentag.

Wichtiger Hinweis: Der Zählungszeitpunkt 14:00 berücksichtigt ausschließlich die zu diesem Zeitpunkt erfolgreich verarbeiteten Schreiben (LetterStatus 2). Dies muss man in der zeitlichen Kalkulation des Versandes berücksichtigen, so dass dieser entsprechend vorher stattfinden muss. Der Zeitpunkt kann grundsätzlich maximal 31 Tage in der Zukunft liegen.

Die eingelieferten Daten werden validiert, aufbereitet und im fehlerfreien Falle in den Produktions- und Versandprozess überführt. Fehlerhafte Schreiben in einer Masseneinlieferung werden aussortiert, so dass der Rest der Einlieferung weiterverarbeitet werden kann.

Die API quittiert die Einlieferungen mit einer eindeutigen [letterID]. Wenn man eine Fehlermeldung der API erhält (siehe Response Codes), wird die Einlieferung verworfen. Für den Fall, dass man die Quittierung nicht mehr erhält, hat man zusätzlich die Möglichkeit, im ersten Feld der individuellen Dokumentenmerkmalen [custom1] eine eigene ID zu hinterlegen, die man auch über eine eigene Abfrage abrufen kann.

Die verschlüsselt abgelegten Eingangsdaten werden nach 90 Tagen gelöscht.

Ob eine Sendung tatsächlich abgerechnet wird, hängt davon ab, welchen Status sie final erreicht (vgl. zu den Status nachfolgenden Abschnitt „Status“). Es werden nur Sendungen im finalen LetterStatus 4 berechnet. Sendungen, die aus dem LetterStatus 3 heraus einen LetterStatus 99 melden, werden abgebrochen und müssen erneut eingeliefert werden. Diese erreichen nicht den LetterStatus 4 und daher wäre in diesem Fall LetterStatus 99 final.

Die in der E-POSTBUSINESS API erforderlichen Sendungs-Metadaten (insbesondere PLZ, Ort und Land) dienen der optimierten weiteren Verarbeitung im Versandprozess. Abweichungen zwischen diesen Metadaten und den aufgebrachten Empfängeranschriften führen zu Schwierigkeiten bei der Verarbeitung. Dies führt daher im weiteren Prozess zu einer Ablehnung der eingelieferten Sendungen und dient der Sicherstellung der Qualität und der frühzeitigen Ermittlung eventueller Störungen.

Mögliche Optionen: 'Einwurf Einschreiben', 'Einschreiben', 'Einschreiben Rückschein'.
Zu beachten: 'Einschreiben eigenhändig' und 'Einschreiben eigenhändig Rückschein' werden zum 01.01.2025 eingestellt.
Diese Varianten werden bei Angabe zum 01.01.2025 als 'Einschreiben' bzw. 'Einschreiben Rückschein' versendet.

Die von der API bereitgestellten Verarbeitungsschritte mit Zeitstempel dokumentieren, welchen Bearbeitungsstand die Sendung zu welchem Zeitpunkt erreicht hat.

Folgende Statusmeldungen [LetterStatus] werden bereitgestellt:

Status	Verfügbarkeit des Status	Bedeutung
1	Direkt nach dem erfolgreichen Upload der Sendung durch die Software des Partners/Herstellers	Annahme der Sendung: Sendung wurde erfolgreich übermittelt und es wurden keine grundsätzlichen Schema- und Inhaltsverletzungen festgestellt.
2	Je nach aktueller Auslastung der E-POSTBUSINESS API maximal jedoch wenige Minuten nach Annahme der Sendung	Verarbeitung der Sendung: Sendung wurde auf E-Post-Konformität geprüft und ist für den Versand an das Druckzentrum freigegeben.
3	Je nach aktueller Auslastung der E-POSTBUSINESS API innerhalb der nächsten Stunden nach Verarbeitung der Sendung, in der Regel jedoch nach ca. 30 min.	Einlieferung ins Druckzentrum: Übertragung der erfolgreich geprüften Daten in das Druckzentrum. Beispiel: Status 3 | Zeitstempel: Mo 11:00  Übertragung ins Druckzentrum: Montag 11:00 Uhr Hinweis: Sollten bei Einlieferung nachträglich technische Fehler in den PDF-Dokumenten festgestellt werden, führt dies im Druckzentrum zu einem Abbruch. Dies wird zeitnah über den Status 99 und einer entsprechenden Fehlerinformation dokumentiert. Der Status 4 wird nicht erreicht und die Sendungen müssen erneut eingeliefert werden.
4	Meldung ist in der Regel verfügbar 1-2 Tage nach Erreichen von Status 3	Verarbeitung im Druckzentrum: Die Sendung wird als "versendet" vom Druckzentrum an die API zurückgemel-det. Man erhält eine Produktionsquittung mit dem Zeitstempel der Verarbeitung im Druckzentrum.   (Achtung: Zeitversatz bei der Meldung!) Beispiel: Status 4 | Mi 14:00 | Zeitstempel: Mo 17:30  Am Mittwoch um 14:00 Uhr meldet die API den Status 4 unter Angabe des Zeitstempels Montag 17:30 Uhr. D.h., die Sendung wurde am Montag 17:30 Uhr produziert und ist dann direkt in den Versandprozess der Deutschen Post AG übergeben worden. Gemeldet wird diese Information in der API in diesem Beispiel jedoch mit einem Versatz von 2 Tagen am Mittwoch um 14:00 Uhr.
99	Zeitnah nach Feststellung des Fehlers/Problems	Verarbeitungsfehler: Die Verarbeitung wurde abgebrochen. Der Fehler ist vom Softwarehersteller bzw. Kunden zu prüfen und zu korrigieren. (Siehe auch Liste [Error]) Achtung: Der Versand muss erneut angestoßen werden.

Dieser Sendungsstatus wird nach der erfolgreichen und finalen Produktionquittung (LetterStatus 4) durch den Service „Verfolgen Brief (BZE Tracking)“ der Deutsche Post AG zur Verfügung gestellt und dokumentiert den Bearbeitungsstatus im Ziel-Briefzentrum (Briefzentrum Eingang (BZE)). Die so erfassten Statusinformationen zu den Sendungen dokumentieren also, dass die Sendung in der Region der Zieladresse (d.h. im Zielgebiet) eingetroffen ist und im dortigen Briefzentrum bearbeitet wurde. Der nächste und abschließende Schritt ist der Weitertransport an den lokalen Zustellstützpunkt und die Zustellung an den Empfänger. Es wird nicht die Zustellung an den Empfänger durch den Zusteller dokumentiert.
Zu dem Bearbeitungsstatus „im Zielgebiet angekommen“ wird das entsprechende Datum des Bearbeitungstags mitgeliefert. Der Bearbeitungstag beschreibt den Zeitraum von 7.00 Uhr bis 6.59 Uhr am Folgetag und gibt den Tag der Lesung im Zielbriefzentrum an. Dies wird durch den Status „im Zielgebiet angekommen“ gekennzeichnet. Neben dem Bearbeitungstag mit dem Status „im Zielgebiet angekommen“ bzw. „Ziel-Briefzentrum“ enthält der Datensatz zu einer Sendung auch die FrankierID der Sendung. Zudem wird bei Sendungen, die im Rahmen eines Nachsendeauftrags der Bearbeitung im BZE weitergesandt werden, der Status „Nachsendung erfolgt“ bzw. „Nachsendung“ jeweils mit dem entsprechenden Datum vermerkt.
Der Service „Verfolgen Brief (BZE Tracking)“ umfasst alle inländischen hybriden Briefsendungen, die über die E-POSTBUSINESS API versendet werden (ausgenommen Einschreiben). Internationale Briefe, die an ausländische Empfangsadressen geschickt werden, sind von diesem Service ausgenommen.

Die E-POSTBUSINESS API stellt technisch die aktuellsten Statusinformationen aus der Sendungsverfolgung im Briefstatus (LetterStatus) bereit. Zusätzlich befinden sich diese und mögliche vergangene Meldungen (bspw. das Ereignis einer Nachsendung) als Informationshinweis im Fehler-Container (Error Object). Die Bereitstellung und Darstellung dieser Daten ist jedoch von der jeweiligen Umsetzung in der eingesetzten Software abhängig und obliegt somit dem jeweiligen Softwareanbieter.

Der Briefstatus (LetterStatus) stellt dazu folgende Metadaten bereit:

• frankierID (Frankier-ID)
• destinationAreaStatus (BZE / REDIRECTED / keine Information)
• destinationAreaStatusDate (Datum der Bearbeitung im Briefzentrum / keine Information)

Den Status jeder einzelnen Einlieferung kann man über die [letterID] für 400 Tage abrufen. Diesen kann man gezielt

• für eine [letterID]
• mengenbasiert über eine [batchID],
• für einen Einlieferzeitraum oder
• dedizierte letterID’s

abfragen.

Mengenabfragen können auf die fehlerhaften Einlieferungen eingeschränkt werden. Die einzelnen Status ID’s sind in der API beschrieben, wobei der Status 4 die Überführung in den Produktionsprozess darstellt.

Im Falle des Status 99 fand ein Abbruch statt. Zusammen mit den jeweiligen Zeitpunkten (Sendungsannahme, Verarbeitung in in der API, Einlieferung Druckzentrum, Rückmeldung Druckzentrum) ist der jeweilige Statusübergang ersichtlich. Fehler werden genauer über Fehlerobjekte beschrieben.

Die bereitgestellte Eingrenzung des Zeitraumes bezieht sich auf den Zeitpunkt der Sendungsannahme [createdDate] der Dokumente. Da zum einen der Rückmeldezeitpunkt des Produktionsdatums [printFeedbackDate] i.d.R. einen Zeitversatz von 1-2 Tagen hat und somit vom Tag der Sendungsannahme [createdDate] abweicht, ist für eine Prüfungen auf Produktionszeiträume ein entspre-chendes größeres Zeitfenster zur Abfrage vorzusehen und zusammen mit der korrekten Statusbetrachtung eine Filterung auf das Produktionsdatum [printFeedbackDate] vorzunehmen. Die Statusabfragen bieten auch die Möglichkeit, nur die noch in Bearbeitung befindlichen Sendungen (Status 1-3) abzufragen.

Verweilen Sendungen über einen längeren Zeitraum im Status 2, nutzen sie entweder den Sammelkorb oder einen Terminversand. Dies kann man durch Abfrage des [LetterStatus] und der Auswertung des Feedbacks aus dem Sammelkorb PlugIn [UploadManagementFeedback] überprüfen.

Für den dringenden Fall der Anpassung, kann man ausschließlich das Verhalten der Sendungen im Sammelkorb und Terminversand beeinflussen.

Hierbei kann man wartende Sendungen komplett stoppen, sie werden dann in den Fehlerfall überführt (Status 99) oder vorziehen, so dass sie Teil des nächsten Uploads zum Druckzentrum werden.

Sollte jedoch bereits die Übertragung in das Druckzentrum begonnen haben, ist dies nicht mehr möglich. Dies gilt auch für Sendungen, die bereits ins Druckzentrum übertragen wurden.

Veränderungen in den wartenden Sendungen beeinflussen die Mindestmenge, so dass diese sich natürlich ggf. verschieben kann.

Nur Sendungen im Sammelkorb und Terminversand kann man durch die Angabe der betroffenen LetterID’s aufhalten (siehe /api/Letter/CancelQueued).

Die Sendung wird dann mit dem Status 99 versehen und kann grundsätzlich nicht mehr übertragen werden. Die bereits in Übertragung befindlichen Sendungen kann man nicht verändern, hier erhält man eine Fehlermeldung.

Nur Sendungen im Sammelkorb und Terminversand kann man durch die Angabe der betroffenen LetterID’s vorziehen und für die nächstmögliche Übertragung freigeben (siehe /api/Letter/ReleaseQueued).

Die bereits in Übertragung befindlichen Sendungen kann man nicht verändern, hier erhält man eine Fehlermeldung.

Sobald der Versandtermin erreicht ist, geht die Sendung im entsprechenden Zeitfenster in das Druckzentrum. Eine nachträgliche Veränderung ist nicht möglich.

Die Inhalte der „Track And Trace“-Statusmeldungen werden aus dem Elektronischen Auftragsmanagement der Deutschen Post bereitgestellt. Die ausführlichen Dokumentationen und Code Tabellen sind auf der Webseite unter Download einsehbar.

Detailliertere Erklärungen zur Bedeutung der Statusinformationen werden auch hier bereitgestellt.

Über die Statusabfrage für Einschreiben [get /api/Letter/Registered] erhält man über einen definierten Zeitraum den Status der Einschreiben, wobei man dies auf die offenen Rückmeldungen einschränken kann.

Der letzte Status und der Zeitstempel sind als eigene Attribute gelistet [registeredLetterStatus], [registeredLetterStatusDate]. Die Historie findet sich in der [errorList] als InfoObjekt (I701) in der ermittelten Reihenfolge.

Über die [EinschreibenID] der Sendung wird zusätzlich regelmäßig der aktuelle Status ermittelt. Eine dedizierte EinschreibenID kann nicht übergeben werden. Die über die API zurückgemeldeten möglichen Inhalte des Status sind unter Sendungsstatus Einschreiben (JSON) gelistet. Dort sind auch die Statuscodes hervorgehoben, die einen finalen Endzustand darstellen.

Über ein Testflag kann man eine Verarbeitung (Validierung, Aufbereitung, etc.) ohne eine Überführung in das Druckzentrum auslösen. Der jeweilige Status mit den Fehlerobjekten gibt Auskunft über die Verarbeitungsmöglichkeit oder Ablehnungen.

Zusätzlich kann zur Qualitätskontrolle für 48h via [letterID] das erzeugte PDF über die API Funktion [get /api/Letter/TestResult] abfragen. Alternativ kann man das aufbereitete Dokument an eine individuelle E-Mail Adresse senden.

Die Testverarbeitung ist für eine administrative Vorabprüfung vorgesehen, eine Einbindung in den Produktivversand wird nicht unterstützt.

Für die Einhaltung der jeweiligen Datenschutzrichtlinien bspw. der DSGVO bei Sendungen ist immer der Versender verantwortlich. Darüber hinaus kann man auch die für die Dokumente geltenden Sperrflächen in diesen Qualitätstest einarbeiten lassen.

Man kann die Funktionsbereitschaft [GET /api/Login/HealthCheck] der API jederzeit über den Login Controller abfragen, eine Anmeldung ist hierfür nicht notwendig. Mögliche Wartungsfenster werden hierüber ebenfalls bekannt gegeben.

Über die Prüfung der Funktionsbereitschaft [GET /api/Login/HealthCheck] im Login Controller der API werden die möglichen Wartungsfenster bekannt gegeben. Ein Login ist hierfür nicht notwendig.

Mit Hilfe des Vendor Controllers kann man sowohl die Anzahl der erfolgreichen Sendungen, bezogen auf einen Zeitraum sowie auch mögliche fehlerhafte Sendungen ermitteln.

Der Status der erfolgreich produzierten Schreiben [LetterDetailsByDay] wird gruppiert in reduzierter Form als [LetterDetailsPrintedByDay] für einen begrenzten Zeitraum bereitgestellt. Hierbei bezieht sich die Eingrenzung des Zeitraumes auf das Produktionsdatum [printFeedbackDate].

Für die fehlerhaften Schreiben [LettersWithError] wird der [LetterStatus] verwendet, wobei dessen Inhalt reduziert und auf die Fehler fokussiert ist. Hierbei bezieht sich die Eingrenzung des Zeitraumes auf den Zeitpunkt der Sendungsannahme [createdDate].

Die [letterID] kann für die weitere Recherche genutzt werden, [fileName], [testMail], [registeredLetterID] und [custom1-5] werden leer zurückgeliefert.

Optional kann durch Ausschalten des Parameters [hideEKP] in [custom5] die für das Dokument verwendete EKP hinterlegt werden. Die [errorList] beinhaltet, analog zu den Ergebnissen der Statusabfragen, die ursächlichen Fehler und Informationen.

Zusätzlich zu [LetterDetailsByDay] kann man mit [LetterDetailsByDayAsCsv] die Daten der versendeten Briefe als CSV erhalten.

Mit dem Zeitpunkt der Sendungsannahme [createdDate] können alle Dokumente abgefragt und deren Status mit Zeitstempel ermittelt werden, unabhängig davon, ob sie produziert wurden oder aufgrund von Fehlern abgelehnt wurden. Dieser Zeitstempel wird zum Zeitpunkt der Sendungsannahme vergeben (Status 1 bzw. Status 99 bei Fehler).

Der Zeitpunkt der Verarbeitung [processedDate] zeigt, wann das jeweilige Dokument den Systemprüfungen unterzogen wurde und weiterverarbeitet wurde oder aber Fehler erzeugt hat. Dieser Zeitstempel wird nach der Verarbeitung vergeben (Status 2 bzw. Status 99 bei Fehler).

Der Übergang in den Produktionsprozess wird über den Einlieferzeitpunkt Druckzentrum [printUploadDate] dokumentiert. Dieser Zeitstempel wird nach der erfolgreichen Bereitstellung vergeben (Status 3).

Die Rückmeldung der Verarbeitung im Druckzentrum [printFeedbackDate] stellt den Produktionszeitpunkt des Dokumentes dar. Dieser Zeitstempel wird i.d.R. erst nach 1-2 Tagen aus dem Druckzentrum zurückgemeldet. Zur Validierung von Produktionsmengen auf der Rechnung sollte dieser Zeitstempel genutzt werden (Status 4 bzw. Status 99 bei Fehler).

Das verwendete Briefformat (Standard, Kompakt, Groß) ergibt sich, aus der Blattzahl und dem Gewicht des Briefes. Geht man von unserem Papier mit 80g/m² aus dann wiegt ein Blatt knapp 5g, ein Umschlag ebenso. Tinte ist dabei vernachlässigbar bzw. wird nur bei der Berechnung beim Großbrief mit 94 Blatt berücksichtigt.

Nachfolgend die Beispiele zur Gewichts- und somit Formatermittlung des Briefes:

• Standard bis 20g, 1 bis max. 3 Blatt
   bei 3 Blatt: 3 x 5g = 15g + Umschlag = 20g
• Kompakt bis 50g, 4 bis max. 9 Blatt
   bei 9 Blatt: 9 x 5g = 45g + Umschlag = 50g
• Groß bis 500g (inkl. 10 Blatt) 10 bis max. 94 Blatt
   bei 94 Blatt: 94 x 5g = 470g + Umschlag und Toner = 500g

Bei Sendungen, die über einen E-POST-Kanal eingeliefert werden, wird automatisch eine „Digitale Kopie“ erstellt. Empfänger bekommen also weiterhin ihre Post in ihren Briefkasten, können aber ihre Sendungen zusätzlich auch digital empfangen und lesen, sofern sie sich für diesen Service registriert haben. Ist das nicht gewünscht, z.B. bei Sendungen von Berufsgeheimnisträgern gemäß §203 StGB, dann kann man das unterbinden. Dazu reicht eine formlose eMail an den Kundenservice der E-POST mit dem Hinweis „Prozess Opt-Out DiKo“ und die technische Umsetzung erfolgt innerhalb von 2 Wochen. Der Kundenservice bestätigt die Umstellung dann per eMail. Nähere Informationen zur digitalen Kopie finden sich in der Leistungsbeschreibung der E-POSTBUSINESS API
„Leistungsbeschreibung der E-POSTBUSINESS API “.

Es gibt eine Mindestmenge an Metadaten, die jedes Dokument für eine ordnungsgemäße Verarbeitung bereitstellen muss. Sind diese Metadaten fehlerhaft oder weichen diese von den aufgedruckten Daten ab, führt dies in der Regel zu Verarbeitungsfehlern im Druck- oder Zustellprozess.

Für eine vereinfachte Verarbeitung wird ein leerer Ländercode als „Deutschland“ interpretiert. Für Auslandssendungen muss man jedoch zwingend, neben der korrekten Anschrift, zusätzlich den korrekten Ländercode befüllen.

Es stehen bis zu fünf individuelle Felder [custom1-5] zur Verfügung, die man in der Einlieferung belegen kann und die in der Statusabfrage zurückgeliefert werden.

Wenn ein Dokument versendet wird, müssen immer die gesamten Anschriftendaten mitgeben werden, um die korrekte Zustellung zu gewährleisten.

Die Anschrift setzt sich immer aus einer Empfängerbezeichnung (bspw. Anrede, Vorname und Nachname, Firma, etc.) und der Adresse, bestehend aus Straße, Hausnummer, Adresszusatz, alternativ Postfach sowie PLZ und Ort, zusammen.

Für Auslandssendungen muss auch der Ländercode angegeben werden. Diese Kombination wird in den Metadaten gespiegelt. Hat man eine Empfängerbezeichnung, die sich nur über eine Zeile erstreckt, dann ist dies [adressLine1] und bspw. für Anrede und Namen oder Firmenbezeichnungen vorgesehen.

Die [adressLine2] würde bspw. hierbei schon die Straße und die Hausnummer oder das Postfach beinhalten. Bei mehrzeiligen Empfängerbezeichnungen verschiebt sich dann der Inhalt der [adressLine2] entsprechend bis maximal zur letzten [adressLine5].

Diese Metadaten werden auch für ein Deckblatt herangezogen, wobei man zusätzlich noch die Metadaten des Versenders (bspw. [senderAdressLine1], [senderStreet], etc.) befüllen muss.

Es gibt für die Absenderzeile kein eigenes Feld für ein Postfach, dafür kann das Feld [senderStreet] genutzt werden. Optional kann man die komplette Versenderadresse in einer Zeile übergeben [senderAdressLineComplete], anstelle der einzelnen Versenderfelder und so das Postfach hinterlegen.

Wenn man keine Anschriften-Metadaten bereitstellen kann, bietet der Automover eine Möglichkeit, dennoch diese nationalen Schreiben zu versenden. (siehe hierzu „Wie kann man automatisch nationale Anschriften repositionieren?“).

Das Einschreiben [registeredLetter] ist, mit Bezug auf das zu versendende Dokument, eine Briefzusatzleistung. Nur im Falle des Rückscheins (bspw. registeredLetter = „Einschreiben Rückschein“) benötigt man die Daten zur Rücksendeadresse. Diese wird jedoch seit dem 01.10.2022 nicht mehr aus den Metadaten entnommen, sondern automatisch aus der Absenderzeile extrahiert. Die ursprünglich für den Rückschein erforderlichen Metadaten-Felder mit den Empfängerdaten Einschreiben [registeredLetterAdressLine1 bis registeredLetterCity] werden daher nicht mehr ausgelesen und sollten leer gelassen werden. WICHTIG: Es ist zwingend immer eine Absenderzeile anzugeben, aus der im Falle des Einschreibens mit Rückschein automatisch der Rückschein mit den Empfängerdaten befüllt wird.

Es steht ein eigenes Feld für die Hinterlegung einer Kostenstelle zur Verfügung [costCenter]. Der Eintrag muss alphanummerisch sein. Die hier hinterlegten Kostenstellen werden in der Monatsrechnung berücksichtigt und die Rechungsbeträge werden entsprechend aufgeschlüsselt.

Die in der E-POSTBUSINESS API erforderlichen Sendungs-Metadaten (insbesondere PLZ, Ort und Land) dienen der fehler- und verzögerungsfreien weiteren Verarbeitung im Versandprozess. Abweichungen zwischen diesen Metadaten und den aufgebrachten Empfängeranschriften führen zu Verstößen gegen diese Vorgabe. Dies kann im weiteren Prozess zu Verzögerungen in der Zustellung bis hin zur Ablehnung und Rückführung der Sendungen führen.

Sendungen, bei denen die Metadaten von den Informationen auf der Empfängeranschrift abweichen, werden daher beim Upload abgelehnt und nicht produziert. Diese Sendungen müssen korrigiert und erneut eingeliefert werden.

Die Metadaten zu den eingelieferten Sendungen, die über die API abgerufen werden können, werden nach 400 Tagen gelöscht. In diesem Zeitraum kann man sich die Informationen wie folgt aus der API ziehen:

• Über den Vendor Controller (GET LetterDetailsByDay) kann man die erfolgreich versendeten Schreiben der letzten 400 Tage ermitteln.
• Der Zeitraum der Auswertung kann man auf einen definierten Datumsbereich einschränken.
• Man kann die benötigten Sendungen anhand der Kundennummer (EKP) filtern.

Die der API übergebenen PDF Dokumente müssen dem DIN A4 Hoch-Format entsprechen. Abweichungen vom DIN A4 Hoch-Format können nicht verarbeitet werden.

Insbesondere die PDF Dokumente, die nicht dem PDF/A Format entsprechen, werden systemisch aufbereitet und sind daher in vorangehenden Tests (Testmodus der E-POSTBUSINESS API) zu prüfen, da in der Aufbereitung beispielweise fehlende Fonts durch Standards ersetzt werden oder Transparenzen in Bildern nicht das gewünschte Ergebnis spiegeln. Diese Rahmenbedingungen können eine einwandfreie Verarbeitung einschränken oder zur Ablehnung in der Verarbeitung führen.

Es sind Einlieferungen von einer oder mehreren Sendungen möglich. Die einzuliefernden PDF-Dateien dürfen pro Sendung 20 MB bzw. mehrere Sendungen per Request 300 MB nicht überschreiten. Hochauflösende Grafiken und/oder Dokumentenscans führen in der Regel zu einer übergroßen Datei, so dass hier die Auflösung (maximal 300 dpi) zu prüfen und ggf. zu reduzieren ist. Die maximale Seitenanzahl pro Sendung sind 94 Seiten für Simplex und 188 Seiten für Duplex, so dass maximal 94 Blätter nicht überschritten werden.

Die API verwendet für die automatisiert auf der ersten Seite oder Deckblatt aufgebrachten Anschriftendaten die Schriftart Arial in Schwarz und die Fontgröße 6 für die Absenderzeile sowie die Fontgröße 9 für die Empfängeradresse.

PDF Dokumente, die nicht als PDF/A bereitgestellt wurden, werden überarbeitet und fehlende Fonts nach Möglichkeit durch Standards ersetzt. Für die von der API automatisiert genutzten Schriftarten sind die Lizenzbestimmungen erfüllt. Grundsätzlich ist man als Versender für die Lizensierung der verwendeten Schriftarten/Fonts im Dokument verantwortlich.

Man kann ein Standard-Deckblatt erzeugen, das den Absender und Empfänger aus den Metadaten der Einlieferung enthält. Darüber hinaus kann man alternativ ein eigenes Deckblatt als base64 PDF/A bereitstellen, das dann mit den Metadaten der Einlieferung befüllt wird. Es ist zu beachten, dass das Deckblatt in der Produktion berechnet und ggf. zur Verwendung und Berechnung des nächstgrößeren Briefformats führt (bei Überschreiten von 3 bzw. 9 Blättern).

Grundsätzlich hat ein Blatt immer zwei Seiten, Vorder- und Rückseite. Abhängig von der Druckoption (einseitig = Simplex/ beidseitig = Duplex) kann die Anzahl der Blätter aus der rückgemeldeten Seitenzahl ermittelt werden.

Im Falle von Simplex ist die Blattzahl identisch der Seitenzahl, für Duplex muss dies dann entsprechend halbiert und aufgerundet werden.

Bei Nutzung der Deckblattoption wird das Deckblatt bei der gemeldeten Seitenanzahl berücksichtigt.

Sowohl für nationale als auch internationale Sendungen muss eine einzeilige Absenderangabe mit Adresse im Inland (Deutschland) an der vorgeschriebenen Position (siehe Sperrflächenschablone V3) aufgebracht werden. Details sind den AGB E-POST, Ziffer 6.8, zu entnehmen. Die Absenderzeile muss den Absender vollständig beinhalten und darf nicht aus dem Fenster herauslaufen. Dies kann man mittels der API Testfunktion und dem Einblenden der Schablone überprüfen.

Wegen der erforderlichen Maschinenlesbarkeit ist die Absenderzeile nur einzeilig anzugeben. Ggf. müssen hier die Absenderdaten abgekürzt oder die Schrift im zulässigen Maß verkleinert werden.
Der Brief wird zwar nicht abgelehnt, doch wenn der Brief nicht zustellbar sein sollte, dann gibt es vielleicht Probleme, auf jeden Fall Verzögerungen beim Rückversand an den Absender. Bei Einschreiben mit Rückschein sollte man auf jeden Fall die Vorgaben einhalten, weil die Rücksendeadresse des Rückscheins aus der Absenderzeile gelesen wird.

Eine Verletzung der Sperrflächen im Anschriftenfeld (gemäß Briefschablone V3) führt zu einem Fehler und somit zur Ablehnung der Sendung. Die Fläche für die DV-Freimachung sowie die Lesbarkeit der Absender- und Empfängerdaten sind ein wesentlicher Aspekt für die Produktionsfähigkeit der Sendungen. Achtung: Auch eine transparente Grafik, die in das Sperrfeld ragt, wird als Fehler gewertet.

Eine Verletzung der Sperrflächen am linken Rand wird nur per Warnung angemerkt. Eine sonst E-POST konforme Sendung wird dennoch produziert, aber Inhalte in dieser Randfläche vor der Produktion geweißt.

Mit Hilfe der Automover Funktion kann man das vorhandene Anschriftenfeld (Sender- und Empfängeradresse) durch die bereitgestellten Metadaten überblenden. Diese erweiterte Funktion wird als PlugIn „Automover“ bereitgestellt.

Hierzu muss man zum einen den Automover aktiveren [useAutomover = true] und zum anderen im JSON die Metadaten ([senderAdressLine1], [senderStreet], [senderZipCode], [senderCity], [addressLine1-5], [zipCode], [city]) bereitstellen.

Man muss beachten, dass auf der ersten Seite der PDF der gesamte Sperrbereich aus der Sperrflächenschablone V3 ( Briefschablone ) geweißt und dann mit den mitgegebenen Daten überschrieben wird.

Eine Kombination mit der Deckblatt-Funktion [coverLetter = true] erzeugt ein Deckblatt, führt diese Funktion jedoch nicht aus und wird als Info im Error Objekt dokumentiert. Man kann mit der Testfunktion der API (siehe „Wie weiß man, ob ein Brief versandt werden kann?“) das Ergebnis des Automover prüfen.

Mit Hilfe der Automover Funktion kann man das vorhandene nationale Anschriftenfeld (Sender- und Empfängeradresse) automatisch repositionieren.

Diese erweiterte Funktion wird als PlugIn „Automover“ bereitgestellt. Hierzu muss man zum einen den Automover aktiveren [useAutomover = true] und zum anderen im JSON die Metadaten [addressLine1], [zipCode] und [city] mit definierten Werten (siehe auch: Schema swagger Dokumentation „Automover“) befüllen.

Voraussetzung zur Repositionierung ist, dass Adressdaten des Absenders und Empfängers in einem Bereich als erkennbarer Text auf der ersten Seite vorhanden sind. Dort werden diese Daten ausgelesen, wobei dieser Bereich vorgegeben ist, aber auch über entsprechende Koordinaten angepasst werden kann.

Kann keine Empfängeradresse ausgelesen werden, führt dies zu einem Fehler. Vorhandene Anschriften-Metadaten werden für die Suche nicht berücksichtigt.

Standardmäßig werden die ermittelten Adressdaten auf dem geweißten Sperrbereich aus der Sperrflächenschablone V3 ( Briefschablone ) der ersten Seite des PDF aufgebracht. Mögliche Inhalte werden somit überblendet. Die Adress-Metadaten [zipCode] und [city] werden mit den ermittelten Werten belegt und sind im LetterStatus-Objekt zu finden.

Man kann mit der Testfunktion der API (siehe „Wie weiß man, ob ein Brief versandt werden kann?“) das Ergebnis des Automover prüfen.

Eine Kombination mit Einschreiben [registeredLetter] und/oder der automatischen Erzeugung eines Deckblattes werden nicht unterstützt, da hierfür die notwendigen Metadaten explizit vorliegen müssen.

Die meisten Auslandssendungen benötigen im Empfängerland eine Postleitzahl. Für Länder, die keine Postleitzahlen benötigen, ist das Pflichtfeld der Postleitzahl [zipCode] mit einer Mindestlänge von drei Leerzeichen zu befüllen.

Die Entscheidung zur korrekten Befüllung der Postleitzahl liegt beim Versender. Für Inlandssendungen ist die korrekte Postleitzahl anzugeben, die Befüllung mit Leerzeichen ist daher nicht zulässig.

Für den Versand von Dialogpost-Sendungen über die E-POSTBUSINESS API hat eine Implementierung der entsprechenden Funktionalitäten gemäß der Implementierungsrichtlinie Dialogpost zu erfolgen. Dies ist ein optionales Zusatzangebot der E-POSTBUSINESS API. Man kann als API Nutzer auch ausschließlich den hybriden Briefversand der E-POST nutzen, ohne die Dialogpost zu implementieren.

Die Entscheidung zur korrekten Befüllung der Postleitzahl liegt beim Versender. Für Inlandssendungen ist die korrekte Postleitzahl anzugeben, die Befüllung mit Leerzeichen ist daher nicht zulässig.

Die E-POSTBUSINESS API stellt sowohl als Kernleistung den hybriden Briefversand der E-POST als auch alle anderen notwendigen Funktionen für den ordnungsgemäßen Betrieb in meiner Software bereit. Eine ausschließliche Implementierung der Dialogpost, ohne die Kernfunktionen der E-POSTBUSINESS API zu implementieren, ist nicht möglich.

Die Methoden der Dialogpost unterliegen, neben dem grundsätzlichen Entwicklungsmodus der E-POSTBUSINESS API, einem eigenen Entwicklungsmodus.

Der Wechsel vom Entwicklungsmodus zum Produktivmodus für die Dialogpostmethoden wird durch den API Support vorgenommen. Wenn die Dialogpost-Entwicklung der API abgeschlossen ist, wendet man sich zur Produktivschaltung an den Kontakt des API Supports.

Man meldet die API-Nutzerdaten

• Unternehmen
• vendorID und
• EKP

Nach Prüfung der Angaben und einer erfolgreichen Sichtung der Benutzerinteraktionen (gemäß der vertraglichen Regelung), schaltet der API-Support die Dialogpost in den Produktivmodus. Erst dann können die Kampagnen finalisiert und übermittelt werden. Der API Support gibt über diese Produktivschaltung eine Rückmeldung.

Die Dialogpost ist ein additiver Teil der E-POSTBUSINESS API. Nur eine produktive E-POSTBUSINESS API ermöglicht mir den Zugang zu den additiven Dialogpostmethoden und deren Produktivschaltung.

Jeder aktive E-POST Nutzer kann Dialogpost Sendungen versenden. Eine zusätzliche Freischaltung/Aktivierung ist nicht notwendig.

Wenn ein E-POST Nutzer sich in seiner Software aktiviert hat, wird keine weitere Aktivierung für die Nutzung der Dialogpost benötigt.

Neben dem ordnungsgemäßen Werbemittel werden die Zielanschriften in ausreichender Zahl, die Kundennummer (EKP) der E-POST Nutzers, die Auftraggeber-/Rechnungsanschrift, der Absender, das Zieldatum sowie die Kontaktdaten des Auftraggebers benötigt.

Damit entsprechende Konditionen optimal bereitgestellt werden können, benötigt ein Versand von Dialogpostsendungen entsprechenden Vorlauf (siehe hierzu das Schema [Campaign palDate]). Die dort angegebene Vorlaufzeit beschreibt das Datum der Postauflieferung, nicht das Zustelldatum.

Die Dialogpost Erweiterung bietet Vorab-Prüfungen für das Werbemittel mit den zugehörigen Anschriften [/api/Campaign/SampleRequest] und [/api/Campaign/SampleData] als auch eine Kostenprüfung [/api/Campaign/CostEstimate]. Diese Daten stehen teilweise nur begrenzte Zeit zur Verfügung und sind von den Kampagnen getrennt.

Unabhängig der Vorab-Prüfung oder im Rahmen einer Kampagne wird das bereitgestellt Werbemittel auf die Einhaltung der Formatvorgaben geprüft. Hierbei wird ein Auszug (siehe [/api/Campaign/SampleRequest] oder [/api/Campaign/{id}/ConfirmRequest]) aus den jeweils bereitgestellten Anschriften in das Werbemittel aufgebracht, so dass anschriftenabhängige Formatverletzungen oder andere Effekte im möglichen Druckbild des Werbemittels vom E-POST Nutzer validiert werden können.

Die Vorab-Kalkulation bietet eine einfache Möglichkeit, in Abhängigkeit der Sendungsmenge den Kostenrahmen zu evaluieren. Die Preisberechnung im Rahmen der Kampagne basiert auf den final bereitgestellten Auftragsdaten (bspw. Anschriften und deren Anzahl, Farbwahl als Produktionsvorgaben, etc.) und stellt die für den E-POST Nutzer zu erwartenden Kosten für eine Beauftragung gemäß den AGB Dialogpost dar. Die Vorab-Kalkulation ist unverbindlich, Unterschiede in der finalen Kostenberechnung sind möglich (bspw. bei nicht produzierbaren Sendungen im Rahmen des Auftrags).

Eine Kampagne besteht aus ihrer ID, dem freiwählbaren Namen aus dem Werbemittel, den zugehörigen Empfängeradressen, den Rechnungsempfänger- und Absenderdaten, der EKP des E-POST Nutzers sowie aus dem Auflieferungsdatum. Die Kampagne selbst wird durch eine eindeutige ID [campaignID] referenziert und ihr unterschiedlicher Status kann geprüft werden (siehe [CampaignStatus]).

Die finale Beauftragung beinhaltet aus den Kampagne Daten die ID und den Namen, die Rechnungsempfängerdaten und das Absenderdatum, Kontaktdaten, die Produktionsdaten (bspw. Anzahl Seite, Farbewahl, Anzahl Schreiben, etc.), Geschäftsbedingungen, Preise und einen Zeitstempel.

Neben den Vorabprüfungen, welche explizit zur Evaluierung von Werbemitteln und Kosten zu verwenden sind, ist ein definierter Prozessablauf für die Beauftragung einer Kampagne einzuhalten.

Die eröffnete Kampagne kann bis zur Beauftragung noch jederzeit verworfen werden [/api/Campaign/{id}/Cancel]. Die Kampagne muss man mit ihren Daten öffnen [/api/Campaign/Open].

Danach muss man die Generierung der Werbemittel [/api/Campaign/{id}/ConfirmRequest] zur Validierung anstoßen. Im vorgegebene Zeitfenster ist dann das generierte Werbemittel abzurufen [/api/Campaign/{id}/ConfirmData] und dem E-POST Nutzer zur Validierung zuzuführen.

Wenn alle grundlegenden Daten für eine Preiskalkulation und spätere Beauftragung vorliegen, wird die Kalkulation [/api/Campaign/{id}/FinalizeInfo] mit den finalen Auftragsdaten angestoßen und man erhält die Informationen [CampaignFinalizeInfo] zur finalen Beauftragung.

In einem Benutzerdialog lässt man über OptIn Verfahren die Validität der generierten (Beispiel) Werbemittel, die sichtbar präsentierten finalen Auftragsdaten, die Akzeptanz der Geschäftsbedingungen (URL Bestandteil der finalen Auftragsdaten und über bspw. externen Browser ansteuerbar) explizit als kostenpflichtige Leistung bestätigen und beauftragen.

Diese finale Beauftragung [/api/Campaign/{id}/Finalize] ist im angegebenen Zeitfenster mit Hilfe der bereitgestellten finalen Beauftragung [CampaignFinalizeInfo] durchzuführen.

Eine Kampagne kann nach der Eröffnung nicht mehr geändert werden. Solange Sie nicht beauftragt [/api/Campaign/{id}/Finalize] wurde, kann sie jedoch jederzeit verworfen [/api/Campaign/{id}/Cancel] und somit neu erzeugt werden [/api/Campaign/Open].

Solang man nicht die Kampagne beauftragt oder abgebrochen hat, bzw. sie zeitbedingt abgebrochen wurde, kann man jederzeit die Werbemittel auch mit jeweils anderen Adresspositionen generieren [/api/Campaign/{id}/ConfirmRequest]. Dabei werden mögliche bisherige Dokumente überschrieben.

Solange man nicht die Kampagne beauftragt oder abgebrochen hat, bzw. sie zeitbedingt abgebrochen wurde, kann man jederzeit die Werbemittel abrufen [/api/Campaign/{id}/ConfirmData].

Dabei werden die Dokumente des letzten Generierungsaufrufes für Werbemittel [/api/Campaign/{id}/ConfirmRequest] bereitgestellt.

Solang man nicht die Kampagne beauftragt oder abgebrochen habe, bzw. sie zeitbedingt abgebrochen wurde, kann man jederzeit die Beauftragungsdaten [CampaignFinalizeInfo] einer Kampagne abrufen.

Nur mit dem letzten Aufruf kann auch die Beauftragung [/api/Campaign/{id}/Finalize] durchgeführt werden.

Der Status einer Kampagne kann dediziert [/api/Campaign/{id}/Status] oder über einen Zeitraum [/api/Campaign/Date] abgerufen werden, wobei die abrufbaren Daten unterschiedlich lange verfügbar sind. Man erhält somit einen genauen Überblick über den aktuellen Verarbeitungsstatus.

Solange man die Kampagne nicht beauftragt oder abgebrochen hat, bzw. sie zeitbedingt abgebrochen wurde, kann man sie abbrechen.

Mit dem zurückgelieferten Status der Kampagne sowie der oder den Fehlermeldungen (Error Objekten) führt man den Benutzer in der Software, damit man zwischen der Problemlösung Software und Produktionsproblem unterscheiden kann.

Im Falle, dass man zur Schnittstelle oder der E-POST Nutzer zur Druckbzw. Der Zustellung Unterstützung durch den Support benötigt, ist hierzu die Kundennummer (EKP) des E-POST Nutzers, der Ansprechpartner, die konkrete [campaignID] und der Status der Kampagne aus dem Status (siehe [/api/Campaign/{id}/Status] oder [/api/Campaign/Date]) bereitzuhalten.

Mit Hilfe des Vendor Controllers kann man sowohl die Anzahl der erfolgreichen Dialogpost Sendungen bezogen auf einen Zeitraum, als auch mögliche fehlerhafte Sendungen ermitteln.

Der Status der produzierten Dialogpost Schreiben wird gruppiert in reduzierter Form als [CampaignDetails] für einen begrenzten Zeitraum bereitgestellt. Die fehlerhaften Kampagnen sind über ihren Status und der entsprechenden [errorList] ersichtlich.

Die Eingrenzung des Zeitraumes bezieht sich auf das Erstelldatum einer Kampagne [CampaignStatus: 1 – initalized].

Man kann zu jeder Kampagne eine [vendorSystemInformation] hinterlegen, in der man z.B. die Software Version ablegt. Diese abgelegte [vendorSystemInformation] erhält man im [CampaignStatus] zurück.

Mit PREMIUMADRESS erfahren Sie, welche Ihrer Sendungen nicht zugestellt werden konnten und erhalten wertvolle Informationen über Adresskorrekturen, Umzüge und Gründe von Unzustellbarkeiten. Die Zusatzleistung PREMIUMADRESS steht in der E-POSTBUSINESS API in den Varianten Basis und Report zur Verfügung. Diese bieten folgende Bestandteile:

• Unzustellbarkeitsinformation
• Anschriftenkorrektur
• Verstorbeneninformation
• Umzugsadresse, Umzugsinformation

Wir bitten zu beachten, dass über die E-POSTBUSINESS API eine sehr einfache, standardisierte Möglichkeit der Nutzung von PREMIUMADRESS geboten wird. Diese ist in ihrem Umfang begrenzt, so dass ausdrücklich nicht das gesamte Leistungsspektrum von PREMIUMADRESS zur Verfügung steht. Insbesondere ist die Nutzung weiterer optionaler Leistungen (Unzustellbarkeitsinformation mit Datenbankbestätigung, Adressrecherche) nicht möglich.

Die für diese Leistungen im Einzelnen ggf. erhobenen Kosten sind auf der PREMIUMADRESS Produktseite, dort auf der Seite „Leistungen“ und dort unter „Leistungen und Preise“ aufgeführt.

PREMIUMADRESS kann für nationale Briefsendungen, ausgenommen Einschreiben, beauftragt werden. Für Dialogpost-Sendungen ist eine Nutzung von PREMIUMADRESS nicht möglich.

Es ist zu beachten, dass nicht zustellbare Sendungen vernichtet werden. Eine Rückführung der Sendung an den Absender ist ausgeschlossen. Selbstverständlich werden Sendungen, deren Empfänger einen Nachsendeauftrag gestellt haben (bspw. im Umzugsfall), entsprechend an die angegebene neue Adresse nachgesendet.

Die Leistung muss über das PremiumAdress PlugIn für jede Sendung einzeln beauftragt werden. Die Rückmeldungen erfolgen zeitversetzt und müssen aktiv an der API abgerufen werden.

Die Inanspruchnahme von PREMIUMADRESS verursacht keine fixen Kosten. Zu zahlen sind nur bereitgestellte Adressinformationen (je Datensatz), sofern sie kostenpflichtig sind. Die ggf. anfallenden Kosten fließen in die monatliche Abrechnung der E-POST Leistung ein. Auf der Rechnung werden alle erbrachten PREMIUMADRESS-Leistungen ausgewiesen, sowohl kostenfreie als auch kostenpflichtige. Eine gesonderte Rechnung für PREMIUMADRESS wird nicht erstellt.

Eine detaillierte Aufstellung der kostenpflichtigen und kostenfreien Leistungen ist auf der PREMIUMADRESS Produktseite, dort auf der Seite „Leistungen“ und dort unter „Leistungen und Preise“, aufgeführt.

Sobald man das PlugIn für PremiumAdress mit der jeweiligen Option (Basis oder Report) der jeweiligen Sendung mitgibt, wird die Leistung beauftragt und dementsprechend ein PREMIUMADRESS Label auf die Sendung aufgebracht.

Da alle Leistungen der API immer sendungsbasiert sind, kann man in einem Upload unterschiedlichste Sendungen mit unterschiedlichen Zusatzleistungen beauftragen. Diese Leistung kann nur für nationale Briefsendungen, ausgenommen Einschreiben, beauftragt werden (nicht für Dialogpost). Ein zusätzlicher Vertrag ist nicht notwendig.

Die Sendungsinformationen von PREMIUMADRESS werden durch das PlugIn [PremiumAdress-Feedback] zeitversetzt sowohl im [LetterStatus] als auch als eigenständige Abfrage bereitgestellt. Der Aufbau und der Inhalt der PREMIUMADRESS Rückmeldung entsprechen den Beschreibungen im PREMIUMADRESS Handbuch ( PREMIUMADRESS Download-Seite ).

Die Ergebnisse von PREMIUMADRESS werden zeitversetzt bereitgestellt. Sie unterliegen den Bearbeitungszeiten von PREMIUMADRESS und sind dann sowohl im [LetterStatus] als auch als eigenständige Abfrage (siehe [Letter/PremiumAdressFeedback]) verfügbar.

 +49 7161 65159-90
Mo-Fr 09:00 - 12:00 Uhr und 13:00-17:00 Uhr
eMail: EPostApiSupport@docuguide.com

 +49 228 4333 112 (Mo-Fr 08:00-20:00 Uhr)
Mo-Fr 09:00 - 12:00 Uhr und 13:00-17:00 Uhr
eMail: e-post@deutschepost.de

Bitte wenden Sie sich direkt an den Shop der Deutschen Post AG über den Kontakt-Link in der Auftragsbestätigung .

Bitte wenden Sie sich bei Fragen zur Abrechnung an die auf Ihrer Rechnung angegebenen eMail- Adresse. Nennen Sie uns in Ihrer eMail Ihre Kundennummer (EKP) und die entsprechende Rechnungsnummer der betroffenen Rechnung.

Bitte wenden Sie sich bei Laufzeit- und Qualitätsproblemen Ihrer Sendungen an unseren Kundenservice unter e-post@deutschepost.de. Bitte geben Sie hierbei möglichst die Frankier IDs der betroffenen Sendungen an, die für eine nähere Recherche, insb. im Hinblick auf die Laufzeit, benötigt werden.

Mit dem Abruf [api/Login/HealthCheck] lassen sich der Verfügbarkeitsstatus der API, die Bereitstellung von Wartungsfenstern, sowie mögliche Störungen abfragen. Ein Login ist hierfür nicht notwendig.

Alternativ kann man diesen Status auch über den folgenden Link den Status abfragen:

https://api.epost.docuguide.com/health

Achtung: Sendungen mit Fehler sind im finalen Zustand und werden nie produziert. Diese müssen per Upload nochmals hochgeladen werden, unabhängig wer den Fehler verursacht hat.

Der zurückgelieferte Status des Dokumentes und ggf. die Fehlermeldungen (Error Objekte) geben klare Hinweise zum Fehlerbild, so dass zwischen Softwareproblemen und Druck-/Zustellproblemen unterschieden werden kann.

Wendet man sich als API-Nutzer an den API-Support aufgrund auftretender Fehler beim Briefversand, sind hierzu die eigene EKP, der Name des Kontaktes nebst vendorID, die konkrete letterID und der Status des Dokumentes mit den Zeitstempeln aus dem Status (siehe LetterStatus) bereitzuhalten.