Module LetterXpress
LetterXpress Module
| Module name | LetterXpress |
|---|---|
| Publisher | Goeger-IT |
| Status | Stable |
| Version | 1.0.0 |
| Module ID | 194020 |
| Compatibility | Dolibarr 18 to 24 (verified on 18.0.9, 20.0.4 and 24.0.0) |
| License | GNU GPL v3 or later |
| Languages | German and English |
Overview
LetterXpress sends Dolibarr business documents as physical letters through LetterXpress, a German letter service operated by A&O Fischer GmbH & Co. KG. The document PDF that Dolibarr already produces is handed to the service, which prints, folds, franks and posts it.
Sending is available from invoices, quotations, orders, shipments and contracts. A button on the document card opens a three-step wizard: choose the dispatch options, check the address, confirm.
The module does not modify Dolibarr core files. It adds its own table and integrates through hooks.
How the recipient address is determined
This section matters more than the feature list, and users of any letter service should read it before sending.
The LetterXpress API has no address field. LetterXpress reads the recipient address out of the PDF itself, from the DIN 5008 address window. This is normal for letter services, and it is also where things go wrong quietly: a template that places the address block a few millimetres off produces a letter that is printed, franked and never delivered. The sender finds out weeks later, if at all.
To make that visible before any money is spent, the module submits the letter in LetterXpress test mode first. Test mode parks the job in the LetterXpress postbox instead of printing it, costs nothing, and returns what the service actually parsed. The wizard then shows, side by side:
- the address LetterXpress read out of the PDF,
- the address Dolibarr holds for that customer,
- the page count, the price, the VAT and the current account balance.
Only then is the letter confirmed for real dispatch.
The comparison matches whole words. "Meier" is therefore not counted as a match for "Meiersberg GmbH", and house number 1 does not match number 12. Fields written in a script the comparison cannot read — Cyrillic, Greek, Turkish — are reported as unverifiable rather than as a match, so an international recipient never produces a false all-clear.
Main features
- Send invoices, quotations, orders, shipments and contracts as letters.
- Address preflight through LetterXpress test mode before any charge.
- Colour or black and white, simplex or duplex, national, international or automatic.
- Registered mail (Einschreiben Einwurf and Einschreiben), preferred dispatch date, C4 envelope for thicker letters.
- Account balance shown before confirmation, with a warning when it will not cover the letter.
- Dispatch log per document and system-wide, with delivery status and tracking code.
- Scheduled status synchronisation through Dolibarr's scheduled jobs.
- Protection against sending and paying twice after a network failure.
- Test mode for the entire workflow.
- Configurable retention: stored comparison addresses are blanked on completed jobs after a chosen number of days, while job numbers and costs are kept for accounting.
- Credentials stored encrypted, separately per entity (multi-company aware).
Installation
Download the module archive from DoliStore.
- Open Home → Setup → Modules/Applications → Deploy/install external app/module.
- Upload the archive.
- Open the tab Interfaces with external systems and enable LetterXpress.
Alternatively, copy the letterxpress directory into htdocs/custom/. This requires custom to be enabled as $dolibarr_main_document_root_alt in conf.php.
Configuration
Credentials
- Open the module setup page (gear icon next to the module).
- Enter the LetterXpress username and API key, found in the LetterXpress customer area under Mein Konto → Zugangsdaten → LXP API.
- Leave the operating mode on test for now.
- Use Test connection — the account balance must appear.
- Grant the module permissions to the relevant users under Home → Users & Groups → Permissions.
PDF layout
Four Dolibarr settings decide whether the recipient address lands inside the DIN 5008 window. Dolibarr's stock sponge template places it correctly once they are set. These values were measured against the live LetterXpress API, not estimated.
| Setting | Value | Effect |
|---|---|---|
MAIN_PDF_FORMAT |
EUA4 |
LetterXpress accepts A4 only |
MAIN_INVERT_SENDER_RECIPIENT |
1 |
puts the recipient on the left, where the window is |
MAIN_PDF_USE_ISO_LOCATION |
1 |
ISO/DIN vertical position of the address block |
MAIN_PDF_MARGIN_LEFT |
17 |
places the address block 20 mm from the paper edge |
Without the last setting the block starts at 13 mm, and the missing seven millimetres cut two to three characters off every line: LetterXpress then reads P Rechnungskontakt, stweg 5 instead of LXP Rechnungskontakt, Testweg 5, and the letter is not delivered.
The module's setup page checks all four settings and names the ones that are missing.
Existing PDFs keep their old layout — regenerate the documents after changing these settings, then run one address preflight on a test document to see what LetterXpress reads.
Scheduled job
Delivery status, tracking codes and the cleanup of abandoned preflights are handled exclusively by Dolibarr's scheduled jobs. The module performs no background work of its own.
This requires a working cron entry on the server calling php scripts/cron/cron_run_jobs.php, or the HTTP variant public/cron/cron_run_jobs_by_url.php where no shell access is available. Without it, jobs remain permanently at the status they had when they were submitted.
Check under Home → Admin tools → Scheduled jobs that the LetterXpress job is present and when it last ran.
Requirements
- Dolibarr 18.0 or later.
- PHP 7.4 or later with the curl extension.
- A LetterXpress account with API credentials.
- A working Dolibarr scheduled-jobs setup for automatic status updates.
Data protection
Sending — including the address preflight in test mode — transmits the complete document PDF and the recipient address it contains to A&O Fischer GmbH & Co. KG.
Under the GDPR the Dolibarr operator is the controller and LetterXpress is the processor; a data processing agreement under Art. 28 GDPR between those two parties is required for productive use. The module runs entirely on the operator's own server and communicates only with LetterXpress. It contains no telemetry and sends nothing to the module vendor, so no agreement with the vendor is needed to use it.
Known limitations
- In version 1.0.0 the permission labels are stored in English only and appear untranslated in the German interface.
- Dolibarr's own recovery for scheduled jobs that were interrupted hard can fail (
mysqli object is already closed), leaving a job permanently marked as running. This is core behaviour, not specific to this module; the job status can be reset under Home → Admin tools → Scheduled jobs. The module limits its batch to 30 jobs per run so that a run does not reach PHP execution limits in the first place.