Skip to content

Postboxitem ​

Verwaltung der Postbox-Items (Nachrichten): Items anlegen, abrufen, aktualisieren, versenden, durchsuchen und deren Status verwalten.

Postbox-Items suchen ​

POST KUNDEN-HMAC /postboxitem/search/{postboxitem_status}

Volltextsuche über die Postbox – im Hintergrund läuft ein Typesense-Server. Der gewünschte Status muss in der URL mitgegeben werden. Sonderfall: der Status outbound umfasst zusätzlich outbound_sending, outbound_failed und outbound_fetched.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_statusinboundPflicht: inbound, outbound, outbound_sending, outbound_failed, outbound_fetched, draft, trash, release oder archive

Request-Body (form-data) ​

FeldBeschreibungBeispiel
postboxitem_statusStatusfilter (Pflicht – wird auch im Pfad übergeben)inbound
searchTypesense-Filter als JSON-Array (optional) – über filter_by lässt sich weiter einschränken, z. B. nach Erstell-Zeitpunkt[{"filter_by":"postboxitem_create_timestamp:>=1764716400"}]
pageSeite (optional, numerisch)–

Weitere Request-Felder (form-data/JSON) ​

FeldBeschreibungBeispiel
sortSortierung nach Erstell-Zeitpunkt: asc oder desc (Default: desc)–

Response ​

Paginiertes Suchergebnis: search enthält die Paginierung (found, per_page, current_page, total_pages), data die Trefferliste (bis zu 100 Dokumente pro Seite). Beispiel (Auszug mit einem Treffer):

json
{
  "search": {
    "found": 35,
    "per_page": 100,
    "current_page": 0,
    "total_pages": 1
  },
  "data": [
    {
      "content_keywords": [],
      "content_reference": "unbekannt",
      "content_subject": "Test",
      "content_subjectarea": "sachgebiet-039",
      "content_summary": "",
      "include_read_receipt": "",
      "own_message_ID": "1d675b48-f574-4dbc-a3af-8e58d950d93d",
      "postboxitem_ID": "4660fb69-3368-4cce-bf45-2282d7a0969f",
      "postboxitem_create_timestamp": 1793001952,
      "postboxitem_open_timestamp": 1793001980,
      "postboxitem_open_user_ID": "d82eb8cf-4740-4b21-af91-408329701017",
      "postboxitem_source": "ebo",
      "postboxitem_status": "inbound",
      "receipt_reject_message": "",
      "receipt_reject_status": "",
      "receipt_send_date": "",
      "receipt_status": "",
      "recipient_cert_ID": "",
      "recipient_data": {
        "contact_ID": "e25ff290-af5f-4000-8eae-b846f55b39b7",
        "contact_alternative_organization": "",
        "contact_city": "Berlin",
        "contact_country": "",
        "contact_created_at": "2026-10-26 09:05:53",
        "contact_egvp_role": "",
        "contact_email": "",
        "contact_fax": "",
        "contact_first_name": "",
        "contact_form_address": "",
        "contact_full_name": "",
        "contact_house_number": "42A",
        "contact_justiz_ID": "DE.Justiz.004804f3-edc6-4ee8-9398-47d861417aae.8e3a",
        "contact_last_name": "Copper & Grey Solutions GmbH",
        "contact_phone": "",
        "contact_postal_code": "10369",
        "contact_profession_property": "",
        "contact_role_name": "",
        "contact_street_name": "Karl-Lade-Straße",
        "contact_title": ""
      },
      "recipient_justiz_ID": "DE.Justiz.004804f3-edc6-4ee8-9398-47d861417aae.8e3a",
      "recipient_name": "",
      "transmitter_cert_ID": "",
      "transmitter_data": {
        "contact_ID": "e25ff290-af5f-4000-8eae-b846f55b39b7",
        "contact_alternative_organization": "",
        "contact_city": "Berlin",
        "contact_country": "",
        "contact_created_at": "2026-10-26 09:05:53",
        "contact_egvp_role": "",
        "contact_email": "",
        "contact_fax": "",
        "contact_first_name": "",
        "contact_form_address": "",
        "contact_full_name": "",
        "contact_house_number": "42A",
        "contact_justiz_ID": "DE.Justiz.004804f3-edc6-4ee8-9398-47d861417aae.8e3a",
        "contact_last_name": "Copper & Grey Solutions GmbH",
        "contact_phone": "",
        "contact_postal_code": "10369",
        "contact_profession_property": "",
        "contact_role_name": "",
        "contact_street_name": "Karl-Lade-Straße",
        "contact_title": ""
      },
      "transmitter_justiz_ID": "DE.Justiz.004804f3-edc6-4ee8-9398-47d861417aae.8e3a"
    }
  ]
}
FeldTypBeschreibung
search.foundintGesamtzahl der Treffer
search.per_pageintTreffer pro Seite (max. 100)
search.current_pageintAktuelle Seite
search.total_pagesintGesamtzahl der Seiten
data[]objectPostbox-Item inkl. Datenfelder sowie recipient_data/transmitter_data (aufgelöste Kontaktobjekte)

Mögliche Fehler ​

CodeMeldungBedingung
406validationinvalidStatus fehlt/ungültig oder sort/page-Werte ungültig
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Postbox-Item anlegen ​

POST KUNDEN-HMAC /postboxitem/set

Legt ein neues Postbox-Item an (Status: draft).

Request-Body (form-data) ​

FeldBeschreibungBeispiel
transmitter_cert_IDUUID des Absender-Zertifikats (sendepflichtig) – per cert/getall abrufbar–
content_subjectBetreff (max. 250, sendepflichtig)–
recipient_justiz_IDJustiz-ID der Empfänger:in (max. 250, sendepflichtig)–
content_referenceAktenzeichen (max. 100)–
content_subjectareaSachgebiets-Code (max. 250)–
include_read_receipt1 = Empfangsbestätigung anfordern–

Als sendepflichtig markierte Felder sind erforderlich, um eine eBO-Nachricht absenden zu können (postboxitem/send).

Weitere Request-Felder (form-data/JSON) ​

FeldBeschreibungBeispiel
postboxitem_source_IDEigene Referenz-ID (max. 100) – muss pro Quelle eindeutig sein; bei draft automatisch generiert–
associated_typeVerknüpfungstyp (nur erlaubte Werte)–
associated_type_IDID des verknüpften Objekts (max. 40)–
postboxitem_create_timestampErstell-Zeitpunkt (Datetime, muss in der Vergangenheit liegen; Default: jetzt)–
postboxitem_opentrue markiert das Item direkt als geöffnet–
content_summaryZusammenfassung (max. 50000)–
content_keywordsKeywords (max. 50000)–

Response ​

Die postboxitem_ID (UUID) der angelegten Nachricht als JSON-String:

json
"6bd525df-5b16-4a55-b5d9-ee4cf5277d7b"

Mögliche Fehler ​

CodeMeldungBedingung
409postboxitem already exists for this sourcepostboxitem_source_ID bereits belegt
406validationinvalidPflicht-Datenfelder fehlen oder Constraints verletzt
500failed to create postboxitemDatenbankfehler beim Anlegen
500not all data items were inserted correctlyTeilweise Datenfelder nicht gespeichert
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Postbox-Item abrufen ​

POST KUNDEN-HMAC /postboxitem/get/{postboxitem_ID}

Liefert ein Postbox-Item inklusive aller Datenfelder, aufgelöster Empfänger-/Absender-Kontaktdaten und zugeordneter Dateien.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_IDb85d477a-9bc5-4ff9-9a33-34dc548c3161UUID des Postbox-Items (36 Zeichen)

Response ​

Das Item-Objekt inklusive Datei-Informationen (files, files_count, files_size):

json
{
  "postboxitem_ID": "6bd525df-5b16-4a55-b5d9-ee4cf5277d7b",
  "company_ID": "7bea2a0b-16ae-418b-8891-45094773c522",
  "postboxitem_source": "ebo",
  "postboxitem_source_ID": "6571c6e5-0969-4038-913f-f73d3ad00810",
  "postboxitem_status": "draft",
  "postboxitem_create_timestamp": "2026-10-26 21:44:53",
  "postboxitem_open_timestamp": "2026-10-26 21:44:53",
  "postboxitem_open_user_ID": "d82eb8cf-4740-4b21-af91-408329701017",
  "associated_type": "",
  "associated_type_ID": "",
  "files": [],
  "files_count": 0,
  "files_size": 0
}
FeldTypBeschreibung
postboxitem_IDstringUUID des Postbox-Items
company_IDstringUUID des zugehörigen Unternehmens
postboxitem_sourcestringQuelle des Items (z. B. ebo)
postboxitem_source_IDstringReferenz-ID der Quelle
postboxitem_statusstringAktueller Status
postboxitem_create_timestampstringErstell-Zeitpunkt (YYYY-MM-DD HH:MM:SS)
postboxitem_open_timestampstringZeitpunkt des ersten Öffnens
postboxitem_open_user_IDstringBenutzer:in, die das Item geöffnet hat
associated_type / associated_type_IDstringVerknüpfung zu einem anderen Objekt (kann leer sein)
filesarrayZugeordnete Dateien
files_countintAnzahl der Dateien
files_sizeintGesamtgröße der Dateien

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
406validationinvalidpostboxitem_ID nicht exakt 36 Zeichen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Verlauf eines Postbox-Items abrufen ​

POST KUNDEN-HMAC /postboxitemhistory/get/{postboxitem_ID}/{postboxitem_export}

Liefert die History-Einträge (Aktionen, Zeitstempel, Benutzer:innen) eines Postbox-Items. Mit export=true wird statt JSON ein formatiertes Verlaufs-Dokument als PDF-Datei generiert.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_ID99d502a6-02ad-4e6f-9c90-f15b0819526bUUID des Postbox-Items (36 Zeichen)
postboxitem_exporttrueOptional: true/1 für Dokument-Export

Response ​

Array von History-Einträgen; bei export=true das generierte Dokument.

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundPostbox-Item existiert nicht
404postboxitem history could not be foundKeine History-Einträge vorhanden
500postboxitemhistory template could not be generatedExport-Dokument konnte nicht erzeugt werden
406validationinvalidpostboxitem_ID nicht exakt 36 Zeichen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Datenfelder eines Items aktualisieren ​

POST KUNDEN-HMAC /postboxitem/update/{postboxitem_ID}

Aktualisiert einzelne Datenfelder (content_*, recipient_* …) eines bestehenden Items. Es werden nur die mitgesendeten Felder verändert. Der Suchindex wird aktualisiert.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_ID402864da-39d0-4650-9bf7-290f45aa43ebUUID des Postbox-Items (36 Zeichen)

Request-Body (form-data) ​

FeldBeschreibungBeispiel
content_keywordsKeywords (max. 50000)–
content_referenceAktenzeichen (max. 100)–
content_subjectBetreff (max. 250, sendepflichtig)–
content_subjectareaSachgebiets-Code (max. 250)–
content_summaryZusammenfassung (max. 50000)–
include_read_receipt1 = Empfangsbestätigung anfordern–
recipient_justiz_IDJustiz-ID der Empfänger:in (max. 250, sendepflichtig)–
transmitter_cert_IDUUID des Absender-Zertifikats (sendepflichtig) – per cert/getall abrufbar–

Response ​

Die aktualisierten Datenfelder inklusive aufgelöster Kontaktdaten.

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
406validationinvalidFelder verletzen die Datentyp-Validierung
500not all data items were updated correctlyTeilweise Felder nicht gespeichert
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Postbox-Item löschen ​

POST KUNDEN-HMAC /postboxitem/delete/{postboxitem_ID}

Löscht ein Item unwiderruflich inklusive Datenfelder, History und zugeordneter Dateien. Nur Items im Status trash oder draft können gelöscht werden – andere Items zuerst per updatestatus verschieben.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_ID8f98c88e-e8e8-4598-b216-b72e114bfc46UUID des Postbox-Items (36 Zeichen)

Response ​

Der Response-Body enthält bei Erfolg [true].

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
400postboxitem must be in trash or draft status to be deletedStatus ist nicht trash/draft
500postboxitem could not be deletedLöschung fehlgeschlagen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Postbox-Item versenden ​

POST KUNDEN-HMAC /postboxitem/send/{postboxitem_ID}

Versendet ein Item. Vorbedingungen: Status draft oder outbound_failed, alle sendepflichtigen Datenfelder befüllt (content_subject, recipient_justiz_ID, transmitter_cert_ID) und ein gültiges Absender-Zertifikat. Aus dem Zertifikat wird automatisch die transmitter_justiz_ID (Safe-ID) übernommen. Das Item wechselt in den Status outbound_sending, der Versand läuft asynchron.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_IDb2354875-f9f4-4c8e-b1d8-f04925ee3c3cUUID des Postbox-Items (36 Zeichen)

Response ​

Der Response-Body enthält [true] – der Versand läuft asynchron; das Ergebnis ist über postboxitem/search (Status outbound/outbound_failed) nachverfolgbar.

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
409postboxitem status is not draft or outbound_failedItem ist in einem nicht versendbaren Status
409postboxitem data is missingKeine Datenfelder vorhanden
404transmitter certificate not foundtransmitter_cert_ID fehlt oder Zertifikat unbekannt
409transmitter certificate is not validZertifikat hat keine Safe-ID
406validationinvalidSendepflichtige Datenfelder fehlen oder ungültig
500postboxitem could not be sendÜbergabe an die Versand-Queue fehlgeschlagen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Empfangsbestätigung senden ​

POST KUNDEN-HMAC /postboxitem/sendreceipt/{postboxitem_ID}

Beantwortet eine angeforderte Empfangsbestätigung (receipt_status = request) eines inbound-Items – entweder mit send (bestätigen, receipt_send_date Pflicht) oder reject (ablehnen, optional mit Grund). Wird an die Absender:in übermittelt.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_IDa8d26e87-dee0-4381-998a-fe301533a871UUID des Postbox-Items (36 Zeichen)

Request-Body (form-data) ​

FeldBeschreibungBeispiel
receipt_statussend = bestätigen, reject = ablehnen (Pflicht)reject
receipt_send_dateEmpfangsdatum (Pflicht bei send; nicht in der Zukunft)2026-05-01
receipt_reject_statusAblehnungsgrund (Selectwert reject_status; nur bei reject)1
receipt_reject_messageAblehnungstext (optional, max. 1500)Ich bin ein neuer Ablehnungstext

Response ​

Der Response-Body enthält [true] – der Versand läuft asynchron.

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
409postboxitem status is not inboundItem ist kein Eingang
409postboxitem receipt status is not requestEs liegt keine angeforderte Empfangsbestätigung vor
404recipient_justiz_ID could not be foundEmpfänger-Justiz-ID fehlt am Item
404certificate not foundKein Zertifikat zur Empfänger-Safe-ID
406validationinvalidreceipt_status/Pflichtfelder ungültig
500postboxitem receipt could not be sendÜbergabe an die Queue fehlgeschlagen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Item als gelesen markieren ​

POST KUNDEN-HMAC /postboxitem/setread/{postboxitem_ID}

Setzt open_timestamp/open_user auf dem Item und schreibt einen History-Eintrag. Bereits gelesene Items liefern trotzdem 200.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_ID99d502a6-02ad-4e6f-9c90-f15b0819526bUUID des Postbox-Items (36 Zeichen)

Response ​

Der Response-Body enthält bei Erfolg [true].

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
500postboxitem could not be set as readUpdate fehlgeschlagen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Status eines Items ändern ​

POST KUNDEN-HMAC /postboxitem/updateStatus/{postboxitem_ID}/{postboxitem_status}

Setzt den Status eines Items. archive ist nur aus inbound/outbound/outbound_fetched erlaubt; restore holt ein archiviertes oder gelöschtes Item in seinen ursprünglichen Status zurück. Vor dem Verschieben nach archive/trash wird der Ursprungsstatus gespeichert.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_ID402864da-39d0-4650-9bf7-290f45aa43ebUUID des Postbox-Items (36 Zeichen)
postboxitem_statusinboundinbound, outbound, draft, trash, release, process, outbound_failed, outbound_fetched, archive oder restore

Response ​

Der Response-Body enthält bei Erfolg [true].

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
200postboxitem status is already as requestedStatus ist bereits gesetzt – als Hinweis mit 200 geliefert
500postboxitem status can only be archived from inbound, outbound or outbound_fetchedUngültiger Übergang nach archive
422postboxitem can only be restored from archive or trashrestore aus ungültigem Status
422no original status found to restoreKein gespeicherter Ursprungsstatus vorhanden
422postboxitem status could not be changedStatus-Update fehlgeschlagen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Alle Dateien eines Items als ZIP laden ​

POST KUNDEN-HMAC /postboxitem/getzip/{postboxitem_ID}

Erzeugt ein ZIP-Archiv aller Dateien des Items und antwortet mit 302-Redirect auf eine zeitlich befristete Download-URL. Dem Redirect folgen oder die Location auslesen.

Pfad-Parameter ​

ParameterBeispielBeschreibung
postboxitem_IDb85d477a-9bc5-4ff9-9a33-34dc548c3161UUID des Postbox-Items (36 Zeichen)

Response ​

Status 302 mit Location-Header auf die ZIP-Download-URL.

Mögliche Fehler ​

CodeMeldungBedingung
404postboxitem could not be foundItem existiert nicht
404No files found for this postbox itemItem hat keine Dateien
500postboxitem url could not be setInterne Download-Verknüpfung fehlgeschlagen
500failed to create download zip linkZIP-Erstellung am Datei-Service fehlgeschlagen
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Änderungs-Hash der Postbox abrufen ​

POST KUNDEN-HMAC /postboxitem/gethash

Liefert einen Hash über den Postbox-Bestand – geeignet, um clientseitig Änderungen zu erkennen, ohne alle Items zu laden.

Response ​

Der Hash-Wert des aktuellen Postbox-Bestands als JSON-String:

json
"<sha1-hash>"

Mögliche Fehler ​

CodeMeldungBedingung
404failed to get postboxitem hashHash konnte nicht ermittelt werden
403access deniedHMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500–Interner Fehler – generische Meldung
503–Rate-Limit überschritten (250 Requests/s pro IP)

Mit 🌈 entwickelt in Berlin 🐻 & Köln ⛪
Hosting zu 100% in Deutschland 🇩🇪