Module PostmarkApp

Informations

Module name	PostmarkApp
Editor / Editeur	Alex BORDARAUD - Lysis https://lysis.net
Download or buy page / Page achat ou téléchargement
Status / Statut / Estado	Stable
Prerequisites / Prérequis
Last update date / Date mise à jour fiche / Fecha última actualización	2026-01-6
Note / Nota

PostmarkApp is a professional Dolibarr module that integrates Postmark, a transactional email service, to replace Dolibarr's native email sending system. It provides complete email traceability, real-time event tracking, and seamless integration with Dolibarr's Agenda module.

Description

English

PostmarkApp transforms your email communications in Dolibarr by providing enterprise-grade email delivery and tracking. Unlike standard SMTP, Postmark ensures high deliverability rates and provides detailed analytics on every email sent.

Key Benefits:

100% Email Traceability: Track every email from sending to delivery, opening, and link clicks
Professional Delivery: Postmark's infrastructure ensures 99.9% deliverability
Real-time Notifications: Instant webhook notifications for all email events
Complete Integration: All events automatically logged in Dolibarr's Agenda
Multi-Entity Support: Full compatibility with Dolibarr's MultiCompany module
User Ownership: Events are owned by the user who sent the email for proper notifications

Français

PostmarkApp transforme vos communications email dans Dolibarr en fournissant une livraison et un suivi d'emails de niveau entreprise. Contrairement au SMTP standard, Postmark garantit des taux de délivrabilité élevés et fournit des analyses détaillées sur chaque email envoyé.

Avantages principaux :

Traçabilité 100% des emails : Suivez chaque email de l'envoi à la livraison, l'ouverture et les clics
Livraison professionnelle : L'infrastructure Postmark garantit 99,9% de délivrabilité
Notifications en temps réel : Notifications webhook instantanées pour tous les événements email
Intégration complète : Tous les événements automatiquement enregistrés dans l'Agenda Dolibarr
Support Multi-Entités : Compatibilité complète avec le module MultiCompany de Dolibarr
Propriété utilisateur : Les événements appartiennent à l'utilisateur qui a envoyé l'email pour des notifications correctes

Features

Core Features

Email Sending via Postmark API

 * Intercepts all Dolibarr email sending via hooks
 * Sends emails through Postmark's REST API
 * Supports HTML and plain text emails (auto-converts if needed)
 * Handles attachments, CC, BCC, Reply-To headers
 * Supports multiple message streams (transactional, marketing)

Real-time Event Tracking

 * Sent: Email successfully sent via Postmark
 * Delivered: Email delivered to recipient's mail server
 * Opened: Recipient opened the email (first open only)
 * Clicked: Recipient clicked a link in the email
 * Bounced: Email delivery failed (hard/soft bounce)
 * Spam Complaint: Recipient marked email as spam

Dolibarr Integration

 * All events automatically created in Dolibarr's Agenda module
 * Events linked to original Dolibarr objects (invoices, proposals, orders, etc.)
 * Events linked to third parties and contacts
 * Parent-child relationships between events (Sent → Delivery → Open → Click)
 * User ownership: events belong to the user who sent the email

Automatic Triggers

 * Six automatic triggers registered in Dolibarr's Agenda
 * Automatically enabled on module activation
 * Configurable in Setup > Modules > Agenda > Automatic events
 * Can trigger custom workflows based on email events

Multi-Entity Support (MultiCompany)

 * Full compatibility with Dolibarr's MultiCompany module
 * Entity field in database for data isolation
 * Configurable sharing between entities
 * Automatic entity assignment based on email sender's entity

Comprehensive Event Management

 * Dedicated events list page with advanced filters
 * Filter by date, event type, recipient, subject, third party, contact, linked object, message ID
 * Search by object reference
 * Direct links to related Dolibarr objects
 * Link to ActionComm events

Webhook Management

 * Automatic webhook creation via Postmark API
 * Manual webhook configuration support
 * Built-in webhook testing tools
 * Webhook signature validation (optional)

Multi-language Support

 * Available in 7 languages: French, English, German, Spanish, Italian, Portuguese, Dutch
 * All interface elements translated
 * Event labels and descriptions translated

Requirements

System Requirements

Dolibarr: Version 19.0 or higher
PHP: Version 7.1 or higher
PHP Extensions: cURL (required for API calls)
Postmark Account: Active account with at least one server
Server API Token: From Postmark dashboard
Agenda Module: Must be enabled (mandatory dependency)

Postmark Requirements

Verified Sender Signatures for the "From" email addresses
Server API Token (found in Postmark > Servers > API Tokens)
Webhook URL accessible from internet (for event tracking)

Installation

Step-by-Step Installation

Download the module package module_postmarkapp-x.y.z.zip
Extract to htdocs/custom/postmarkapp/ directory
Go to Home > Setup > Modules/Applications
Search for "PostmarkApp" in the module list
Click Enable to activate the module
The module will automatically:

 * Create the llx_postmarkapp_events table
 * Register automatic triggers in Agenda
 * Configure MultiCompany sharing (if MultiCompany module is enabled)

Configure the module in Setup > Modules > PostmarkApp > Settings

Post-Installation

After installation, verify:

The llx_postmarkapp_events table exists in your database
The Agenda module is enabled
Automatic triggers are visible in Setup > Modules > Agenda > Automatic events

Configuration

Step 1: Server API Token

The Server API Token is the primary authentication method for Postmark.

Log in to your Postmark account at https://postmarkapp.com
Navigate to Servers and select your server
Go to the API Tokens tab
Copy the Server API Token (starts with a long alphanumeric string)
Paste it in the PostmarkApp configuration page under "Server API Token"
Click Validate to test the connection
If successful, you'll see a green confirmation message

Security Note: The token is stored encrypted in Dolibarr's constants table.

Step 2: Options

Message Stream:

 * Select the Postmark message stream to use
 * Default: "outbound" (transactional emails)
 * Alternative: "broadcast" (marketing emails)
 * Streams are automatically loaded from your Postmark account

Track Opens:

 * Enable/disable open tracking
 * When enabled, Postmark tracks when emails are opened
 * Only the first open is tracked (PostFirstOpenOnly)

Track Clicks:

 * Enable/disable click tracking
 * Requires HTML emails - plain text emails cannot track clicks
 * When enabled, all links in emails are rewritten by Postmark for tracking

Replace Dolibarr Mailer:

 * Enable to route ALL Dolibarr emails through Postmark
 * When disabled, Dolibarr uses its native email system
 * Recommended: Keep enabled for consistent tracking

Step 3: Webhook Configuration (Optional but Recommended)

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

Automatic Setup:

Ensure your Server API Token is validated
Click Create Webhook Automatically
The module will:

 * Generate the webhook URL (format: https://yourdomain.com/dolibarr/custom/postmarkapp/webhook.php)
 * Create the webhook in Postmark via API
 * Configure it to listen for: Delivery, Open (First Open Only), Click, Bounce, Spam Complaint

You'll see a confirmation message with the webhook ID

Manual Setup:

Copy the webhook URL displayed in the configuration page
Log in to Postmark dashboard
Go to Servers > Your Server > Webhooks
Click Add Webhook
Paste the URL
Enable the following triggers:

 * Delivery
 * Open (select "First Open Only")
 * Click
 * Bounce
 * Spam Complaint

Save the webhook

Testing Webhooks: The configuration page includes test buttons to simulate webhook events:

Test Delivery
Test Open
Test Click
Test Bounce

These send test payloads to your webhook endpoint for verification.

Step 4: Testing

Click Test Connection to verify API connectivity
Click Send Test Email to send a test email to your logged-in user's email address
The test email includes:

 * HTML and plain text versions
 * A trackable link to test click tracking
 * Metadata for webhook linking

Check your email inbox and verify delivery
Use the webhook test buttons to verify event processing

MultiCompany Compatibility

PostmarkApp is fully compatible with Dolibarr's MultiCompany module.

How It Works

Each email event is stored with an entity field
By default, events are isolated per entity (entity = current entity)
Events can be shared between entities if MultiCompany sharing is enabled

Configuration

Enable the MultiCompany module in Dolibarr
Go to Setup > Modules > MultiCompany > Options
Find the "PostmarkApp Events" sharing option
Enable/disable sharing as needed

Sharing Behavior

Sharing Disabled: Each entity only sees its own email events
Sharing Enabled: Events can be shared between entities (entity IN (0, entity1, entity2, ...))
The webhook automatically uses the entity from the original "Sent" event

Entity Assignment

When an email is sent, the event is assigned to the current entity ($conf->entity)
Webhook events inherit the entity from the original "Sent" event
This ensures proper data isolation and sharing

Technical Architecture

Module Structure

postmarkapp/
├── core/
│   └── modules/
│       └── modPostmarkApp.class.php    # Module descriptor
├── class/
│   └── actions_postmarkapp.class.php   # Hook handlers
├── lib/
│   └── class/
│       └── postmarkappmail.class.php   # Postmark API wrapper
├── admin/
│   └── setup.php                       # Configuration page
├── events.php                           # Events list page
├── webhook.php                          # Webhook endpoint
└── langs/
    └── [lang]/
        └── postmarkapp.lang            # Translations

Hooks System

The module uses Dolibarr's hook system to intercept email sending:

Hook Name: sendMail
Hook File: class/actions_postmarkapp.class.php
Hook Method: sendMail($parameters, &$object, &$action, $hookmanager)

How It Works:

Dolibarr prepares to send an email via CMailFile
The hook intercepts the email before native sending
Extracts email data (to, subject, body, attachments, etc.)
Sends email via Postmark API using PostmarkAppMail class
Logs the "Sent" event to database
Returns 1 to prevent native Dolibarr email sending

API Integration

The module uses Postmark's REST API:

Base URL: https://api.postmarkapp.com
Authentication: X-Postmark-Server-Token header
Endpoints Used:

 * POST /email - Send email
 * GET /server - Test connection
 * GET /message-streams - List streams
 * GET /senders - List sender signatures
 * GET /webhooks - List webhooks
 * POST /webhooks - Create webhook

Database Schema

The module creates one custom table: llx_postmarkapp_events

Column	Type	Null	Default	Description
rowid	INTEGER	NO	AUTO_INCREMENT	Primary key
email_id	VARCHAR(255)	NO		Postmark MessageID (unique identifier)
event_type	VARCHAR(50)	NO		Event type (Sent, Delivery, Open, Click, Bounce, SpamComplaint)
recipient	VARCHAR(255)	YES	NULL	Email recipient address
subject	VARCHAR(255)	YES	NULL	Email subject line
fk_soc	INTEGER	YES	NULL	Linked third party ID (llx_societe.rowid)
fk_contact	INTEGER	YES	NULL	Linked contact ID (llx_socpeople.rowid)
fk_element	INTEGER	YES	NULL	Linked element ID (depends on element_type)
element_type	VARCHAR(50)	YES	NULL	Element type (propal, facture, commande, etc.)
fk_user	INTEGER	YES	NULL	User ID who sent the email (for event ownership)
fk_actioncomm	INTEGER	YES	NULL	Linked ActionComm ID (llx_actioncomm.rowid)
event_data	TEXT	YES	NULL	JSON data from webhook (full payload)
entity	INTEGER	NO	1	Entity ID (for MultiCompany)
date_creation	DATETIME	NO		Event timestamp

Indexes:

idx_email_id on email_id
idx_event_type on event_type
idx_date_creation on date_creation
idx_fk_soc on fk_soc
idx_fk_contact on fk_contact
idx_fk_element on fk_element
idx_fk_user on fk_user
idx_entity on entity

Supported Object Types

The module can link email events to various Dolibarr objects:

Object Type	Description	Table
propal	Customer Proposal	llx_propal
commande	Customer Order	llx_commande
facture	Customer Invoice	llx_facture
expedition	Shipment	llx_expedition
contrat	Contract	llx_contrat
fichinter	Intervention	llx_fichinter
facture_fourn	Supplier Invoice	llx_facture_fourn
order_supplier	Supplier Order	llx_commande_fournisseur
supplier_proposal	Supplier Proposal	llx_supplier_proposal
project	Project	llx_projet
ticket	Ticket	llx_ticket
member	Member	llx_adherent
reception	Reception	llx_reception
expensereport	Expense Report	llx_expensereport

Automatic Triggers

The module registers 6 automatic triggers in Dolibarr's Agenda system:

Trigger Code	Label Key	Description Key	Rang
POSTMARK_SENT	PostmarkTriggerSent	PostmarkTriggerSentDesc	50100
POSTMARK_DELIVERY	PostmarkTriggerDelivery	PostmarkTriggerDeliveryDesc	50101
POSTMARK_OPEN	PostmarkTriggerOpen	PostmarkTriggerOpenDesc	50102
POSTMARK_CLICK	PostmarkTriggerClick	PostmarkTriggerClickDesc	50103
POSTMARK_BOUNCE	PostmarkTriggerBounce	PostmarkTriggerBounceDesc	50104
POSTMARK_SPAMCOMPLAINT	PostmarkTriggerSpam	PostmarkTriggerSpamDesc	50105

These triggers are:

Automatically registered on module activation
Automatically enabled (constants MAIN_AGENDA_ACTIONAUTO_* set to 1)
Configurable in Setup > Modules > Agenda > Automatic events
Can trigger custom workflows based on email events

Permissions

The module defines two permissions:

postmarkapp_read: View email events (required for events list page)
postmarkapp_setup: Configure the module (required for setup page)

Permissions are checked using: if ($user->hasRight('postmarkapp', 'read')) if ($user->hasRight('postmarkapp', 'setup'))

Webhook Processing

The webhook endpoint (webhook.php) processes incoming Postmark events:

Receives POST request from Postmark with JSON payload
Validates webhook signature (optional, if configured)
Extracts event data (type, recipient, message ID, metadata)
Searches for original "Sent" event by MessageID
Retrieves linked objects (third party, contact, element) from original event
Creates ActionComm event in Dolibarr's Agenda
Sets event ownership to original sender's user ID
Links event to original ActionComm (parent-child relationship)
Stores detailed event data in llx_postmarkapp_events table
Returns HTTP 200 to Postmark

SQL Queries and MultiCompany

All SQL queries use getEntity() function for MultiCompany compatibility:

SELECT * FROM llx_postmarkapp_events WHERE entity IN (getEntity('postmarkapp_events'))

This ensures:

Data isolation per entity (by default)
Data sharing when MultiCompany sharing is enabled
Proper entity assignment on insert

How It Works

Email Sending Flow

User triggers email sending in Dolibarr (e.g., sending an invoice)
Dolibarr prepares CMailFile object with email data
PostmarkApp hook intercepts via sendMail hook
Module extracts:

 * Recipient(s), subject, body (HTML/text), attachments
 * Linked objects (from trackid or metadata)
 * Current user ID (for event ownership)

Email sent via Postmark API
Postmark returns MessageID
Module logs "Sent" event to database with:

 * MessageID, recipient, subject, linked objects, user ID, entity

Returns 1 to prevent native Dolibarr email sending

Webhook Event Flow

Postmark detects email event (delivery, open, click, bounce, spam)
Postmark sends POST request to webhook URL with JSON payload
Webhook endpoint receives and validates request
Searches for original "Sent" event using MessageID
Retrieves:

 * Linked objects (third party, contact, element)
 * User ID who sent the email
 * Entity ID
 * Original ActionComm ID

Creates new ActionComm event:

 * Type: AC_EMAIL
 * Code: POSTMARK_[EVENT_TYPE]
 * Label: Translated event label
 * Owner: Original sender's user ID
 * Parent: Original ActionComm ID
 * Linked to: Third party, contact, element

Stores event in llx_postmarkapp_events table
Returns success to Postmark

Event Linking

Events are automatically linked to Dolibarr objects:

From trackid: Parses Dolibarr's trackid format (e.g., "pro1" = proposal ID 1)
From metadata: Extracts fk_soc, fk_contact, fk_element, element_type
From recipient email: Searches third parties and contacts by email address
From MessageID: Webhook events link to original "Sent" event via MessageID

Event Types

Event Type	Description	When It Occurs	Dolibarr Code	ActionComm Type
Sent	Email sent via Postmark	Immediately after API call	POSTMARK_SENT	AC_EMAIL
Delivery	Email delivered	When recipient's server accepts	POSTMARK_DELIVERY	AC_EMAIL
Open	Email opened	First time recipient opens email	POSTMARK_OPEN	AC_EMAIL
Click	Link clicked	When recipient clicks a tracked link	POSTMARK_CLICK	AC_EMAIL
Bounce	Delivery failed	Email rejected by recipient's server	POSTMARK_BOUNCE	AC_EMAIL
Spam Complaint	Marked as spam	Recipient reports email as spam	POSTMARK_SPAMCOMPLAINT	AC_EMAIL

Troubleshooting

Emails Not Sending

Verify POSTMARKAPP_REPLACE_MAILER constant is set to 1
Check Server API Token is valid (use "Test Connection" button)
Verify "From" email address is a verified Sender Signature in Postmark
Check Dolibarr logs (dolibarr.log) for error messages
Ensure cURL extension is enabled in PHP
Verify internet connectivity from server to Postmark API

Webhooks Not Received

Verify webhook URL is accessible from internet (test with curl or browser)
Check webhook is created in Postmark dashboard
Verify webhook triggers are enabled (Delivery, Open, Click, Bounce, Spam)
Test webhooks using built-in test buttons in configuration page
Check server logs for incoming POST requests to webhook.php
Verify webhook URL doesn't require authentication (webhook uses NOLOGIN)

Click Tracking Not Working

Click tracking requires emails to be sent in HTML format
Plain text emails cannot track clicks
Ensure MAIN_MAIL_FORCE_CONTENT_TYPE_TO_HTML is enabled
Verify "Track Clicks" option is enabled in configuration
Check that links in emails are not already rewritten by another system

Events Not Appearing in Agenda

Verify Agenda module is enabled
Check automatic triggers are enabled in Setup > Modules > Agenda > Automatic events
Verify user has permission to view ActionComm events
Check llx_postmarkapp_events table has data
Verify webhook is receiving and processing events (check logs)

MultiCompany Issues

Verify MultiCompany module is enabled
Check entity field exists in llx_postmarkapp_events table
Verify sharing configuration in Setup > Modules > MultiCompany > Options
Check SQL queries use getEntity('postmarkapp_events')
Verify entity is correctly assigned on email send

Screenshots

Changelog

Version 1.5.2 (2026-01-06)

Added MultiCompany compatibility
Added entity field to database
Implemented getEntity() in all SQL queries
Added MultiCompany sharing configuration
Added user ownership for events (fk_user field)
Enhanced object type support (supplier invoices, orders, projects, tickets, etc.)
Improved event linking (from trackid, metadata, recipient email)
Simplified event notes and labels
Removed duplicate "Sent" event (relies on Dolibarr's native system)
Added bilingual documentation
Added multi-language support (7 languages)
Added automatic trigger activation
Enhanced webhook processing with entity inheritance
Added comprehensive event filters
Added reference search for linked objects

Version 1.5.0 (2026-01-06)

Initial release
Postmark API integration
Webhook handling
Event tracking
Agenda integration
Object linking

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
MultiCompany configuration and data migration
Custom development and feature requests
Training for your team

Contact us for a personalized quote: https://lysis.net

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 configuration MultiCompany et la migration de données
Le développement sur mesure et les demandes de fonctionnalités
La formation de vos équipes

Contactez-nous pour un devis personnalisé : https://lysis.net

Author

Alex BORDARAUD
Website: https://lysis.net

Module PostmarkApp

Informations

Description

English

Français

Features

Core Features

Requirements

System Requirements

Postmark Requirements

Installation

Step-by-Step Installation

Post-Installation

Configuration

Step 1: Server API Token

Step 2: Options

Step 3: Webhook Configuration (Optional but Recommended)

Step 4: Testing

MultiCompany Compatibility

How It Works

Configuration

Sharing Behavior

Entity Assignment

Technical Architecture

Module Structure

Hooks System

API Integration

Database Schema

Supported Object Types

Automatic Triggers

Permissions

Webhook Processing

SQL Queries and MultiCompany

How It Works

Email Sending Flow

Webhook Event Flow

Event Linking

Event Types

Troubleshooting

Emails Not Sending

Webhooks Not Received

Click Tracking Not Working

Events Not Appearing in Agenda

MultiCompany Issues

Screenshots

Changelog

Version 1.5.2 (2026-01-06)

Version 1.5.0 (2026-01-06)

Links

License

Professional Services / Services professionnels

English

Français

Author

Navigation menu

Search