Working with the E-POSTBUSINESS API

The E-POSTBUSINESS API from Deutsche Post enables seamless automation of letter dispatch through the Document Dispatch platform. By integrating this API, the entire process—from digital document creation to physical letter delivery—is fully automated, requiring no manual effort.

The API handles the following steps:

Printing – Converts digital documents into physical letters
Enveloping – Automatically inserts documents into envelopes
Franking – Prepares letters for postal dispatch

Once the letter is ready, Deutsche Post takes care of the delivery, eliminating manual intervention. This automation saves businesses time and costs while ensuring a reliable and efficient mailing solution.

Info

Before you can successfully send letters, the E-POSTBUSINESS API must be set up. You can find detailed setup instructions here.

Creating and sending a document via E-POST

Using the E-POSTBUSINESS API, users can send documents directly from Business Central as letters.

Steps to create and send a letter via the API:

Navigate to a document (e.g. posted sales invoice) in Business Central.
Use the Send E-Post Action in the Document Dispatch factbox.
- Make sure that you have a dispatch profile for the table from which a document is to be sent.
Add the desired documents or attachments and select your specific desired dispatch setting. These settings include:
- Registered Letter
  - Drop-Off Registered Mail (Einwurf-Einschreiben):
    - The letter is delivered directly to the recipient's mailbox without requiring any signature.
    - This option provides basic tracking and proof of delivery, confirming that the letter has been placed in the mailbox.
    - Ideal for important but non-critical documents where a signature is not necessary, such as notifications or general correspondence.
  - Registered Mail (Einschreiben):
    - The letter is handed over personally to the recipient or an authorized person in exchange for a signature.
    - The sender receives confirmation that the letter has been delivered, but no additional proof of who exactly received it.
    - Suitable for sensitive documents where direct handover is necessary, such as contracts or legal notices.
  - Registered Mail with Return Receipt (Einschreiben mit Rückschein):
    - In addition to the recipients signature, the sender receives a written delivery confirmation (return receipt).
    - The return receipt includes the recipients name and signature, serving as legally valid proof of receipt.
    - Recommended for highly important or legally binding documents, such as termination letters, legal notices, or official communications.
  - Coverletter
    - Adds a cover page to the mailing, which can include additional information or serve as a separator between different document sections.
  - Duplex
    - Enables double-sided (duplex) printing to save paper and make the mailing more environmentally friendly.
  - Color
    - Specifies whether the document should be printed in color or black and white. This is useful for documents containing images or important color-coded information.
Select the OK action.
After the confirmation in the dialog, the API automatically sends the document to Deutsche Post, where it is printed and dispatched.

Info

The combination of Duplex and Registered Letter is not possible. If you select Duplex, the Registered Letter option will be disabled. This function requires an active API connection to Deutsche Post.

Display of the dispatch status in Business Central

All dispatches, including E-Post shipments, are listed and recorded in the Document Dispatch - Queue. Within this queue, there is a specific action for E-Post entries called "E-Post Information".

By selecting this action, a page opens displaying the following information:

General Information

Entry Number
Source Document
Test Mode Indicator
Date of Last Status Update

Letter Information

Letter ID
Selected Dispatch Options

Recipient Information

Recipient Name
Recipient Address

Status Tracking

A ListPart records all queried statuses, each associated with a Status ID and Status Code.

Status IDs and Explanations:

1 - Acceptance of Shipment - The shipment was successfully transmitted, and no schema or content violations were detected in the JSON. - Status Placement: Upon successful upload of the shipment.

2 - Processing of Shipment - The PDF has been checked for E-Post compliance and is approved for printing. - Note: Despite thorough checks, technical errors in the PDF may lead to processing failures at the print center, resulting in Status 99. - Status Placement: A few minutes after shipment acceptance.

3 - Submission to Print Center - The shipment has been transferred to the print center for production. - Note: If technical errors cause a processing failure, Status 99 will be issued instead of Status 4. - Status Placement: Within hours after processing.

4 - Processing in Print Center - The shipment has been marked as "sent" by the print center. - Status Placement: 1-2 business days after submission to the print center.

99 - Processing Error - See error list for details.

Queue Entry Status

The status of a queue entry is updated according to the process steps. Once the status "4" (Processing in Print Center) is reached, the entry is marked as "sent".

After a successful E-Post dispatch, the queue entry is assigned the status "Shipment Started". This status indicates the initialization of the shipping process. It will be automatically updated with all subsequent E-Post process statuses, provided that the job queue "Document Dispatch Automatic E-Post Letter Status Update" is running.

Status Codes and Explanations:

Errors: Require action, processing aborted

E001 - Invalid credentials – Check login details
E002 - Invalid credentials – VendorSubID incorrect
E003 - Too many SMS requests – Blocked for 15 minutes
E004 - EKP blocked by Deutsche Post
E101 - Invalid token – Expired
E201 - Invalid status query – No shipment found
E203 - Address metadata deviation detected
E301 - No PDF format recognized
E302 - Violation of DVF restricted area
E303 - Maximum file size of 20 MB exceeded
E304 - Maximum page count of 94 exceeded
E305 - Invalid country code
E306 - Invalid recipient address format
E307 - First page in landscape format
E308 - Non-DIN A4 format detected
E309 - Duplicate filename detected
E311 - Invalid combination: Registered Letter and international shipping
E312 - Invalid combination: Duplex + Registered Letter
E313 - Letter schema violation
E314 - Cover page file size exceeds 1 MB
E315 - Processing error in shipment
E316 - Upload error
E317 - Invalid registered letter format
E318 - Rejection at print center
E319 - EKP not approved for print center – Live dispatch not possible
E320 - Maximum number of test shipments per day reached
E322 - Status request frequency too high – Minimum 5 seconds between requests
E323 - No content detected in recipient area (blank page)
E399 - General error
E501 - API status: Inactive
E601 - Plugin error
E900 - Unspecified error

Warnings: May require action, but processing continues

W101 - PDF/A conversion warnings
W201 - Address area exceeded
W202 - Left restricted area exceeded (will be whitened)
W203 - Address metadata deviations
W220 - As of 01.10.2022, return receipt address details are automatically extracted from the letter’s visible sender area
W301 - Sender address missing
W501 - API status: Maintenance notice
W601 - Plugin warning

Informational Messages: No action required

I101 - Additional option: PDF to PDF/A conversion
I501 - API status: OK
I601 - Plugin info
I701 - Track and trace status update
I751 - Status message for destination region

Queue Log for E-Post Entries

The Document Dispatch - Queue Log track events related to every type of dispatch, but for E-Post entries the log provides a detailed history of dispatch actions and include entries such as:

When an E-Post letter was successfully sent.
If a letter was sent in test mode.
Any system errors or failures that occurred during the dispatch process.

Users can review queue logs within the Document Dispatch - Queue with the Action View Log, allowing them to monitor dispatch activities and diagnose potential issues.

E-Post Log

The E-Post Log provides a detailed audit of system actions related to E-Post, including:

Login Attempts: Successful and failed authentication attempts.
Password Changes: Records when a password was changed for the E-POSTBUSINESS API user.
SMS Code Request Attempts: When a new SMS code was successful and failed requested for authentication.

The E-Post Log enables administrators to track changes and ensure the security of the E-POSTBUSINESS API.

Working with the Automatic Address Setter

The Automatic Address Setter helps ensure that recipient addresses are positioned correctly for E-Post letter dispatch.

Steps to Use the Automatic Address Setter:

Move to for example a posted sales invoice in Business Central.
Choose a record and select the Send E-Post action in the Document Dispatch factbox.
Ensure that an address overlay configuration has been set up and activated (configured in Dispatch Profile Attachment for a Report, which if it should be used correctly and as interpret, the first Attachment in the listpart. Also the Overlay should be set up for the report layout, which is in use right now).
When generating a e.g. invoice for a dispatch through E-Post, the system will automatically apply the preset address overlay.
Review the document preview in the dialog to verify that the address overlay was correctly applied.
- The automatically added address will not be displayed in the preview. It gets applied after getting send towards the E-POSTBUSINESS API.
Proceed with sending the document through confirming the dialog with the Ok action.

By utilizing the automatic address setter, users can ensure compliance with Deutsche Post's format requirements, reducing errors and optimizing dispatch efficiency.