Skip to content

Send hybrid letter (Deutsche Post)

The “Send hybrid letter” service task submits PDF documents to Deutsche Post via the E-POSTBUSINESS API as hybrid letters. The task handles PDF/A conversion, DVF window/overlay, and maps the input fields to the API structure. Login credentials can optionally be overridden per call.

Input parameters

{
  "letter": {
    "filename": "Invoice_4711.pdf",
    "pdf_ref": {"...": "file_reference"},
    "iscolor": false,
    "isduplex": true,
    "testflag": false,
    "testemail": "max.sample@example.com",
    "testshowrestrictedarea": false,
    "addresslineone": "Max Sample",
    "addresslinetwo": "Sample Street 1",
    "addresslinethree": "1st floor",
    "zipcode": "12345",
    "city": "Sample City",
    "country": "DE",
    "senderadresslineone": "Pantarey GmbH",
    "senderstreet": "Main Street 5",
    "senderzipcode": "86150",
    "sendercity": "Augsburg",
    "costcenter": "AB1234",
    "customone": "Order no. 4711",
    "customtwo": "Customer-XYZ"
  },
  "login": {
    "vendorID": "OPTIONAL_OVERRIDE",
    "ekp": "OPTIONAL_OVERRIDE",
    "secret": "OPTIONAL_OVERRIDE",
    "password": "OPTIONAL_OVERRIDE",
    "vendorSubID": "OPTIONAL",
    "tokenDuration": 1440
  }
}

Explanation:

  • letter: Contains all information about the letter to send.
  • filename: Unique file name (allowed: [A-Za-z0-9._-]), used for mapping in the API.
  • pdf_ref: File reference; the PDF is converted to PDF/A-1b and enriched with the DVF overlay.
  • iscolor / isduplex: Printing options (color and duplex).
  • testflag / testemail / testshowrestrictedarea: Fields for test submissions.
  • addressline…, zipcode, city, country: Recipient address.
  • sender…: Sender details (sender line must appear in 8 pt within the DVF window).
  • costcenter: Up to 8 alphanumeric characters for client separation/billing.
  • customone to customtwo (up to customfive): Free fields forwarded to Deutsche Post as custom1..5.
  • login: Optional; if omitted, the credentials stored with the service task are used.

Output

For each submitted letter the enriched letter object including the Deutsche Post ID is returned:

{
  "letterid": "ab12cd34-ef56-...",
  "filename": "Invoice_4711.pdf",
  "costcenter": "AB1234",
  "status": {
    "statusid": 0,
    "statusdetails": "Letter successfully submitted to Deutsche Post (Pantarey)",
    "createddate": "2025-09-05T11:12:13.000Z",
    "errorlist": [],
    "pluginfeedbacklist": []
  }
}
  • letterid: ID of the letter in the Deutsche Post API.
  • status: Initial status with UTC timestamps (...Z).

Behavior and validation

  • PDF conversion: Input files are converted to PDF/A-1b including sRGB profile, XMP metadata, and DVF window.
  • Filename/mapping: Deduplication is based on filename; the order of items is irrelevant.
  • UTC timestamps: API times are normalized to UTC; the backend accepts UTC ISO only.
  • Login caching: Tokens are cached per tenant; the optional login object overrides defaults.

JSON examples

Minimal

{
  "letter": {
    "filename": "Reminder_0815.pdf",
    "pdf_ref": {"...": "file_reference"},
    "addresslineone": "Sample GmbH",
    "addresslinetwo": "Attn. Accounting",
    "zipcode": "20095",
    "city": "Hamburg",
    "senderadresslineone": "Pantarey GmbH",
    "senderstreet": "Main Street 5",
    "senderzipcode": "86150",
    "sendercity": "Augsburg",
    "iscolor": false,
    "isduplex": true
  }
}

With login override

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

JSONata examples

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

Notes

  • Address window/DVF: Populate recipient blocks correctly; masks and texts are positioned automatically.
  • Filename: Use API-compliant filenames only; unsupported characters are replaced.
  • Test mode: Set testflag = true and optionally testemail to run test deliveries without real dispatch.