cogAdministration UI for mail configuration and statuses
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

Installable with the Extension Manager


Prior to XWiki 6.4, the Mail configuration was part of the Administration Application.

Allows configuring Mail. For example, the Mail Sender API uses this configuration when sending mail.

To use, go the global Administration page of your wiki and click on the Email categories:


Mail Obfuscation


If turned on, the mails are displayed obfuscated, for example in the User's profile page:


Mail Sending

Mail sending parameters:


The Additional Properties fields allow passing JavaMail configuration properties. Here are some common ones:

mail.smtp.localhostLocal host name used in the SMTP HELO or EHLO command. Defaults to InetAddress.getLocalHost().getHostName(). Should not normally need to be set if your JDK and your name service are configured
mail.smtp.authIf true, attempt to authenticate the user using the AUTH command. Defaults to false. If you specify a username and a password, XWiki will set this property automatically for youmail.smtp.auth=true
mail.smtp.starttls.enableIf true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must be configured so that the client trusts the server's certificate. Defaults to false. mail.smtp.starttls.enable=true

Note that these configuration options can also have default values configured in XWiki's configuration file.

Using Google SMTP server

For testing purposes, you can use your own GMail account as a SMTP server:

username[email protected]
JavaMail propertiesmail.smtp.starttls.enable=true

In case your Google account has 2-step verification activated, you might receive and error while trying to send a mail.

In the logs, the error should look like this:

ERROR c.x.x.p.m.MailSenderPlugin     - sendEmailFromTemplate: XWiki.SharePage vcontext: org.apache.velocity.VelocityContext@26e308eb
javax.mail.AuthenticationFailedException: 534-5.7.9 Application-specific password required. Learn more at
534 5.7.9 r7sm3779883wjw.23 - gsmtp

To fix it, follow the instructions at the link mentioned in the error log to create an application password that you should use in the configuration instead of your account's real password.

Never use Gmail in production, in place of a real SMTP server, since this could get your account blocked, and your personal email appears as the sender in Outlook and other email clients.

Mail Sending Status

Display the statuses of all mails sent (when the feature that sent the email has defined that the mail status should be persisted) and allow resending emails that have failed to be sent.


Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki


Dependencies for this extension (org.xwiki.platform:xwiki-platform-mail-ui 12.8):

Tags: mail
Created by Vincent Massol on 2020/05/11 15:48

Get Connected