Ce document en français.
The use of this software subjects you to our Terms Of Use and Data Protection Policy.
eMailerOOo is part of a Suite of LibreOffice and/or OpenOffice extensions allowing to offer you innovative services in these office suites.
This extension allows you to send documents in LibreOffice as an email, possibly by mail merge, to your telephone contacts.
It also provides an API allowing you to send emails in BASIC and supporting the most advanced technologies: OAuth2 protocol, Mozilla IspDB, HTTP instead of SMTP/IMAP for Google servers…
A macro SendEmail for sending emails is provided as an example. If you open a document beforehand, you can launch it by:
Tools -> Macros -> Run Macro… -> My Macros -> eMailerOOo -> SendEmail -> Main -> Run
Being free software I encourage you:
In short, to participate in the development of this extension.
Because it is together that we can make Free Software smarter.
The eMailerOOo extension uses the OAuth2OOo extension to work.
It must therefore meet the requirement of the OAuth2OOo extension.
The eMailerOOo extension uses the jdbcDriverOOo extension to work.
It must therefore meet the requirement of the jdbcDriverOOo extension.
On Linux and macOS the Python packages used by the extension, if already installed, may come from the system and therefore may not be up to date.
To ensure that your Python packages are up to date it is recommended to use the System Info option in the extension Options accessible by:
Tools -> Options -> Internet -> eMailerOOo -> View log -> System Info
If outdated packages appear, you can update them with the command:
pip install --upgrade <package-name>
For more information see: What has been done for version 1.2.0.
It seems important that the file was not renamed when it was downloaded.
If necessary, rename it before installing it.
Install OAuth2OOo.oxt extension
You must first install this extension, if it is not already installed.
Install jdbcDriverOOo.oxt extension
This extension is necessary to use HsqlDB version 2.7.2 with all its features.
If you don’t have a datasource, you can:
Install vCardOOo.oxt extension
This extension is only necessary if you want to use your contacts present on a Nextcloud platform as a data source for mailing lists and document merging.
Install gContactOOo.oxt extension
This extension is only needed if you want to use your personal phone contacts (Android contact) as a data source for mailing lists and document merging.
Install mContactOOo.oxt extension
This extension is only needed if you want to use your Microsoft Outlook contacts as a data source for mailing lists and document merging.
Install HyperSQLOOo.oxt extension
This extension is only necessary if you want to use a Calc file as a data source for mailing lists and document merging. See: How to import data from a Calc file.
Install eMailerOOo.oxt extension
Restart LibreOffice after installation.
Be careful, restarting LibreOffice may not be enough.
soffice
and using the key combination Ctrl + C
if after stopping LibreOffice, the terminal is not active (no command prompt).To be able to use the email merge feature using mailing lists, it is necessary to have a datasource with tables having the following columns:
In addition, this datasource must have at least one main table, including all the records that can be used during the email merge.
If you do not have such a datasource then I invite you to install one of the following extensions:
For the first 3 extensions the name of the main table can be found (and even changed before any connection) in:
Tools -> Options -> Internet -> Extension name -> Main table name
This mode of use is made up of 3 sections:
To be able to post emails to a mailing list, you must:
This Writer document can include merge fields (insertable by the command: Insert -> Field -> More fields -> Database -> Mail merge fields), this is even necessary if you want to be able to customize the content of the email and any attached files.
These merge fields should only refer to the main table of the datasource.
If you want to use an existing Writer document, you must also ensure that the datasource and the main table are attached to the document in: Tools -> Address Book Source.
If these recommendations are not followed then merging of documents will not work and this silently.
In LibreOffice Writer document go to: Tools -> Add-Ons -> Sending emails -> Merge a document
The datasource load for the Email merging wizard should appear:
The following screenshots use the gContactOOo extension as the datasource. If you are using your own datasource, it is necessary to adapt the settings in relation to it.
In the following screenshot, we can see that the datasource gContactOOo is called: Addresses
and that in the list of tables the table: PUBLIC.All my contacts
is selected.
If no mailing list exists, you need to create one, by entering its name and validating with: ENTER
or the Add
button.
Make sure when creating the mailing list that the main table is always selected in the list of tables.
If this recommendation is not followed then merging of documents will not work and this silently.
Now that your new mailing list is available in the list, you need to select it.
And add the following columns:
Uri
HomeEmail
, WorkEmail
and OtherEmail
If several columns of email addresses are selected, then the order becomes relevant since the email will be sent to the first available address.
In addition, on Recipients selection step of the wizard, in the Available recipients tab, only records with at least one email address column entered will be listed.
So make sure you have an address book with at least one of the email address field (Home, Work or Other) entered.
This setting is to be made only for new mailing lists.
You can now proceed to the next step.
The recipients are selected using 2 buttons Add all
and Add
allowing respectively:
Address book
list. This allows during a mailing, that the modifications of the contents of the group are taken into account. A mailing list only accepts one group.CTRL
key. This selection is immutable regardless of the modification of the address book groups.Example of multiple selection:
The recipients are deselected using 2 buttons Remove all
and Remove
allowing respectively:
CTRL
key.If you have selected at least 1 recipient, you can proceed to the next step.
If this is not already done, you must create a new sender using the Add
button.
The creation of the new sender is described in the Configure connection section.
The email must have a subject. It can be saved in the Writer document.
You can insert merge fields in the email subject. A merge field is composed of an opening brace, the name of the referenced column (case sensitive) and a closing brace (ie: {ColumnName}
).
The email may optionally have attached files. They can be saved in the Writer document.
The following screenshot shows 1 attached file which will be merged on the data source then converted to PDF format before being attached to the email.
Make sure to always exit the wizard with the Finish
button to confirm submitting the send jobs.
To submit mailing jobs, please follow the section Outgoing emails.
In LibreOffice go to: Tools -> Add-Ons -> Sending emails -> Configure connection
Always exit the wizard with the Finish
button to save the connection settings.
In LibreOffice go to: Tools -> Add-Ons -> Sending emails -> Outgoing emails
Each send job has 3 different states:
The email spooler is stopped by default. It must be started with the Start / Stop
button so that the pending emails are sent.
When the email spooler is started, its activity can be viewed in the activity log.
It is possible to send emails using macros written in Basic. Sending an email requires a macro of some 50 lines of code and will support most SMTP/IMAP servers.
Here is the minimum code needed to send an email with attachments.
Sub Main
Rem Ask the user for a sender's email address.
sSender = InputBox("Please enter the sender's email address")
Rem User clicked Cancel.
if sSender = "" then
exit sub
endif
Rem Ask the user for recipient's email address.
sRecipient = InputBox("Please enter the recipient's email address")
Rem User clicked Cancel.
if sRecipient = "" then
exit sub
endif
Rem Ask the user for email's subject.
sSubject = InputBox("Please enter the email's subject")
Rem User clicked Cancel.
if sSubject = "" then
exit sub
endif
Rem Ask the user for email's content.
sBody = InputBox("Please enter the email's content")
Rem User clicked Cancel.
if sBody = "" then
exit sub
endif
Rem Ok now we have everything, we start sending an email.
Rem We will use 4 UNO services which are:
Rem - com.sun.star.mail.MailUser: This is the service which will ensure the correct configuration
Rem of SMTP and IMAP servers (we can thank Mozilla for the ISPBD database that I use).
Rem - com.sun.star.mail.MailServiceProvider: This is the service that allows you to use SMTP and
Rem IMAP servers. We will use this service with the help of the previous service.
Rem - com.sun.star.datatransfer.TransferableFactory: This service is a forge for the creation of
Rem Transferable which are the basis of the body of the email as well as these attached files.
Rem - com.sun.star.mail.MailMessage: This is the service that implements the email message.
Rem Now that everything is clear we can begin.
Rem First we create the email.
Rem This is our Transferable forge, it greatly simplifies the LibreOffice mail API...
oTransferable = createUnoService("com.sun.star.datatransfer.TransferableFactory")
Rem oBody is the body of the email. It is created here from a String but could also
Rem have been created from an InputStream, a file Url (file://...) or a sequence of bytes.
oBody = oTransferable.getByString(sBody)
Rem oMail is the email message. It is created from the com.sun.star.mail.MailMessage service.
Rem It can be created with an attachment with the createWithAttachment() method.
oMail = com.sun.star.mail.MailMessage.create(sRecipient, sSender, sSubject, oBody)
Rem Ask the user for the URLs of the attached files.
oDialog = createUnoService("com.sun.star.ui.dialogs.FilePicker")
oDialog.setMultiSelectionMode(true)
if oDialog.execute() = com.sun.star.ui.dialogs.ExecutableDialogResults.OK then
oFiles() = oDialog.getSelectedFiles()
Rem These two services are simply used to get a suitable file name.
oUrlTransformer = createUnoService("com.sun.star.util.URLTransformer")
oUriFactory = createUnoService("com.sun.star.uri.UriReferenceFactory")
for i = lbound(oFiles()) To ubound(oFiles())
oUri = getUri(oUrlTransformer, oUriFactory, oFiles(i))
oAttachment = createUnoStruct("com.sun.star.mail.MailAttachment")
Rem ReadableName must be entered. This is the name of the attached file
Rem as it appears in the email. Here we get the file name.
oAttachment.ReadableName = oUri.getPathSegment(oUri.getPathSegmentCount() - 1)
Rem The attachment is retrieved from an Url but same as for oBody
Rem it can be retrieved from a String, an InputStream or a sequence of bytes.
oAttachment.Data = oTransferable.getByUrl(oUri.getUriReference())
oMail.addAttachment(oAttachment)
next i
endif
Rem End of creating the email.
Rem Now we need to send the email.
Rem First we create a MailUser from the sender address. This is not necessary the
Rem sender address but it must follow the rfc822 (ie: my surname <myname@myisp.com>).
Rem The IspDB Wizard will automatically be launched if this user has never been configured.
oUser = com.sun.star.mail.MailUser.create(sSender)
Rem User canceled IspDB Wizard.
if isNull(oUser) then
exit sub
endif
Rem Now that we have the user we can check if they want to use a Reply-To address.
if oUser.useReplyTo() then
oMail.ReplyToAddress = oUser.getReplyToAddress()
endif
Rem In the same way I can test if the user has an IMAP configuration with oUser.supportIMAP()
Rem and then create an email thread if necessary. In this case you must:
Rem - Construct an email message thread (as done previously for oMail).
Rem - Create and connect to an IMAP server (as we will do for SMTP).
Rem - Upload this email to the IMAP server with: oServer.uploadMessage(oServer.getSentFolder(), oMail).
Rem - Once it has been uploaded, retrieve the MessageId with the oMail.MessageId property.
Rem - Set the oMail.ThreadId property to MessageId for all subsequent emails.
Rem Great you have successfully grouped the sending of emails into a thread.
Rem To send the email we need to create an SMTP server. Here's how to do it:
SMTP = com.sun.star.mail.MailServiceType.SMTP
oServer = createUnoService("com.sun.star.mail.MailServiceProvider").create(SMTP)
Rem Now we connect using the SMTP user's configuration.
oServer.connect(oUser.getConnectionContext(SMTP), oUser.getAuthenticator(SMTP))
Rem Well, that's it, we are connected, all we have to do is send the email.
oServer.sendMailMessage(oMail)
Rem Don't forget to close the connection.
oServer.disconnect()
MsgBox "The email has been sent successfully." & chr(13) & "Its MessageId is: " & oMail.MessageId
Rem Et voilà, you have it...
End Sub
Function getUri(oUrlTransformer As Variant, oUriFactory As Variant, sUrl As String) As Variant
oUrl = createUnoStruct("com.sun.star.util.URL")
oUrl.Complete = sUrl
oUrlTransformer.parseStrict(oUrl)
oUri = oUriFactory.parse(oUrlTransformer.getPresentation(oUrl, false))
getUri = oUri
End Function
And there you have it, it only took a few lines of code so enjoy…
However, this is only an example of popularization, and all the necessary error checks are not in place…
LibreOffice 7.3.7.2 - Lubuntu 22.04 - Python version 3.10.12 - OpenJDK-11-JRE (amd64)
LibreOffice 7.5.4.2(x86) - Windows 10 - Python version 3.8.16 - Adoptium JDK Hotspot 11.0.19 (under Lubuntu 22.04 / VirtualBox 6.1.38)
LibreOffice 7.4.3.2(x64) - Windows 10(x64) - Python version 3.8.15 - Adoptium JDK Hotspot 11.0.17 (x64) (under Lubuntu 22.04 / VirtualBox 6.1.38)
LibreOffice 24.2.1.2 - Lubuntu 22.04
LibreOffice 24.8.0.3 (x86_64) - Windows 10(x64) - Python version 3.9.19 (under Lubuntu 22.04 / VirtualBox 6.1.38)
Does not work with OpenOffice see bug 128569. Having no solution, I encourage you to install LibreOffice.
I encourage you in case of problem
to create an issue
I will try to solve it
com.sun.star.mail.MailServiceProvider
when connecting to the SMTP server and sending an email.com.sun.star.mail.SpoolerService
when sending emails.com.sun.star.sdb.RowSet
allowing:
Rewriting of the Spooler in order to integrate IMAP functionality such as the creation of a thread summarizing the mailing and grouping all the emails sent.
VARCHAR
and INTEGER
or derived.The absence or obsolescence of the OAuth2OOo and/or jdbcDriverOOo extensions necessary for the proper functioning of eMailerOOo now displays an error message. This is to prevent a malfunction such as issue #3 from recurring…
The underlying HsqlDB database can be opened in Base with: Tools -> Options -> Internet -> eMailerOOo -> Database.
The Tools -> Add-Ons menu now displays correctly based on context.
Many other things…
In the connection configuration wizard (IspDB Wizard) it is now possible to deactivate the IMAP configuration.
As a result, this no longer sends a thread (IMAP message) when merging a mailing.
In this same wizard, it is now possible to enter an email reply-to address.
In the email merge wizard, it is now possible to insert merge fields in the subject of the email. See issue #6.
In the subject of an email, a merge field is composed of an opening brace, the name of the referenced column (case sensitive) and a closing brace (ie: {ColumnName}
).
When entering the email subject, a syntax error in a merge field will be reported and will prevent the mailing from being submitted.
It is now possible in the Spooler to view emails in eml format.
A service com.sun.star.mail.MailUser now allows access to a connection configuration (SMTP and/or IMAP) from an email address following rfc822.
Another service com.sun.star.datatransfer.TransferableFactory allows, as its name suggests, the creation of Transferable from a String, a binary sequence, an Url (file://…) or a data stream (InputStream).
These two new services greatly simplify the LibreOffice mail API and allow sending emails from Basic. See Issue #4.
You will find a Basic macro allowing you to send emails in: Tools -> Macros -> Edit Macros… -> eMailerOOo -> SendEmail.
pip install requirements.txt
This should allow implementing a third-party API for sending emails just by modifying the Options.xcu configuration file.
Add new languages for internationalization…
Anything welcome…