Use this information to configure email services, including inbound and outbound email, subscriptions, and email clients.

Configure inbound and outbound email

The email subsystem allows you to configure the outbound and inbound SMTP email settings to interact with Community Edition.

You can run the email server process in the same JVM context as the repository.

Inbound SMTP configuration properties

The Inbound SMTP email subsystem type allows you to configure the behavior of the email server and service.

The following properties can be set for Inbound SMTP email in the alfresco-global.properties file.

Outbound SMTP configuration properties

The following properties can be configured for the Outbound SMTP subsystem type.

Note: You must set the Outbound email configuration for Alfresco Share invitations to work correctly. If you don’t set the email configuration, when you invite a user to a site, the user will not receive the assigned task notification.

The email service is exposed as a Spring bean, mailService, which is contained in the Outbound SMTP subsystem.

Configure the repository to send emails to an external SMTP server by overriding the default settings. Set the email property overrides in the alfresco-global.properties file.

The following properties are for SMTP:

The following properties are for SMTPS:

The following properties can be set to define a test message when the subsystem starts:

The following property is for setting the email site invitation behavior:

The following examples show which properties to set for two different email clients. Add these properties to the alfresco-global.properties file.

The following example shows the properties that you need to set to configure Gmail:

Code copied to clipboard.
# 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

The following example shows the properties that you need to set to configure Zimbra:

Code copied to clipboard.
# 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

Handle messages by target node type

Default behaviors for incoming email to different types of referenced nodes. You can modify or extend the default behaviors by adding in custom handlers.

Groups and permissions for email

An email arriving at the Community Edition email server is unauthenticated. An authentication group, EMAIL_CONTRIBUTORS, must exist to allow permissions to be handled at a high level by the administrator.

When an email comes into the system, the only identification is the sender’s email address. The user is looked up based on the email address.

• If a matching user isn’t found, then the current user is assumed to be unknown, if unknown exists.
• If unknown doesn’t exist, then the email is rejected as authentication won’t be possible.
• If the user selected isn’t part of email contributor’s group, then the email is rejected.

The current request’s user is set and all subsequent processes are run as the authenticated user. If any type of authentication error is generated, then the email is rejected. The authentication will also imply that the authenticated user may not have visibility of the target node, in which case the email is also rejected. Effectively, this means that the target recipient of the email doesn’t exist, at least not for the sender.

The current default server configuration creates the EMAIL_CONTRIBUTORS group and adds the admin user to this group.

Configure email client with IMAP

IMAP protocol support allows email applications that support IMAP (including Outlook, Apple Mail, Thunderbird, and so on) to connect to and interact with Community Edition repositories.

Each user has their own set of mailboxes stored in Community Edition, for example, they have their own INBOX. Users can manage emails in Community Edition, and the workflow, transformation, and permissions features are available.

In addition, sites can be nominated as IMAP Favorites. This means that the site contents show as a set of IMAP folders. Non-favorite sites are not shown.

A metadata extractor for IMAP emails (RFC822 messages) can extract values from the contents of the email message and store the values as properties.

Note: Be careful when deciding what mount points you provide. When an IMAP client mounts a mount point, it issues a LSUB "" * command. This retrieves the entire tree of folders below the mount point.

Enable IMAP protocol using alfresco-global.properties

The IMAP protocol server is disabled by default. You need to enable the IMAP protocol server to start interaction between the email client and the repository.

1. Open the alfresco-global.properties file.

2. Enable the IMAP server by setting the following property to true:

   Code copied to clipboard.
    imap.server.enabled=true
   

3. Set the IMAP server to listen on a specific interface using the following property:

   Code copied to clipboard.
    imap.server.host=x.x.x.x
   

   where x.x.x.x is the IP address (or corresponding DNS address) of your external IP interface. Don’t use 127.0.0.1 or localhost.

   By default, the IMAP server listens on all interfaces on the default IMAP port of 143. You can set this property to use an alternative port number, for example 144.

4. Restart the Community Edition server.

Once the server has restarted, the new configuration will take effect. Since the IMAP server has only one instance, make your configuration changes to the <extension root>alfresco-global.properties file. You can also make your changes to <extension root>\alfresco\extension\subsystems\imap\default\default for the IMAP subsystem configuration to take precedence.

IMAP subsystem properties

The following properties can be configured for the IMAP subsystem.

Enable IMAP protocol

The following properties control the IMAP subsystem:

Configure the following properties of the sysAdmin subsystem:

To configure the IMAP Home space, which is used to store user mailboxes in ARCHIVE mode, in particular the user’s INBOX, use the following properties:

Enable IMAPS

IMAPS is a secure IMAP that’s encrypted using SSL. IMAPS is assigned to port number 993 by default. When you’ve enabled the IMAP subsystem, you must configure the default Java keystore, and then enable IMAPS.

To configure the default Java keystore, use the following properties:

To enable IMAPS, use the following properties:

Extract attachments

An IMAP message can contain a message and a set of attachments, and the IMAP server can split the attachments into separate content nodes. Use this property with caution if you have a large repository. See Troubleshooting IMAP for more information.

IMAP mount points

IMAP mount points are used to control which folders are available using IMAP and the mode in which they are accessed. Modes are used to define the type of interaction available.

The IMAP integration offers the following access modes:

Add the IMAP composite property, imap.config.server.mountPoints along with the names of your IMAP mount points to the alfresco-global.properties file. For each mount point specify the following settings:

• beanName
• store
• rootPath
• mode

By default, a single mount point called AlfrescoIMAP is defined in the MIXED mode for Company Home and you can change it or add more mount points.

Code copied to clipboard.
imap.config.server.mountPoints=AlfrescoIMAP
imap.config.server.mountPoints.default.mountPointName=IMAP
imap.config.server.mountPoints.default.modeName=ARCHIVE
imap.config.server.mountPoints.default.store=${spaces.store}
imap.config.server.mountPoints.default.rootPath=/${spaces.company_home.childname}
imap.config.server.mountPoints.value.AlfrescoIMAP.mountPointName=Alfresco IMAP
imap.config.server.mountPoints.value.AlfrescoIMAP.modeName=MIXED

In JMX dump, the same presentation looks like this:

Code copied to clipboard.
** Object Name Alfresco:Type=Configuration,Category=imap,id1=default,id2=imap.config.server.mountPoints,id3=AlfrescoIMAP
** Object Type imap$default$imap.config.server.mountPoints$AlfrescoIMAP
folderPath
mode           MIXED
modeName       MIXED
mountPointName Alfresco IMAP
rootPath       /app:company_home
store          workspace://SpacesStore
storeRef       workspace://SpacesStore

Note: Be careful when deciding what mount points you provide. When an IMAP client mounts a mount point, it issues a LSUB "" * command. This retrieves the entire tree of folders below the mount point.

Virtual view email format

The virtualized view uses presentation templates to generate the mail body and display document metadata, action links (for download, view, webdav, folder) and Start Workflow form (HTML view only).

The templates are stored in the repository in Company Home > Data Dictionary > Imap Configs > Templates. Separate templates are available to generate either a HTML or plain text body, based on the format request by the email client. The templates can be customized to change the metadata and actions available in the email body.

Mark sites as IMAP favorites

To have access to Alfresco Share sites using IMAP, the site(s) need to be added to your list of sites using Share IMAP Favorites.

1. Select IMAP Favorites in the Share My Sites dashlet on your My Dashboard page:

   

2. Refresh your IMAP view to see the new sites.

   

   You can see the site added to the IMAP Sites folder.

   Note: If the folders don’t appear in your email client, you should confirm that:

   • The folder is in a site marked as an IMAP favorite.
   • Your email client is showing all folders, and not just the folders that you have subscribed to.
   • In your email client, look for a property like Reload IMAP folders.
   • In your email client, clear your IMAP cache.

Configure email templates using v1 REST APIs

Use this information to configure customized email templates for your registered applications using the v1 REST APIs.

There are a number of properties for configuring customized email templates when using the v1 REST APIs. Once you have developed your custom application, add the required properties in the global properties file (alfresco-global.properties) to register your application. In this file you can also set the path to each email template and any linked assets (such as images and company logo) to use your own branding.

The shared-links and request-password-reset APIs provide a way to send email notifications. To view these APIs, navigate to:

One of the mandatory properties in the request body of these APIs, client, sets the name of your registered client application. Registering a client means you can create a unique email template for each client, and configure the required email template and assets using different properties.

The client registration is based on a predefined naming convention loaded from properties files. The naming convention must conform to the format:

Code copied to clipboard.
repo.client-app.<client-name>.<propertyName>

Note: The client name (<client-name>) and property name (<propertyName>) must not contain a dot (.).

An example implementation is provided where Alfresco Share is registered as the default client for the shared-links and request-password-reset APIs. These properties are defined in alfresco/client/config/repo-clients-apps.properties but you can override them in alfresco-global.properties:

Code copied to clipboard.
 repo.client-app.share.templateAssetsUrl=${shareUrl}/res/components/images/
 # shared-link (quickShare) base url
 repo.client-app.share.sharedLinkBaseUrl=${shareUrl}/s
 # shared-link email template path
 repo.client-app.share.sharedLinkTemplatePath=
 # reset password request email template path
 repo.client-app.share.requestResetPasswordTemplatePath=
 # reset password UI page url
 repo.client-app.share.resetPasswordPageUrl=${shareUrl}/page/reset-password
 # reset password confirmation email template path
 repo.client-app.share.confirmResetPasswordTemplatePath=

Note: Any property without a value is ignored, however, a client can’t be registered if all the properties of that client have no values.

Configure customized email templates

In Community Edition you can customize the emails that are sent by the v1 REST API when users share links to content and request a password change.

To customize an email template for your application, register the application as a new client, then create new email templates using your own branding by adding them to the Data Dictionary.

1. Open Share, and click Repository on the toolbar.

2. Click Data Dictionary then Email Templates.

   You can create a folder to store your customized email templates here.

3. Add the required properties to alfresco-global.properties.

   Here’s an example implementation for the default Share client that uses the v1 REST APIs:

   Code copied to clipboard.
    repo.client-app.share.templateAssetsUrl=${shareUrl}/res/components/images/
    repo.client-app.share.sharedLinkBaseUrl=${shareUrl}/s
    repo.client-app.share.sharedLinkTemplatePath=
    repo.client-app.share.requestResetPasswordTemplatePath=
    repo.client-app.share.resetPasswordPageUrl=${shareUrl}/page/reset-password
    repo.client-app.share.confirmResetPasswordTemplatePath=
   

   Note: Any property without a value is ignored, however, a client can’t be registered if all the properties for that client have no values.

   Here’s the full list of property settings that you can configure. Note that the expected format of the email template paths (*TemplatePath) are similar:

   Property	Description
   sharedLinkTemplatePath requestResetPasswordTemplatePath confirmResetPasswordTemplatePath	Define the template path as an XPATH, NodeRef or classpath Example: XPATH: app:company_home/app:dictionary/app: email_templates/cm:example-email.ftl NodeRef: workspace://SpacesStore/a371fc59-d5ea-4849-a45c-b00c0c0d00ab Class path: alfresco/templates/quickshare-email-templates/ myapp-template.ftl
   templateAssetsUrl	The URL of the assets for the email template, such as images and logos, used in the HTML template. Example: ${shareUrl}/res/components/images/
   sharedLinkBaseUrl	The base URL of a page where the registered application displays the shared content. Example: ${shareUrl}/s

   For example, to register the application myapp to send customized shared-link emails, add the following properties to alfresco-global.properties:

   Code copied to clipboard.
    repo.client-app.myapp.sharedLinkTemplatePath=myapp email template path
    repo.client-app.myapp.templateAssetsUrl=myapp email template assets url
    repo.client-app.myapp.sharedLinkBaseUrl=myapp url
   

   Note: If the template path isn’t a valid nodeRef or template, the fallback template for Share is used.

4. Restart the Alfresco server.

You can view your registered clients by using a JMX client, located under the ClientsAppsConfigInformation MBean.