Skip to content

Hybrid letter status query (multiple IDs)

The “Hybrid letter status query (multiple IDs)” service task retrieves the current status of several hybrid letters via the E-POSTBUSINESS API. IDs can be provided directly or extracted from letter objects. The result can be returned as a list or as a map { letterid: statusObj }.

Input parameters

{
  "letterIDs": ["c9c8e9f0-...", "a1b2c3d4-..."],
  "letters": [
    { "letterid": "c9c8e9f0-..." },
    { "letterID": "a1b2c3d4-..." }
  ],
  "options": {
    "asMap": false
  },
  "login": {
    "vendorID": "OPTIONAL_OVERRIDE",
    "ekp": "OPTIONAL_OVERRIDE",
    "secret": "OPTIONAL_OVERRIDE",
    "password": "OPTIONAL_OVERRIDE",
    "vendorSubID": "OPTIONAL",
    "tokenDuration": 1440
  }
}
  • letterIDs: Array of letter IDs.
  • letters: Alternative or additional source for IDs (letterid or letterID).
  • options.asMap: When true, the result is returned as an object map { [letterid]: statusObj } (default: array).
  • login: Optional; if omitted, stored defaults are used and individual fields can be overridden.

Output

By default the task returns an array of status objects (keys lowercase, timestamps in UTC):

[
  {
    "letterid": "c9c8e9f0-...",
    "filename": "Invoice_4711.pdf",
    "statusid": 210,
    "statusdetails": "Transferred to print center",
    "createddate": "2025-09-05T08:12:03.000Z",
    "processeddate": "2025-09-05T08:15:10.000Z",
    "printuploaddate": "2025-09-05T08:16:00.000Z",
    "printfeedbackdate": "2025-09-05T08:28:30.000Z",
    "registeredletter": false,
    "noofpages": 3,
    "costcenter": "AB1234",
    "errorlist": [],
    "pluginfeedbacklist": []
  }
]

If options.asMap = true, the result is returned as a lookup map:

{
  "c9c8e9f0-...": { "...status as above..." },
  "a1b2c3d4-...": { "...status as above..." }
}

Behavior and validation

  • ID collection: IDs are gathered from letterIDs and letters[*].letterid|letterID, deduplicated, and empty values removed.
  • UTC timestamps: Date fields are normalized to UTC ISO (...Z).
  • Login caching: Tokens are cached per tenant; the optional login object overrides defaults.
  • Performance/Rate limits: Deutsche Post requires ≥ 5 s between status checks; internal retries (on 429) with jitter are implemented.
  • Security/filtering: Results are filtered per tenant via costcenter.

JSON examples

{
  "letterIDs": ["c9c8e9f0-...", "a1b2c3d4-..."]
}

{
  "letters": [
    { "letterid": "c9c8e9f0-..." },
    { "letterID": "a1b2c3d4-..." }
  ],
  "options": { "asMap": true }
}

{
  "letterIDs": ["c9c8e9f0-..."],
  "login": {
    "ekp": "EKP123456",
    "password": "****"
  }
}

JSONata examples

{
  "letterIDs": $.submitResult[].letterid,
  "options": { "asMap": true }
}

{
  "letterIDs": $.letters.(
    $id := letterid ? letterid : letterID;
    $id
  )
}

Notes

  • Error cases: If no valid IDs remain after cleanup, the task fails.
  • Mapping: All output keys are lowercase and follow the Pantarey schema.
  • Post-processing: For repeated polling, set options.asMap = true for faster access via letterid.