{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/dhl/json-schema/dhl-letter-schema.json",
  "title": "Letter",
  "description": "Letter-Klasse, die eine Sendung definiert. Wird immer in einem Array übergeben.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/dhl-deutsche-post-hybrid-mail-shipments-e-post-post-parcel-germany-openapi.json#/components/schemas/Letter",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "fileName",
    "data",
    "addressLine1",
    "zipCode",
    "city"
  ],
  "properties": {
    "fileName": {
      "type": "string",
      "description": "Eindeutiger Dateiname der Sendung aus dem Quellsystem. Sonderzeichen sind nicht erlaubt",
      "maxLength": 200,
      "minLength": 5
    },
    "data": {
      "type": "string",
      "description": "PDF/A als Base64-String. Die ursprüngliche Dateigröße des PDFs darf ein Maximum von 20 MB nicht überscheiten."
    },
    "isColor": {
      "type": "boolean",
      "description": "Option Farbe oder S/W",
      "default": false
    },
    "isDuplex": {
      "type": "boolean",
      "description": "Option für doppelseitigen Druck",
      "default": false
    },
    "batchID": {
      "type": "integer",
      "description": "Kennung eines Stapellaufs (z.b. 15342). Kann für nachfolgende Statusabfragen als Gruppierungs-Kriterium verwendet werden. Erhält bei Nicht-Verwendung den Wert 0",
      "format": "int32"
    },
    "registeredLetter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Nationales Einschreiben-Kennzeichen (nur Simplex) - Mögliche Optionen: 'Einwurf Einschreiben', 'Einschreiben', 'Einschreiben eigenhändig', 'Einschreiben Rückschein', 'Einschreiben eigenhändig Rückschein'",
      "maxLength": 50,
      "minLength": 0
    },
    "registeredLetterAdressLine1": {
      "type": [
        "string",
        "null"
      ],
      "description": "(Überholt) Einschreiben-Empfängerzeile 1 (z.B. Name,Firma) für den Rückschein, falls dieser als Einschreibenoption gewählt wird",
      "maxLength": 80,
      "minLength": 0
    },
    "registeredLetterAdressLine2": {
      "type": [
        "string",
        "null"
      ],
      "description": "(Überholt) Einschreiben-Empfängerzeile 2 (z.B. Strasse,Adresszusatz) für den Rückschein, falls dieser als Einschreibenoption gewählt wird",
      "maxLength": 80,
      "minLength": 0
    },
    "registeredLetterAdressLine3": {
      "type": [
        "string",
        "null"
      ],
      "description": "(Überholt) Einschreiben-Empfängerzeile 3 (z.B. Strasse,Adresszusatz) für den Rückschein, falls dieser als Einschreibenoption gewählt wird",
      "maxLength": 80,
      "minLength": 0
    },
    "registeredLetterZipCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "(Überholt) PLZ des Einschreiben-Empfängers (z.B. 73312) für den Rückschein, falls dieser als Einschreibenoption gewählt wird",
      "maxLength": 20,
      "minLength": 5
    },
    "registeredLetterCity": {
      "type": [
        "string",
        "null"
      ],
      "description": "(Überholt) Stadt des Einschreiben-Empfänger (z.B. Geislingen an der Steige) für den Rückschein, falls dieser als Einschreibenoption gewählt wird",
      "maxLength": 80,
      "minLength": 0
    },
    "testFlag": {
      "type": "boolean",
      "description": "Test-Kennzeichen - bei true wird die Sendung nur zur Prüfung verarbeitet. Es erfolgt kein Briefversand",
      "default": false
    },
    "testEMail": {
      "type": [
        "string",
        "null"
      ],
      "description": "Test-Emailadresse - An diese Email-Adresse wird bei aktiviertem Test-Flag die Test-Sendung als Anhang verschickt ",
      "maxLength": 100,
      "minLength": 0
    },
    "testShowRestrictedArea": {
      "type": "boolean",
      "description": "Test-Sperrflächenmodus - Über dieses Flag wird das per email zurückgesendete pdf-Dokument mit einer Schablone überlagert, damit Sperrflächenverletzungen schneller erkannt werden.",
      "default": false
    },
    "coverLetter": {
      "type": "boolean",
      "description": "Deckblatt-Option - erzeugt ein Standard-Deckblatt mit validem Adressbereich. Wird ein eigenes PDF als Deckblatt (CoverData) übergeben , wird dieses anstelle der Standard-Vorlage verwendet. In beiden Fällen werden die übergebenen JSON-Adressdaten von der API verarbeitet und auf dem Deckblatt platziert.",
      "default": false
    },
    "coverData": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optionales PDF/A-Deckblatt als Base64-String. Die ursprüngliche Deckblatt-Dateigröße darf ein Maximum von 500 kb nicht überscheiten."
    },
    "addressLine1": {
      "type": "string",
      "description": "Empfängerzeile 1 (z.B. Name,Firma)",
      "maxLength": 80,
      "minLength": 1
    },
    "addressLine2": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfängerzeile 2 (z.B. Strasse,Adresszusatz)",
      "maxLength": 80,
      "minLength": 0
    },
    "addressLine3": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfängerzeile 3 (z.B. Strasse,Adresszusatz)",
      "maxLength": 80,
      "minLength": 0
    },
    "addressLine4": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfängerzeile 4 (z.B. Strasse,Adresszusatz)",
      "maxLength": 80,
      "minLength": 0
    },
    "addressLine5": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfängerzeile 5 (Nur bei DE-Adressen nutzbar)",
      "maxLength": 80,
      "minLength": 0
    },
    "zipCode": {
      "type": "string",
      "description": "Adresse-PLZ (z.B. 53115). Für Empfänger im Ausland ohne Postleitzahlen ist das Feld mit drei Leerzeichen (Blanks) zu befüllen. Für Inlandssendungen ist die korrekte Postleitzahl anzugeben, Leerzeichen sind nicht zulässig.",
      "maxLength": 20,
      "minLength": 3
    },
    "city": {
      "type": "string",
      "description": "Adresse-Stadt (z.B. Bonn)",
      "maxLength": 80,
      "minLength": 1
    },
    "country": {
      "type": [
        "string",
        "null"
      ],
      "description": "Adresse-Land - Hier muss der Ländername nach ISO 3166-1 in GROßBUCHSTABEN und deutscher Sprache hinterlegt werden. (z.B. KROATIEN, ITALIEN, ÖSTERREICH ..). Inlandsendungen benötigen keine Länderangabe.",
      "maxLength": 80,
      "minLength": 0
    },
    "senderAdressLine1": {
      "type": [
        "string",
        "null"
      ],
      "description": "Adresszeile1 des Versenders (z.B. Fa. Huber GmbH)",
      "maxLength": 80,
      "minLength": 0
    },
    "senderStreet": {
      "type": [
        "string",
        "null"
      ],
      "description": "Strasse des Versenders (z.B. Am Weg 1)",
      "maxLength": 80,
      "minLength": 0
    },
    "senderZipCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "PLZ des Versenders (z.B. 76887)",
      "maxLength": 80,
      "minLength": 0
    },
    "senderCity": {
      "type": [
        "string",
        "null"
      ],
      "description": "Stadt des Versenders (z.B. Bad Bergabern)",
      "maxLength": 80,
      "minLength": 0
    },
    "senderAdressLineComplete": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optionale Übergabe der kompletten Versenderadresse in einer Zeile, anstelle der einzelnen Versenderfelder (SenderAdressLine1,SenderStreet,SenderZipCode,SenderCity)",
      "maxLength": 200,
      "minLength": 0
    },
    "custom1": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen (z.B. RE345232)",
      "maxLength": 80,
      "minLength": 0
    },
    "custom2": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen",
      "maxLength": 80,
      "minLength": 0
    },
    "custom3": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen",
      "maxLength": 80,
      "minLength": 0
    },
    "custom4": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen",
      "maxLength": 80,
      "minLength": 0
    },
    "custom5": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen",
      "maxLength": 80,
      "minLength": 0
    },
    "vendorSystemInformation": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von systemspezifischen Kennungen und Informationen betreffend der vom Versender verwendeten Partner Software",
      "maxLength": 120,
      "minLength": 0
    },
    "costCenter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Kostenstelle mit einer möglichen Kombination der Zeichen 0-9, a-z, A-Z(keine Umlaute oder andere Sonderzeichen), auf welcher die Kosten bei der Abrechnung gruppiert werden",
      "maxLength": 8,
      "minLength": 0
    },
    "plugInList": {
      "type": [
        "array",
        "null"
      ],
      "description": "Liste von PlugIn-Objekten, über die zusätzliche Funktionen angesprochen werden können",
      "items": {
        "$ref": "#/$defs/PlugIn"
      }
    }
  },
  "$defs": {
    "PlugIn": {
      "type": "object",
      "description": "PlugIn-Objekt, zur Erweiterung um spezifische Informationen und Funktionen",
      "additionalProperties": false,
      "required": [
        "plugInName"
      ],
      "properties": {
        "plugInName": {
          "type": "string",
          "description": "Namenskennung des PlugIn",
          "maxLength": 200,
          "minLength": 0
        },
        "plugInModel": {
          "description": "Mit Daten angereichertes PlugIn-Model im JSON Format",
          "nullable": true
        }
      }
    }
  }
}