Module PostmarkApp: Difference between revisions

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
VisualWikitext
(Création du module PostmarkApp)
Tag: 2017 source edit
 
(init)
Line 1: Line 1:
= POSTMARKAPP =
{{Dolibarr module
:subtitle: POSTMARKAPP DOCUMENTATION
|name=PostmarkApp
:source-highlighter: rouge
|logo=
:companyname: Lysis
|developer=Alex BORDARAUD - Lysis
:corpname: Lysis
|contact=alex@lysis.net
:orgname: Lysis
|website=https://lysis.net
:author: Alex BORDARAUD
|dolistore=
:email: alex@lysis.net
|version=1.5.2
:creator: Alex BORDARAUD
|dolibarr_min=19.0
:title: Documentation of module PostmarkApp
|dolibarr_max=
:subject: This document is the documentation of module PostmarkApp.
|license=GPLv3
:keywords: PostmarkApp, Postmark, Email, Dolibarr, Webhook
|language=Multi (FR, EN, DE, ES, IT, PT, NL)
:docdate: 2026-01-06
}}
:toc: manual
:toc-placement: preamble


'''PostmarkApp''' is a Dolibarr module that replaces the native email sending system with [https://postmarkapp.com Postmark], a professional transactional email service.


== TOPIC OF DOCUMENT
==Why use PostmarkApp?==


This is the documentation of module PostmarkApp - Postmark email integration for Dolibarr.
===English===


'''Legal proof and dispute resolution''': Having precise tracking of email delivery, opening, and link clicks provides valuable evidence in case of disputes. You can prove that:


*Log of versions of document*
*An invoice or quote was successfully delivered to your client
*The recipient opened the email and read it
*They clicked on links (payment, validation, etc.)


[options="header",format="csv"]
This traceability is essential for businesses that need to demonstrate that important information was transmitted and received.
|===
Author, Date, Version
Alex BORDARAUD <alex@lysis.net>, 2026-01-06, Version 1.5.2
|===


===Français===


[NOTE]
'''Preuve juridique et résolution de litiges'''<span> </span>: Disposer d'un suivi précis de la livraison, de l'ouverture et des clics sur les liens de vos emails constitue une preuve précieuse en cas de litige. Vous pouvez prouver que<span> </span>:
==============
This document was generated using Dolibarr ERP CRM process
==============


*Une facture ou un devis a bien été délivré à votre client
*Le destinataire a ouvert l'email et l'a lu
*Il a cliqué sur les liens (paiement, validation, etc.)


:toc: manual
Cette traçabilité est essentielle pour les entreprises qui doivent démontrer que des informations importantes ont été transmises et reçues.
:toc-placement: preamble


==Features==


*'''Email Sending via Postmark API''' - All Dolibarr emails are sent through Postmark
*'''Delivery Tracking''' - Know when your emails are delivered
*'''Open Tracking''' - Track when recipients open your emails (first open only)
*'''Click Tracking''' - Monitor which links are clicked in your emails
*'''Bounce Handling''' - Automatically handle bounced emails
*'''Spam Complaint Tracking''' - Be notified of spam complaints
*'''Dolibarr Events Integration''' - All email events are logged in Dolibarr's Agenda module
*'''Object Linking''' - Events are linked to related Dolibarr objects (invoices, proposals, orders, etc.)
*'''Multi-language''' - Available in 7 languages (FR, EN, DE, ES, IT, PT, NL)


== INTRODUCTION
==Requirements==


=== English
*Dolibarr 19.0 or higher
*PHP 7.1 or higher with cURL extension
*Postmark account with Server API Token
*Agenda module must be enabled


PostmarkApp is a Dolibarr module that replaces the native email sending system with Postmark's transactional email service. It provides advanced email tracking capabilities including delivery confirmation, open tracking, click tracking, and bounce handling.
==Installation==


=== Français
#Download the module package <code>module_postmarkapp-x.y.z.zip</code>
#Extract to <code>htdocs/custom/postmarkapp/</code> or use Dolibarr's module deployment feature
#Go to '''Home > Setup > Modules/Applications'''
#Search for "PostmarkApp" and enable the module
#Configure the module in '''Setup > Modules > PostmarkApp > Settings'''


PostmarkApp est un module Dolibarr qui remplace le système natif d'envoi d'emails par le service de messagerie transactionnelle Postmark. Il offre des fonctionnalités avancées de suivi des emails incluant la confirmation de livraison, le suivi d'ouverture, le suivi des clics et la gestion des rebonds.
==Configuration==


===Step 1: Server API Token===


== FEATURES / FONCTIONNALITÉS
#Log in to your Postmark account at https://postmarkapp.com
#Select your server
#Go to '''API Tokens''' tab
#Copy the '''Server API Token'''
#Paste it in the PostmarkApp configuration page
#Click '''Validate''' to test the connection


=== English
===Step 2: Options===


* *Email Sending via Postmark API*: All emails sent from Dolibarr are routed through Postmark
*'''Message Stream''': Select the message stream to use (default: "outbound")
* *Delivery Tracking*: Know when your emails are delivered
*'''Track Opens''': Enable/disable open tracking
* *Open Tracking*: Track when recipients open your emails (first open only)
*'''Track Clicks''': Enable/disable click tracking (requires HTML emails)
* *Click Tracking*: Monitor which links are clicked in your emails
*'''Replace Dolibarr Mailer''': Enable to route all emails through Postmark
* *Bounce Handling*: Automatically handle bounced emails
* *Spam Complaint Tracking*: Be notified of spam complaints
* *Dolibarr Events Integration*: All email events are logged in Dolibarr's agenda
* *Object Linking*: Events are linked to related Dolibarr objects (third parties, contacts, proposals, invoices, etc.)


=== Français
===Step 3: Webhook===
 
* *Envoi d'emails via l'API Postmark* : Tous les emails envoyés depuis Dolibarr passent par Postmark
* *Suivi de livraison* : Savoir quand vos emails sont livrés
* *Suivi d'ouverture* : Suivre quand les destinataires ouvrent vos emails (première ouverture uniquement)
* *Suivi des clics* : Surveiller les liens cliqués dans vos emails
* *Gestion des rebonds* : Gérer automatiquement les emails rebondis
* *Suivi des plaintes spam* : Être notifié des plaintes spam
* *Intégration événements Dolibarr* : Tous les événements email sont enregistrés dans l'agenda Dolibarr
* *Liaison aux objets* : Les événements sont liés aux objets Dolibarr concernés
 
 
== REQUIREMENTS / PRÉREQUIS
 
* Dolibarr 16.0+
* PHP 7.4+ with cURL extension
* Postmark account with Server API Token
* Agenda module enabled in Dolibarr
 
 
== INSTALLATION
 
=== English
 
1. Download the module package `module_postmarkapp-x.y.z.zip`
2. Extract to `htdocs/custom/postmarkapp/` or use Dolibarr's module deployment feature
3. Go to *Home > Setup > Modules/Applications*
4. Search for "PostmarkApp" and enable the module
5. Configure the module in *Setup > Modules > PostmarkApp Setup*
 
=== Français
 
1. Téléchargez le package `module_postmarkapp-x.y.z.zip`
2. Extrayez dans `htdocs/custom/postmarkapp/` ou utilisez le déploiement de modules Dolibarr
3. Allez dans *Accueil > Configuration > Modules/Applications*
4. Recherchez "PostmarkApp" et activez le module
5. Configurez dans *Configuration > Modules > Configuration PostmarkApp*
 
 
== CONFIGURATION
 
=== Step 1: Server API Token / Étape 1 : Server API Token
 
1. Log in to your Postmark account at https://postmarkapp.com
2. Select your server / Sélectionnez votre serveur
3. Go to *API Tokens* tab / Allez dans l'onglet *API Tokens*
4. Copy the *Server API Token* / Copiez le *Server API Token*
5. Paste it in the PostmarkApp configuration page / Collez-le dans la page de configuration
6. Click *Validate* to test the connection / Cliquez sur *Valider* pour tester
 
=== Step 2: Options / Étape 2 : Options
 
* *Message Stream*: Select the message stream (default: "outbound") / Sélectionnez le flux de messages
* *Track Opens*: Enable/disable open tracking / Activer/désactiver le suivi d'ouverture
* *Track Clicks*: Enable/disable click tracking (requires HTML emails) / Activer/désactiver le suivi des clics
* *Replace Dolibarr Mailer*: Enable to route all emails through Postmark / Activer pour router tous les emails via Postmark
 
=== Step 3: Webhook (Optional) / Étape 3 : Webhook (Optionnel)


Webhooks allow Postmark to notify Dolibarr of email events in real-time.
Webhooks allow Postmark to notify Dolibarr of email events in real-time.
Les webhooks permettent à Postmark de notifier Dolibarr des événements email en temps réel.


*Automatic Setup / Configuration automatique:*
'''Automatic Setup:'''
Click *Create Webhook Automatically* / Cliquez sur *Créer le webhook automatiquement*


*Manual Setup / Configuration manuelle:*
*Click '''Create Webhook Automatically'''
*The webhook URL will be registered with Postmark


1. Copy the webhook URL displayed in the configuration / Copiez l'URL du webhook affichée
'''Manual Setup:'''
2. Go to Postmark > Servers > Your Server > Webhooks / Allez dans Postmark > Servers > Votre serveur > Webhooks
3. Add a new webhook with the copied URL / Ajoutez un nouveau webhook avec l'URL copiée
4. Enable: Delivery, Open (First Open Only), Click, Bounce, Spam Complaint / Activez ces événements


#Copy the webhook URL displayed in the configuration
#Go to Postmark > Servers > Your Server > Webhooks
#Add a new webhook with the copied URL
#Enable: Delivery, Open (First Open Only), Click, Bounce, Spam Complaint


== DATA SPECIFICATIONS
==How it works==


=== Database Table: llx_postmarkapp_events
Once enabled, all emails sent from Dolibarr will be routed through Postmark. The module intercepts the native email sending and replaces it with Postmark's API.


.Database columns
When a webhook is configured, Postmark will notify your Dolibarr installation of email events:
[cols="20,20,60",frame="topbot"]
|====
|Column |Type |Description


|rowid |INTEGER |Primary key / Clé primaire
{| class="wikitable"
|email_id |VARCHAR(255) |Postmark MessageID
!Event!!Description!!Dolibarr Code
|event_type |VARCHAR(50) |Event type (Sent, Delivery, Open, Click, Bounce, SpamComplaint)
|-
|recipient |VARCHAR(255) |Email recipient / Destinataire
|Sent||Email sent via Postmark||POSTMARK_SENT
|subject |VARCHAR(255) |Email subject / Sujet
|-
|fk_soc |INTEGER |Linked third party ID / ID tiers lié
|Delivered||Email delivered to recipient's server||POSTMARK_DELIVERY
|fk_contact |INTEGER |Linked contact ID / ID contact lié
|-
|fk_element |INTEGER |Linked element ID / ID élément lié
|Opened||Recipient opened the email||POSTMARK_OPEN
|element_type |VARCHAR(50) |Element type (propal, facture, commande, etc.)
|-
|fk_actioncomm |INTEGER |Linked ActionComm ID / ID événement lié
|Clicked||Recipient clicked a link||POSTMARK_CLICK
|event_data |TEXT |JSON data from webhook / Données JSON du webhook
|-
|date_creation |DATETIME |Event timestamp / Horodatage
|Bounced||Email could not be delivered||POSTMARK_BOUNCE
|====
|-
|Spam||Recipient marked as spam||POSTMARK_SPAM_COMPLAINT
|}


Each event creates an entry in Dolibarr's Agenda, linked to the original object.


== EVENT TYPES / TYPES D'ÉVÉNEMENTS
==Database==


.Event types
The module creates one custom table:
[cols="15,25,25,35",frame="topbot"]
|====
|Event |Description EN |Description FR |Code


|Sent |Email sent via Postmark |Email envoyé via Postmark |POSTMARK_SENT
{| class="wikitable"
|Delivered |Email delivered |Email délivré |POSTMARK_DELIVERY
!Column!!Type!!Description
|Opened |Email opened |Email lu |POSTMARK_OPEN
|-
|Clicked |Link clicked |Lien cliqué |POSTMARK_CLICK
|rowid||INTEGER||Primary key
|Bounced |Email bounced |Email rebondi |POSTMARK_BOUNCE
|-
|Spam |Spam complaint |Plainte spam |POSTMARK_SPAM_COMPLAINT
|email_id||VARCHAR(255)||Postmark MessageID
|====
|-
|event_type||VARCHAR(50)||Event type
|-
|recipient||VARCHAR(255)||Email recipient
|-
|subject||VARCHAR(255)||Email subject
|-
|fk_soc||INTEGER||Linked third party ID
|-
|fk_contact||INTEGER||Linked contact ID
|-
|fk_element||INTEGER||Linked element ID
|-
|element_type||VARCHAR(50)||Element type (propal, facture, etc.)
|-
|fk_actioncomm||INTEGER||Linked ActionComm ID
|-
|event_data||TEXT||JSON data from webhook
|-
|date_creation||DATETIME||Event timestamp
|}


==Troubleshooting==


== MATRIX OF PERMISSIONS / MATRICE DES PERMISSIONS
===Emails not sending===


.Permissions
#Check that <code>POSTMARKAPP_REPLACE_MAILER</code> is enabled
[cols="20,40,40",frame="topbot"]
#Verify the Server API Token is valid
|====
#Check Dolibarr logs for error messages
|Permission |Description |PHP Check
#Ensure the "From" address is a verified Sender Signature in Postmark


|Read |Read PostmarkApp configuration |$user->hasRight('postmarkapp', 'read')
===Webhooks not received===
|Write |Modify PostmarkApp configuration |$user->hasRight('postmarkapp', 'write')
|====


#Verify the webhook URL is accessible from the internet
#Check that webhooks are created in Postmark dashboard
#Test webhooks using the built-in test buttons
#Check server logs for incoming requests


== TROUBLESHOOTING / DÉPANNAGE
===Click tracking not working===
 
=== Emails not sending / Emails non envoyés
 
1. Check that `POSTMARKAPP_REPLACE_MAILER` is enabled / Vérifiez que `POSTMARKAPP_REPLACE_MAILER` est activé
2. Verify the Server API Token is valid / Vérifiez que le Server API Token est valide
3. Check Dolibarr logs for error messages / Consultez les logs Dolibarr
4. Ensure the "From" address is a verified Sender Signature in Postmark / Vérifiez que l'adresse "From" est vérifiée dans Postmark
 
=== Webhooks not received / Webhooks non reçus
 
1. Verify the webhook URL is accessible from the internet / Vérifiez que l'URL est accessible depuis Internet
2. Check that webhooks are created in Postmark dashboard / Vérifiez les webhooks dans Postmark
3. Test webhooks using the built-in test buttons / Testez avec les boutons intégrés
 
=== Click tracking not working / Suivi des clics non fonctionnel


Click tracking requires emails to be sent in HTML format. Plain text emails cannot track clicks.
Click tracking requires emails to be sent in HTML format. Plain text emails cannot track clicks.
Le suivi des clics nécessite des emails au format HTML. Les emails texte brut ne peuvent pas suivre les clics.


==Screenshots==


== API DOCUMENTATION
<!-- Add screenshots here -->


=== Postmark API Endpoints Used
==Changelog==


* `POST /email` - Send email
===Version 1.5.2 (2026-01-06)===
* `GET /server` - Test connection
* `GET /message-streams` - List message streams
* `GET /senders` - List sender signatures
* `GET /webhooks` - List webhooks
* `POST /webhooks` - Create webhook


=== Webhook Endpoint
*Simplified event notes and labels
*Removed duplicate "Sent" event
*Added bilingual documentation
*Added multi-language support


`POST /custom/postmarkapp/webhook.php`
==Links==


Receives webhook notifications from Postmark for the following events:
*[https://postmarkapp.com Postmark Official Website]
- Delivery
*[https://lysis.net Lysis - Developer Website]
- Open (First Open Only)
- Click
- Bounce
- SpamComplaint


==License==


== CHANGELOG
This module is distributed under the [https://www.gnu.org/licenses/gpl-3.0 GNU General Public License v3 (GPLv3)].


See link:../CHANGELOG.md[CHANGELOG.md] for full version history.
==Professional Services / Services professionnels==


=== Version 1.5.2 (2026-01-06)
===English===


* Simplified event notes and labels
'''Need help with setup?''' We can assist you with:
* Removed duplicate "Sent" event (uses Dolibarr native system)
* Added bilingual documentation
* Added multi-language support (FR, EN, DE, ES, IT, PT, NL)
* Added Agenda module dependency
* Added automatic triggers for Postmark events


=== Version 1.0 (2026-01-06)
*Installation and configuration of the PostmarkApp module
*Postmark account setup and sender signature verification
*Webhook configuration and testing
*Integration with your existing Dolibarr workflows
*Training for your team


* Initial release
Contact us for a personalized quote.
* Postmark API integration
* Webhook handling
* Event tracking


===Français===


== LICENSE
'''Besoin d'aide pour le paramétrage ?''' Nous pouvons vous accompagner pour<span> </span>:


This module is distributed under the GNU General Public License v3 (GPLv3).
*L'installation et la configuration du module PostmarkApp
*La création de votre compte Postmark et la vérification des signatures d'expéditeur
*La configuration et les tests des webhooks
*L'intégration avec vos processus Dolibarr existants
*La formation de vos équipes


Copyright (C) 2026 Lysis - Alex BORDARAUD
Contactez-nous pour un devis personnalisé.


== SUPPORT
==Author==


For support, please contact: alex@lysis.net
'''Alex BORDARAUD'''<br />
Website: https://lysis.net
Website: https://lysis.net
[[Category:External module]]
[[Category:Communication module]]
[[Category:Email module]]

Revision as of 13:27, 6 January 2026

Template:Dolibarr module

PostmarkApp is a Dolibarr module that replaces the native email sending system with Postmark, a professional transactional email service.

Why use PostmarkApp?

English

Legal proof and dispute resolution: Having precise tracking of email delivery, opening, and link clicks provides valuable evidence in case of disputes. You can prove that:

  • An invoice or quote was successfully delivered to your client
  • The recipient opened the email and read it
  • They clicked on links (payment, validation, etc.)

This traceability is essential for businesses that need to demonstrate that important information was transmitted and received.

Français

Preuve juridique et résolution de litiges : Disposer d'un suivi précis de la livraison, de l'ouverture et des clics sur les liens de vos emails constitue une preuve précieuse en cas de litige. Vous pouvez prouver que :

  • Une facture ou un devis a bien été délivré à votre client
  • Le destinataire a ouvert l'email et l'a lu
  • Il a cliqué sur les liens (paiement, validation, etc.)

Cette traçabilité est essentielle pour les entreprises qui doivent démontrer que des informations importantes ont été transmises et reçues.

Features

  • Email Sending via Postmark API - All Dolibarr emails are sent through Postmark
  • Delivery Tracking - Know when your emails are delivered
  • Open Tracking - Track when recipients open your emails (first open only)
  • Click Tracking - Monitor which links are clicked in your emails
  • Bounce Handling - Automatically handle bounced emails
  • Spam Complaint Tracking - Be notified of spam complaints
  • Dolibarr Events Integration - All email events are logged in Dolibarr's Agenda module
  • Object Linking - Events are linked to related Dolibarr objects (invoices, proposals, orders, etc.)
  • Multi-language - Available in 7 languages (FR, EN, DE, ES, IT, PT, NL)

Requirements

  • Dolibarr 19.0 or higher
  • PHP 7.1 or higher with cURL extension
  • Postmark account with Server API Token
  • Agenda module must be enabled

Installation

  1. Download the module package module_postmarkapp-x.y.z.zip
  2. Extract to htdocs/custom/postmarkapp/ or use Dolibarr's module deployment feature
  3. Go to Home > Setup > Modules/Applications
  4. Search for "PostmarkApp" and enable the module
  5. Configure the module in Setup > Modules > PostmarkApp > Settings

Configuration

Step 1: Server API Token

  1. Log in to your Postmark account at https://postmarkapp.com
  2. Select your server
  3. Go to API Tokens tab
  4. Copy the Server API Token
  5. Paste it in the PostmarkApp configuration page
  6. Click Validate to test the connection

Step 2: Options

  • Message Stream: Select the message stream to use (default: "outbound")
  • Track Opens: Enable/disable open tracking
  • Track Clicks: Enable/disable click tracking (requires HTML emails)
  • Replace Dolibarr Mailer: Enable to route all emails through Postmark

Step 3: Webhook

Webhooks allow Postmark to notify Dolibarr of email events in real-time.

Automatic Setup:

  • Click Create Webhook Automatically
  • The webhook URL will be registered with Postmark

Manual Setup:

  1. Copy the webhook URL displayed in the configuration
  2. Go to Postmark > Servers > Your Server > Webhooks
  3. Add a new webhook with the copied URL
  4. Enable: Delivery, Open (First Open Only), Click, Bounce, Spam Complaint

How it works

Once enabled, all emails sent from Dolibarr will be routed through Postmark. The module intercepts the native email sending and replaces it with Postmark's API.

When a webhook is configured, Postmark will notify your Dolibarr installation of email events:

Event Description Dolibarr Code
Sent Email sent via Postmark POSTMARK_SENT
Delivered Email delivered to recipient's server POSTMARK_DELIVERY
Opened Recipient opened the email POSTMARK_OPEN
Clicked Recipient clicked a link POSTMARK_CLICK
Bounced Email could not be delivered POSTMARK_BOUNCE
Spam Recipient marked as spam POSTMARK_SPAM_COMPLAINT

Each event creates an entry in Dolibarr's Agenda, linked to the original object.

Database

The module creates one custom table:

Column Type Description
rowid INTEGER Primary key
email_id VARCHAR(255) Postmark MessageID
event_type VARCHAR(50) Event type
recipient VARCHAR(255) Email recipient
subject VARCHAR(255) Email subject
fk_soc INTEGER Linked third party ID
fk_contact INTEGER Linked contact ID
fk_element INTEGER Linked element ID
element_type VARCHAR(50) Element type (propal, facture, etc.)
fk_actioncomm INTEGER Linked ActionComm ID
event_data TEXT JSON data from webhook
date_creation DATETIME Event timestamp

Troubleshooting

Emails not sending

  1. Check that POSTMARKAPP_REPLACE_MAILER is enabled
  2. Verify the Server API Token is valid
  3. Check Dolibarr logs for error messages
  4. Ensure the "From" address is a verified Sender Signature in Postmark

Webhooks not received

  1. Verify the webhook URL is accessible from the internet
  2. Check that webhooks are created in Postmark dashboard
  3. Test webhooks using the built-in test buttons
  4. Check server logs for incoming requests

Click tracking not working

Click tracking requires emails to be sent in HTML format. Plain text emails cannot track clicks.

Screenshots

Changelog

Version 1.5.2 (2026-01-06)

  • Simplified event notes and labels
  • Removed duplicate "Sent" event
  • Added bilingual documentation
  • Added multi-language support

Links

License

This module is distributed under the GNU General Public License v3 (GPLv3).

Professional Services / Services professionnels

English

Need help with setup? We can assist you with:

  • Installation and configuration of the PostmarkApp module
  • Postmark account setup and sender signature verification
  • Webhook configuration and testing
  • Integration with your existing Dolibarr workflows
  • Training for your team

Contact us for a personalized quote.

Français

Besoin d'aide pour le paramétrage ? Nous pouvons vous accompagner pour :

  • L'installation et la configuration du module PostmarkApp
  • La création de votre compte Postmark et la vérification des signatures d'expéditeur
  • La configuration et les tests des webhooks
  • L'intégration avec vos processus Dolibarr existants
  • La formation de vos équipes

Contactez-nous pour un devis personnalisé.

Author

Alex BORDARAUD
Website: https://lysis.net

Retrieved from "https://wiki.dolibarr.org/index.php?title=Module_PostmarkApp&oldid=65138"