Module EMailing
| Mailing | |
|---|---|
| Numero/ID of module | 22 |
| User doc. of module | This page |
| Developer doc. of module | Module EMailing (developer) |
Introduction
This module permits to send mass emailing to your customers, suppliers, prospects, contacts, members, or users.
Installation
This module is included with the Dolibarr distribution, so there is no need to install it.
Setup
To use this module, you must first enable it using an administrator account, via the menu option "Home - Setup - Modules".
Choose the tab where the module is listed. Then click on "Activate".
The module is now activated.
If a cog icon appears 
on module thumb or at end of the line of the module, click on it to access the setup page specific to the module.
Check also that Dolibarr setup to send mails is ok: Setup EMails
Check also the setup options available in Setup Other, for the emailing module. Amongst others, you can set the number of emails to be sent from your web interface with MAILING_LIMIT_SENDBYWEB.
Note: If a constant MAILING_NO_USING_PHPMAIL is set to 1 in Home - Setup - Other, it is only possible to send emailing when the send mode in setup is not on "PHP Mail" but on another mode (like "SMTPs").
Usage
Mass E-Mailing features are available from menus (if Module EMailing has been activated). Menu link can be found in menu "Tools" with default menu manager "Eldy".
Life cycle / Business rules
The full process is this one:
- You create an emailing with a title, a topic and an email sender (For this, click on menu "Tools - EMailings - New emailing", input the content of the email with substitue variables and click on "Create emailing" button. The other solution is to go on an existing emailing and click "Clone").
- Then you choose the targets, among predefined dynamic lists from your Dolibarr data or from external files (For this, go on tab "Recipients" and click on button "Add" of the predefined lists you want).
- You can modify this list, by removing targets for example, orcadding targets from dufferent sources.
- The user responsible to validate emailing checks content and recipients. He can do a test to its own e-mail address to see the result inside its email software. If results looks good, he set the status of e-mailing to validated (For this, click on button "Validate").
- The mass e-mail sending is done then from:
- the web application screen. In such a case, there is a limit in number of emails sent in one step, 50 by defaut in most cases. If you have more than 50 recipients, you can submit the emailing from screen a second time and the application will automatically send emails to the 50 next recipients. Repeat until all recipients are addressed.
- or from the command line with script Script mailing-send.php.
Only an emailing with the status Validated can be sent by the script. See page Script mailing-send.php for more information on how to launch it from command line.
- The global status for e-mailing and send result for each recipient will be updated and visible.
Personalising the email: __OTHER1__ to __OTHER5__
Besides __EMAIL__, __LASTNAME__ and __FIRSTNAME__, you can use __OTHER1__ to __OTHER5__ in the topic and the body of the emailing.
Their content comes from the column "Other information" of tab "Recipients" (format Key1=value1;Key2=value2;...): __OTHER1__ is the 1st value, __OTHER2__ the 2nd, and so on. The key before "=" is not used.
| Recipients list | __OTHER1__ | __OTHER2__ | __OTHER3__ | __OTHER4__ |
|---|---|---|---|---|
| Contacts of thirdparties | Third party name | Civility (label, e.g. "Mr.") | Job position | |
| Foundation members | Login | Civility (label, e.g. "Mr.") | End date of membership | Company |
| Users with Emails | Login | Civility (code, e.g. "MR") | Professional phone |
Example: Dear __OTHER2__ __LASTNAME__, gives Dear Mr. Legrand, for a contact.
Emails from file: each line is email;name;firstname;other, and everything after the 3rd ";" is kept. The line john@example.com;Doe;John;Mr.;VIP gives __OTHER1__ = Mr. and __OTHER2__ = VIP.
Emails input by user: same format, but only the 4th field is kept (__OTHER1__ only).
For the other lists (Third parties, etc.), the content depends on the list and on the filters chosen: check the column "Other information" before using these variables.
The values are saved when the recipients are added, in the language of the user who adds them. If you change a contact afterwards, remove the recipient and add it again.
Checked in Dolibarr v14 to v24.
Layout: email templates
Since Dolibarr v20, when you create an emailing, the link "Fill message with a layout" (icon above the message) offers ready-made layouts. Choosing a layout replaces the message with the layout content, which you can then edit freely. There is no screen to create or edit layouts.
- v20: fixed list (Empty, Basic, News, Commerce), defined in the code.
- From v21: each layout is an HTML file in the directory htdocs/install/doctemplates/maillayout/. The list shows "Empty" ("None" from v23) and then one layout per file. From v22, News is only shown if the Websites module is enabled, and Products (Product from v23) only if the Products or Services module is enabled.
Adding your own layout (v21 and later):
- Copy basic.html under another name in the same directory, for example association.html, and edit the copy. The layout appears in the list under the file name ("Association").
- For the thumbnail, add an image with the same name (association.png) in htdocs/theme/common/maillayout/.
Emailing variables (__LASTNAME__, __OTHER1__…) can be written in the file: they stay as they are in the message and are replaced when sending. Do not edit basic.html itself (it is replaced at each upgrade), and keep a copy of your files: they are in the application directory, not in the documents directory.
Without touching files: prepare an emailing with the layout you want, then for each new sending, open it and click "Clone" with "Clone message" checked.
Tested in v20, v21, v22 and v24 (same code in v23).