Outbound E-mail Configuration

Introduction

Alfresco supports the ability to generate and send email to en external SMTP server. For example when a new user is invited to a site an email is sent.

The email service is exposed as a spring bean called mailService which is contained within the OutboundSMTP subsystem.

This document will highlight the basic components that make this possible, give details of the types of behaviour that can be expected. This document assumes knowledge of how to extend the repository configuration.

The Alfresco repository repository can be configured to send e-mails to an external SMTP server by overriding the details found in the alfresco configuration file.

3.2+

• <extension root>/alfresco-global.properties

or for older versions of Alfresco

• <configRoot>/custom-repository.properties.

The default SMTP configuration should look like this:

SMTP configuration

The remote SMTP server is configured through a set of properties.

Assuming that the configuration is being overridden as described in Repository Configuration, then the correct mail configuration can be placed in your alfresco-global.properties or custom-repository.properties file. You only need to give the values that differ from the main configuration file; for example, the port number will probably stay the same, so does not need to be specified in your custom configuration file.

mail.host=<the name of your SMTP host>
mail.port=<the port that your SMTP service runs on (the default is 25)>
mail.username=<the username of the account you want e-mail to be sent from>
mail.password=<the password>

The following property values are the default values that you can change.

mail.from.default=alfresco@alfresco.org

This is used for the "from" field by the MailActionExecutor if the current user does not have an email address.

mail.from.enabled

(New in 4.0.1) If false then mail.from.default will always be used. If true then the FROM field may be changed. This may be required in the security settings of your email server insist on the FROM field matching the authentication details.

mail.host 

the hostname of your smtp server, that is the hostname or IP address of the server to which email should be sent.

mail.port=25 

the port number of your smtp server, by convention TCP port 25 is reserved for SMTP although your email adminstrator may change it.

mail.protocol=smtp 

how to send the email, either smtp or smtps

mail.username

the user name to connect to the smtp server

mail.password 

the password to connect to the smtp server

mail.encoding=UTF-8

Set this value to UTF-8 or similar for encoding of email messages as required

mail.header=

For SMTP

mail.smtp.auth=false

is authentication required or not.

mail.smtp.timeout=30000

mail.smtp.starttls.enable=false

mail.smtp.debug=false

For SMTPS

mail.smtps.starttls.enable

mail.smtps.auth=false

Test Message

When the Outbound SMTP subsystem is initialized it can attempt to send an email to determine whether the server is available or not.

mail.testmessage.send=false

mail.testmessage.to=

mail.testmessage.subject=Outbound SMTP

mail.testmessage.text=The Outbound SMTP email subsystem is working.

Custom Configuration Example for 4.0

The mailService implementation is provided by Spring and the configuration can be customised by setting various key value pairs in javaMailProperties.

Alfresco provides configuration for the most common scenarios, however if you need a greater level of control then you can over-ride the out of the box configuration. Typically you may want to add or remove properties.

All the configuration you may need can be found at $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco/subsystems/email/OutboundSMTP/outboundSMTP.properties but do not modify this file, set up your own $TOMCAT_HOME/shared/classes/alfresco/extension/subsystems/email/OutboundSMTP/outbound or directly in the $TOMCAT_HOME/shared/classes/alfresco-global.properties file.

GMAIL

Gmail (gmail.com) requires the use of SMTPS

This example shows how to configure two additional java mail properties directly to: <TOMCAT_HOME>/classes/alfresco-global.properties:

# Sample Gmail settings
mail.host=smtp.gmail.com
mail.port=465
mail.username=user@gmail.com
mail.password=password
mail.protocol=smtps
mail.smtps.starttls.enable=true
mail.smtps.auth=true

ZIMBRA

# Sample Zimbra settings
Not authenticated.

mail.host=zimbra.<your company>
mail.port=25
mail.username=anonymous
mail.password=
# Set this value to UTF-8 or similar for encoding of email messages as required
mail.encoding=UTF-8
# Set this value to 7bit or similar for Asian encoding of email headers as required
mail.header=
mail.from.default=<default from address>
mail.smtp.auth=false
mail.smtp.timeout=30000

You're done

Custom Configuration Example for 3.2

The mailService implementation is provided by Spring and the configuration can be customised by setting various key value pairs in javaMailProperties.

Alfresco provides configuration for the most common scenarios, however if you need a greater level of control then you can over-ride the out of the box configuration. Typically you may want to add or remove properties.

This scenario applies to Alfresco 3.2. In later versions this will work "out of the box" without needing custom configuration. Also please note that in 3.3 and greater the configuration of SMTP moves to a subsystem, so your over-ride will go into $TOMCAT_HOME/shared/classes/alfresco/extension/subsystems/email/OutboundSMTP/outbound.

Gmail (gmail.com) requires the use of SMTPS so you need to provide a few more configuration properties.

If you're using Gmail (gmail.com) you'll have to create a custom context file to over-ride the configuration of 'mailService' such as custom-email-context.xml in your alfresco/extension folder.

This example shows how to configure two additional java mail properties. These apply to: <TOMCAT_HOME>/classes/alfresco-global.properties (Alfresco 3.2)

# Sample Gmail settings
mail.host=smtp.gmail.com
mail.port=465
mail.protocol=smtps
mail.username=user@gmail.com
mail.password=password

# New Properties
mail.smtps.starttls.enable=true
mail.smtps.auth=true

Note that we've added these two new java mail properties to the file:

${mail.smtps.auth}
${mail.smtps.starttls.enable}

Now, we need to enable SMTPS by overriding the mailService bean. Create and edit <TOMCAT_HOME>/classes/alfresco/extension/custom-email-context.xml and paste in the following:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>
<!--                        -->
<!-- MAIL SERVICE           -->
<!--                        -->

<bean id="mailService" class="org.springframework.mail.javamail.JavaMailSenderImpl">
    <property name="host">
        <value>${mail.host}</value>
    </property>
    <property name="port">
        <value>${mail.port}</value>
    </property>
    <property name="protocol">
        <value>${mail.protocol}</value>
    </property>
    <property name="username">
        <value>${mail.username}</value>
    </property>
    <property name="password">
        <value>${mail.password}</value>
    </property>
    <property name="defaultEncoding">
        <value>${mail.encoding}</value>
    </property>
    <property name="javaMailProperties">
        <props>
            <prop key="mail.smtps.auth">${mail.smtps.auth}</prop>
            <prop key="mail.smtps.starttls.enable">${mail.smtps.starttls.enable}</prop>
        </props>
    </property>
</bean>
</beans>

Custom Configuration Example for 3.3+

The mailService implementation is provided by Spring and the configuration can be customised by setting various key value pairs in javaMailProperties.

Alfresco provides configuration for the most common scenarios, however if you need a greater level of control then you can over-ride the out of the box configuration. Typically you may want to add or remove properties.

This scenario applies to Alfresco 3.3. In previous versions you'll had to create a custom context file to over-ride the configuration of 'mailService' such as custom-email-context.xml in your alfresco/extension folder. On 3.3 and greater version this will work "out of the box" without needing custom configuration, you'll just have to configure with properties.

All the configuration you may need can be found at $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco/subsystems/email/OutboundSMTP/outboundSMTP.properties but do not modify this file, set up your own $TOMCAT_HOME/shared/classes/alfresco/extension/subsystems/email/OutboundSMTP/outbound or directly in the $TOMCAT_HOME/shared/classes/alfresco-global.properties file.

Gmail (gmail.com) requires the use of SMTPS so you need to provide a few more configuration properties.

This example shows how to configure two additional java mail properties directly to: <TOMCAT_HOME>/classes/alfresco-global.properties (Alfresco 3.3):

# Sample Gmail settings
mail.host=smtp.gmail.com
mail.port=465
mail.username=user@gmail.com
mail.password=password

# New Properties
mail.protocol=smtps
mail.smtps.starttls.enable=true
mail.smtps.auth=true

You're done

Email Action Executor

Alfresco uses the action service to send email.

MailActionExecuter The following properties can be set.

• PARAM_NAME = "mail"
• PARAM_TO = "to"
• PARAM_TO_MANY = "to_many"
• PARAM_SUBJECT = "subject"
• PARAM_TEXT = "text"
• PARAM_FROM = "from"
• PARAM_TEMPLATE = "template";
• FROM_ADDRESS = "alfresco@alfresco.org";

Debugging

To debug, you could put in alfresco log4j:

log4j.logger.org.alfresco.web.bean.TemplateMailHelperBean=debug

That will log mail emission attempts:

5:25:09,470 User:admin DEBUG [web.bean.TemplateMailHelperBean] Sending notification email to: user1@localhost
...with subject:
Test subject
...with body:
Test body

You could also do a network dump on the alfresc server to dump the stmp traffic.

Misc

This information was gathered from these places:

Email - Alfresco with Gmail SMTP: [1]

failed to send email via gmail smtp: [2]

Alfresco: Sending mails with Gmail: [3] Note: This is an alternative to above configuration, we suggest not editing files inside the Alfresco WAR, instead use the extensions directory approach noted above.

---

Back to Server Configuration