Sending invoices manually in Dolibarr ERP/CRM is functional but time-consuming, especially when dealing with large volumes or recurring billing. Automating this process through scheduled cron jobs can save significant time and eliminate human error. This guide provides a complete walkthrough for setting up automatic invoice email delivery in Dolibarr using cron, without relying on paid plugins or external automation tools.

Table of Contents

  1. Introduction to Invoice Automation in Dolibarr

  2. Benefits of Automating Invoice Emailing

  3. Understanding Dolibarr’s Architecture and Email System

  4. Requirements for Cron-Based Automation

  5. Overview of the Dolibarr CLI and REST API

  6. Preparing Your Dolibarr Environment

  7. Creating Invoices Programmatically

  8. Marking Invoices as Validated

  9. Generating PDF Documents via Command Line or Script

  10. Automatically Sending Invoices by Email

  11. Writing a Custom Script to Handle the Workflow

  12. Setting Up a Cron Job for Scheduled Execution

  13. Logging, Error Handling, and Alerts

  14. Securing Your Automation Setup

  15. Final Thoughts and Best Practices

1. Introduction to Invoice Automation in Dolibarr

Dolibarr provides robust tools for invoice generation, validation, and email delivery. However, out-of-the-box functionality requires manual actions. For businesses that generate dozens or hundreds of invoices daily or monthly, automating these steps is not just convenient—it’s essential for operational efficiency.

This guide focuses on automating the full cycle: from identifying invoices ready to send, generating the corresponding PDF documents, and emailing them to clients—triggered via a scheduled cron job.

2. Benefits of Automating Invoice Emailing

Automating invoice email delivery offers several key advantages:

  • Saves time and manual labor

  • Reduces the risk of missed invoices

  • Enhances consistency and professionalism

  • Ensures timely delivery, especially for subscription-based businesses

  • Minimizes human error in the invoicing workflow

When combined with logs and notifications, it also gives you traceability for every invoice sent.

3. Understanding Dolibarr’s Architecture and Email System

Dolibarr’s emailing system works through either:

  • The built-in PHP mail() function (not recommended for production)

  • SMTP configuration (highly recommended for authentication and deliverability)

Invoices in Dolibarr follow this life cycle:

  1. Draft (not yet valid)

  2. Validated

  3. Paid / Unpaid status

Emails can only be sent for validated invoices. PDF generation is tied to invoice templates located in /htdocs/core/modules/facture/doc/.

4. Requirements for Cron-Based Automation

To automate invoice emailing:

  • A server with command line access (Linux preferred)

  • A working Dolibarr installation with CLI/API access

  • SMTP properly configured in Dolibarr

  • Basic knowledge of bash scripting or PHP/Python

  • Access to the filesystem (for PDFs)

Ensure your Dolibarr version is up to date (v12 or newer recommended).

5. Overview of the Dolibarr CLI and REST API

Dolibarr does not officially offer CLI tools out-of-the-box, but you can interface with it using:

  • REST API (recommended for modularity and remote access)

  • Direct PHP script calls within the Dolibarr framework

The REST API allows interaction with invoices, third-parties, and documents.

Example GET request to fetch invoices:

curl -X GET "https://yourdomain.com/api/index.php/invoices?DOLAPIKEY=yourapikey"

6. Preparing Your Dolibarr Environment

Steps to prepare:

  1. Enable the API module under Setup > Modules > Web Services/API

  2. Generate an API key for a user with access to invoices and third-parties

  3. Set up SMTP under Setup > Email > Email Setup

  4. Test PDF generation and email delivery manually

Confirm you can:

  • Generate a PDF invoice

  • Send an email with a PDF attachment

7. Creating Invoices Programmatically

To automate, you need to generate new invoices or identify existing ones ready for sending.

Create via API:

POST https://yourdomain.com/api/index.php/invoices
{
  "socid": 12,
  "lines": [
    {"desc": "Service Plan A", "subprice": 100, "qty": 1}
  ],
  "date": "2025-05-01",
  "cond_reglement_id": 1,
  "mode_reglement_id": 2
}

After creation, the invoice is in draft mode.

8. Marking Invoices as Validated

To send an invoice, it must be validated. Use this endpoint:

POST /api/index.php/invoices/{id}/validate

This triggers internal state change and prepares the invoice for email.

You may also need to generate the PDF if it hasn’t been created yet.

9. Generating PDF Documents via Command Line or Script

Invoices are usually generated as PDFs using templates like crabe or azur.

To automate PDF creation:

  1. Use the API: POST /api/index.php/invoices/{id}/builddoc?model=azur

  2. Or execute a custom PHP script in Dolibarr root:

require 'main.inc.php';
require_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php';

$invoice = new Facture($db);
$invoice->fetch($invoice_id);
$invoice->generateDocument('azur', $langs);

10. Automatically Sending Invoices by Email

Sending invoices via API:

POST /api/index.php/invoices/{id}/sendbymail

With JSON payload:

{
  "email_from": "billing@company.com",
  "email_to": "client@example.com",
  "subject": "Your Invoice",
  "message": "Please find attached your invoice.",
  "trackid": "INV-202505"
}

Make sure:

  • The invoice has a valid email address linked to the third-party

  • The invoice is validated and has a PDF generated

11. Writing a Custom Script to Handle the Workflow

Use PHP, Python, or bash. Here's a simplified pseudo-logic in Python:

for invoice in fetch_draft_invoices():
    validate_invoice(invoice['id'])
    generate_pdf(invoice['id'])
    send_email(invoice['id'], invoice['email'])

Ensure each step checks the previous result before proceeding. Log outcomes.

12. Setting Up a Cron Job for Scheduled Execution

On Linux, edit the crontab:

crontab -e

Add:

0 8 * * * /usr/bin/python3 /path/to/send_invoices.py >> /var/log/dolibarr_invoice.log 2>&1

This runs the script daily at 8 AM and logs output.

13. Logging, Error Handling, and Alerts

Your script should:

  • Write logs per run

  • Handle errors gracefully (e.g., unreachable API, bad email)

  • Send alerts if mass failure is detected

Use Python’s logging module or logrotate on Linux to manage log files.

14. Securing Your Automation Setup

Best practices:

  • Use .env or encrypted config files for API keys

  • Set permissions on scripts and logs

  • Use HTTPS for all API interactions

  • Monitor cron logs for unauthorized edits

Consider running automation scripts under a dedicated low-privilege user.

15. Final Thoughts and Best Practices

Automating the email delivery of invoices in Dolibarr saves time, enhances accuracy, and improves the client experience. With a combination of the REST API, proper scripting, and scheduled cron jobs, businesses can eliminate a tedious administrative task.

Best practices summary:

  • Always validate invoices before emailing

  • Ensure SMTP is correctly configured

  • Maintain clear logs and error reporting

  • Start with manual tests before automating

  • Secure your environment thoroughly