XWiki Mail Features

XWiki Standard allows administrators to handle mail configuration and statuses via the "Mail Application" that uses the new "Mail Sender API". The application is available in the wiki preferences page by clicking the DrawerMenuIcon.png button in order to open the drawer menu, then on "Administer Wiki".


In the "Mail" section of the accordion menu you will see 3 dedicated sections:

  • "Mail Sending" - exposes a list of parameters for configuring a SMTP server as well as some additional JavaMail properties
  • "Mail Sending Status" - displays the list of sent emails with the option of resending 
  • "Advanced" - allows to enable or disable the email address obfuscation


Obfuscate the Email Addresses

The "Obfuscate Email Addresses" option allows to enable or disable the obfuscation of the email addresses that are stored in object properties of type Email. By default, email addresses obfuscation is disabled but it can be easily activated by clicking on "Advanced" in the accordion menu from the wiki preferences page.


Next, choose "Yes" in the drop-down menu, then click on "Save". This way, only the first letter of the email account will be displayed whereas the rest of the letters will be replaced by an ellipsis. 


Configure a SMTP Server from the Wiki UI

If you are using the "Notifications" and "Share page by email" features, you will need to configure a SMTP server and specify the default email address that XWiki will use. The easiest way is via the wiki administration by clicking on "Mail Sending" in the accordion menu to the left.


The SMTP server should be like mail.yourdomain.com (it defaults to localhost) .You might need to specify some additional JavaMail properties. The most common are:

  • mail.smtp.starttls.enable: if set to true, this parameter 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.
  • mail.smtp.auth: if set to true, the server will authenticate the user using the AUTH command.
  • mail.smtp.localhost: this is the local host name used in the SMTP HELO or EHLO command. The default value is InetAddress.getLocalHost().getHostName().

For the complete list of parameters, please consult the JavaMail API. Also, the Mail Sender API documentation is listed in the "Related Pages" section, under "Developer Guide".

If you are using the Google SMTP server, the fields in the "Email" section should be filled like in the below example:

  • Server: smtp.gmail.com
  • Port: 587
  • User: martin.charles@gmail.com
  • Additional JavaMail properties: mail.smtp.starttls.enable=true

Starting with version 6.4, you may configure default BCC addresses which will be added to all emails sent using the Mail Sender API. You can also specify the delay to wait between each mail being sent. This was done in order to support mail throttling and not be considered a spammer by mail servers. The default value is 8 seconds but in case you wish to change it you have 2 possibilities:

  • Straight from the UI
  • Edit the "WEB-INF/xwiki.properties" file and set the mail.sender.sendWaitTime parameter with a value of your choice, in milliseconds. Note that this modification requires a server restart.


By default, the status for messages that have been sent successfully is stored by the Mail Application but you can deactivate this feature by checking the option "Discard Success Statuses?".

Check the Mail Sending Status

The Mail Application also allows to check the status of sent emails, provided the feature that sent the email has defined that the mail status should be persisted, in which case it is possible to resend the ones that have failed to be sent. In the newest XWiki Standard versions, mails that weren't sent yet are now resent automatically at startup, thanks to the Mail Sender Storage API.


When using the Database Mail Listener, in case a mail fails to be sent, both the error summary and the full error description are saved. For more details, check the Mail Sender API documentation.

Configure a SMTP Server from Tomcat on Localhost

The first step is to add a global resource to the "Tomcat_Home/conf/server.xml" file as shown below:

<Resource name="mail/Session"

For the "mail.smtp.host" parameter you should choose "localhost" and for "mail.smtp.port" you should keep the default value which is "25". According to the source code, if port is not specified, it takes the value of the "mail.smtp.port" property if it exists, otherwise it defaults to 25.

For the "mail.smtp.user" and "password" properties, make sure they are the ones you entered when you configured the SMTP server.

Next, you must add a resource link to the "Tomcat_Home/conf/context.xml" file as follows:

<ResourceLink name="mail/Session"
              type="javax.mail.Session" />

You also have to configure Tomcat's resource factory by adding the below element:

<Resource name="mail/Session"

The values of the "auth", "type" and "mail.smtp.host" properties must be the same as the ones you entered in "Tomcat_Home/conf/server.xml".

The final step is to configure XWiki by adding a resource reference to a factory for "javax.mail.Session" instances configured to connect to the appropriate SMTP server. To do so, edit the "webapps/xwiki/WEB-INF/web.xml" file and add the below lines:


The "res-ref-name","res-type" and "res-auth" elements should have the same values as the "name", "type" and "auth" properties from "server.xml" and "context.xml".

To test the SMTP server, restart Tomcat, edit any wiki page and copy/paste the Test Mail code snippet.

Windows Systems that don't provide a SMTP Server

Windows systems designed for home use, like Windows 7 or Windows 8 don't include a SMTP server. Instead, you can download:

  • hMailServer - an open source e-mail server for Microsoft Windows that supports IMAP, SMTP and POP3. To learn how to relay outbound email from legacy network devices using Google Mail or Google Apps mail servers, check the below sections.

Configure hMailServer for Google Mail

Start by downloading "hMailServer", then perform a standard install. Next, connect to the server using the administrator password you chose during the installation:


In the left panel, click on "Settings" -> "Protocols" -> "SMTP".


Next, click on the "Delivery of e-mail" tab, locate the "SMTP Relayer" section and:

  • for "Remote host name" enter "smtp.gmail.com"
  • for "Remote TCP/IP port" enter "465"
  • check "Server requires authentication" and enter your Gmail user name and password
  • check "Use SSL"
  • click on "Save"


Go again to the left panel and click on "Settings" -> "Advanced" -> "IP Ranges".


On "localhost", click on "Add" and fill in the required fields just like in the below image.


You should also make sure the following options are disabled:

  • in the "Others" section:
    • Anti-Spam
    • Anti-Virus
  • in the "Require SMTP Authentication" section:
    • Local to local e-mail addresses
    • Local to external e-mail addresses
    • External to local e-mail addresses
    • External to external e-mail addresses

For more configuration details, check the hMailServer documentation.

Install the JavaMail Libraries

The XWiki Mail Sender API uses JavaMail that you can download from this link. You might also need the "JavaBeans Activation Framework" that can be downloaded from this link

The 2 files, "mail-1.4.1.jar" and "activation-1.1.1.jar" should be copied under "Tomcat_Home/lib".


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space