Darstellung
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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_status | inbound | Pflicht: inbound, outbound, outbound_sending, outbound_failed, outbound_fetched, draft, trash, release oder archive |
Request-Body (form-data)
| Feld | Beschreibung | Beispiel |
|---|---|---|
postboxitem_status | Statusfilter (Pflicht – wird auch im Pfad übergeben) | inbound |
search | Typesense-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"}] |
page | Seite (optional, numerisch) | – |
Weitere Request-Felder (form-data/JSON)
| Feld | Beschreibung | Beispiel |
|---|---|---|
sort | Sortierung 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"
}
]
}| Feld | Typ | Beschreibung |
|---|---|---|
search.found | int | Gesamtzahl der Treffer |
search.per_page | int | Treffer pro Seite (max. 100) |
search.current_page | int | Aktuelle Seite |
search.total_pages | int | Gesamtzahl der Seiten |
data[] | object | Postbox-Item inkl. Datenfelder sowie recipient_data/transmitter_data (aufgelöste Kontaktobjekte) |
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
406 | validationinvalid | Status fehlt/ungültig oder sort/page-Werte ungültig |
403 | access denied | HMAC-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/setLegt ein neues Postbox-Item an (Status: draft).
Request-Body (form-data)
| Feld | Beschreibung | Beispiel |
|---|---|---|
transmitter_cert_ID | UUID des Absender-Zertifikats (sendepflichtig) – per cert/getall abrufbar | – |
content_subject | Betreff (max. 250, sendepflichtig) | – |
recipient_justiz_ID | Justiz-ID der Empfänger:in (max. 250, sendepflichtig) | – |
content_reference | Aktenzeichen (max. 100) | – |
content_subjectarea | Sachgebiets-Code (max. 250) | – |
include_read_receipt | 1 = 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)
| Feld | Beschreibung | Beispiel |
|---|---|---|
postboxitem_source_ID | Eigene Referenz-ID (max. 100) – muss pro Quelle eindeutig sein; bei draft automatisch generiert | – |
associated_type | Verknüpfungstyp (nur erlaubte Werte) | – |
associated_type_ID | ID des verknüpften Objekts (max. 40) | – |
postboxitem_create_timestamp | Erstell-Zeitpunkt (Datetime, muss in der Vergangenheit liegen; Default: jetzt) | – |
postboxitem_open | true markiert das Item direkt als geöffnet | – |
content_summary | Zusammenfassung (max. 50000) | – |
content_keywords | Keywords (max. 50000) | – |
Response
Die postboxitem_ID (UUID) der angelegten Nachricht als JSON-String:
json
"6bd525df-5b16-4a55-b5d9-ee4cf5277d7b"Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
409 | postboxitem already exists for this source | postboxitem_source_ID bereits belegt |
406 | validationinvalid | Pflicht-Datenfelder fehlen oder Constraints verletzt |
500 | failed to create postboxitem | Datenbankfehler beim Anlegen |
500 | not all data items were inserted correctly | Teilweise Datenfelder nicht gespeichert |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | b85d477a-9bc5-4ff9-9a33-34dc548c3161 | UUID 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
}| Feld | Typ | Beschreibung |
|---|---|---|
postboxitem_ID | string | UUID des Postbox-Items |
company_ID | string | UUID des zugehörigen Unternehmens |
postboxitem_source | string | Quelle des Items (z. B. ebo) |
postboxitem_source_ID | string | Referenz-ID der Quelle |
postboxitem_status | string | Aktueller Status |
postboxitem_create_timestamp | string | Erstell-Zeitpunkt (YYYY-MM-DD HH:MM:SS) |
postboxitem_open_timestamp | string | Zeitpunkt des ersten Öffnens |
postboxitem_open_user_ID | string | Benutzer:in, die das Item geöffnet hat |
associated_type / associated_type_ID | string | Verknüpfung zu einem anderen Objekt (kann leer sein) |
files | array | Zugeordnete Dateien |
files_count | int | Anzahl der Dateien |
files_size | int | Gesamtgröße der Dateien |
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
406 | validationinvalid | postboxitem_ID nicht exakt 36 Zeichen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | 99d502a6-02ad-4e6f-9c90-f15b0819526b | UUID des Postbox-Items (36 Zeichen) |
postboxitem_export | true | Optional: true/1 für Dokument-Export |
Response
Array von History-Einträgen; bei export=true das generierte Dokument.
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Postbox-Item existiert nicht |
404 | postboxitem history could not be found | Keine History-Einträge vorhanden |
500 | postboxitemhistory template could not be generated | Export-Dokument konnte nicht erzeugt werden |
406 | validationinvalid | postboxitem_ID nicht exakt 36 Zeichen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | 402864da-39d0-4650-9bf7-290f45aa43eb | UUID des Postbox-Items (36 Zeichen) |
Request-Body (form-data)
| Feld | Beschreibung | Beispiel |
|---|---|---|
content_keywords | Keywords (max. 50000) | – |
content_reference | Aktenzeichen (max. 100) | – |
content_subject | Betreff (max. 250, sendepflichtig) | – |
content_subjectarea | Sachgebiets-Code (max. 250) | – |
content_summary | Zusammenfassung (max. 50000) | – |
include_read_receipt | 1 = Empfangsbestätigung anfordern | – |
recipient_justiz_ID | Justiz-ID der Empfänger:in (max. 250, sendepflichtig) | – |
transmitter_cert_ID | UUID des Absender-Zertifikats (sendepflichtig) – per cert/getall abrufbar | – |
Response
Die aktualisierten Datenfelder inklusive aufgelöster Kontaktdaten.
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
406 | validationinvalid | Felder verletzen die Datentyp-Validierung |
500 | not all data items were updated correctly | Teilweise Felder nicht gespeichert |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | 8f98c88e-e8e8-4598-b216-b72e114bfc46 | UUID des Postbox-Items (36 Zeichen) |
Response
Der Response-Body enthält bei Erfolg [true].
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
400 | postboxitem must be in trash or draft status to be deleted | Status ist nicht trash/draft |
500 | postboxitem could not be deleted | Löschung fehlgeschlagen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | b2354875-f9f4-4c8e-b1d8-f04925ee3c3c | UUID 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
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
409 | postboxitem status is not draft or outbound_failed | Item ist in einem nicht versendbaren Status |
409 | postboxitem data is missing | Keine Datenfelder vorhanden |
404 | transmitter certificate not found | transmitter_cert_ID fehlt oder Zertifikat unbekannt |
409 | transmitter certificate is not valid | Zertifikat hat keine Safe-ID |
406 | validationinvalid | Sendepflichtige Datenfelder fehlen oder ungültig |
500 | postboxitem could not be send | Übergabe an die Versand-Queue fehlgeschlagen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | a8d26e87-dee0-4381-998a-fe301533a871 | UUID des Postbox-Items (36 Zeichen) |
Request-Body (form-data)
| Feld | Beschreibung | Beispiel |
|---|---|---|
receipt_status | send = bestätigen, reject = ablehnen (Pflicht) | reject |
receipt_send_date | Empfangsdatum (Pflicht bei send; nicht in der Zukunft) | 2026-05-01 |
receipt_reject_status | Ablehnungsgrund (Selectwert reject_status; nur bei reject) | 1 |
receipt_reject_message | Ablehnungstext (optional, max. 1500) | Ich bin ein neuer Ablehnungstext |
Response
Der Response-Body enthält [true] – der Versand läuft asynchron.
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
409 | postboxitem status is not inbound | Item ist kein Eingang |
409 | postboxitem receipt status is not request | Es liegt keine angeforderte Empfangsbestätigung vor |
404 | recipient_justiz_ID could not be found | Empfänger-Justiz-ID fehlt am Item |
404 | certificate not found | Kein Zertifikat zur Empfänger-Safe-ID |
406 | validationinvalid | receipt_status/Pflichtfelder ungültig |
500 | postboxitem receipt could not be send | Übergabe an die Queue fehlgeschlagen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | 99d502a6-02ad-4e6f-9c90-f15b0819526b | UUID des Postbox-Items (36 Zeichen) |
Response
Der Response-Body enthält bei Erfolg [true].
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
500 | postboxitem could not be set as read | Update fehlgeschlagen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | 402864da-39d0-4650-9bf7-290f45aa43eb | UUID des Postbox-Items (36 Zeichen) |
postboxitem_status | inbound | inbound, outbound, draft, trash, release, process, outbound_failed, outbound_fetched, archive oder restore |
Response
Der Response-Body enthält bei Erfolg [true].
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
200 | postboxitem status is already as requested | Status ist bereits gesetzt – als Hinweis mit 200 geliefert |
500 | postboxitem status can only be archived from inbound, outbound or outbound_fetched | Ungültiger Übergang nach archive |
422 | postboxitem can only be restored from archive or trash | restore aus ungültigem Status |
422 | no original status found to restore | Kein gespeicherter Ursprungsstatus vorhanden |
422 | postboxitem status could not be changed | Status-Update fehlgeschlagen |
403 | access denied | HMAC-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
| Parameter | Beispiel | Beschreibung |
|---|---|---|
postboxitem_ID | b85d477a-9bc5-4ff9-9a33-34dc548c3161 | UUID des Postbox-Items (36 Zeichen) |
Response
Status 302 mit Location-Header auf die ZIP-Download-URL.
Mögliche Fehler
| Code | Meldung | Bedingung |
|---|---|---|
404 | postboxitem could not be found | Item existiert nicht |
404 | No files found for this postbox item | Item hat keine Dateien |
500 | postboxitem url could not be set | Interne Download-Verknüpfung fehlgeschlagen |
500 | failed to create download zip link | ZIP-Erstellung am Datei-Service fehlgeschlagen |
403 | access denied | HMAC-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/gethashLiefert 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
| Code | Meldung | Bedingung |
|---|---|---|
404 | failed to get postboxitem hash | Hash konnte nicht ermittelt werden |
403 | access denied | HMAC-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) |