Submit Feedback

Configuring Mail

Liferay can be configured to use a mail server to send email notifications for a variety of purposes: user registration, password management, site membership notifications, content updates, etc. You can configure the mail server connection at the instance scope or at the system scope. There are three system-scoped ways to configure Liferay DXP’s connection to a mail server:

Through the Control Panel
Through the application server
Through portal properties

The following examples demonstrate how to configure the built-in mail session to use a Gmail server with the POP3 protocol.

Warning

If you’re using the IMAP protocol for a category’s mailing list, make sure to configure the IMAP inbox to delete messages as they are pulled by the email client that sends messages to the users on the mailing list. Otherwise, each email message retained on the server is sent to the mailing list each time there’s a new post or update in the category.

Configuring Mail from the Control Panel

Follow these steps to configure the mail session from the Control Panel:

Navigate to Control Panel → Configuration → System Settings and go to Platform → Email → Mail Settings (Before Liferay DXP 2025.Q4/Portal 2026, this was done in Control Panel → Configuration → Server Administration → Mail).
Enter your values for the following fields:
- Additional Java Mail Properties: If you need any additional properties, supply them here.
- Enable POP Server Notifications Checked
- Enable StartTLS Checked
- Incoming Port: 110
- Incoming POP Server: pop.gmail.com
- Outgoing Port: 465
- Outgoing SMTP Server: smtp.gmail.com
- POP Password: *****
- POP User Name: joe.bloggs
- SMTP Password: *****
- SMTP User Name: joe.bloggs
- Store Protocol: pop3
- Transport Protocol: smtp
Click Save.

Configuring Mail from the Application Server

Follow these steps to configure the mail session from the application server:

Create a mail session on your application server.
Navigate to Control Panel → Configuration → System Settings and go to Platform → Email → Mail Settings (Before Liferay DXP 2025.Q4/Portal 2026.Q1, this was done in Control Panel → Configuration → Server Administration → Mail).
Enter the following value in Additional Java Mail Properties:
```
mail.session.jndi.name=mail/MailSession
```
Click Save.

This points DXP to the mail session on your application server.

Note

This can also be done through OSGi configuration files or portal properties.

Configuring Mail Using Portal Properties

Liferay DXP 2025.Q4/Portal 2026.Q1 and Below

To configure the mail session offline or before deploying DXP:

Create a portal-ext.properties file in your Liferay Home (if the file does not already exist).

Copy these default property settings into the portal-ext.properties file:

mail.session.mail=false
mail.session.mail.pop3.host=pop.gmail.com
mail.session.mail.pop3.password=*******
mail.session.mail.pop3.port=110
mail.session.mail.pop3.user=joe.bloggs
mail.session.mail.smtp.auth=true
mail.session.mail.smtp.host=smtp.gmail.com
mail.session.mail.smtp.password=*******
mail.session.mail.smtp.port=465
mail.session.mail.smtp.user=joe.bloggs
mail.session.mail.store.protocol=pop3
mail.session.mail.transport.protocol=smtp

Liferay connects to the mail session on the next startup.

Note

When upgrading to a newer version, Liferay automatically converts the portal properties into OSGi configurations. You can override them using configuration files.

Mail Configuration Reference

Field	Description
Additional Java Mail Properties	Optional additional JavaMail settings.
Enable POP Server Notifications	Whether to allow connection to a POP server and check for incoming emails.
Enable StartTLS	Whether to enable encryption for outgoing emails.
Incoming Port	The port on which the POP server is listening.
Incoming POP Server	The hostname for a server running the Post Office Protocol. DXP checks this mailbox for incoming messages, such as message board replies.
Outgoing Port	The port on which the SMTP server is listening.
Outgoing SMTP Server	The hostname for a server running the Simple Mail Transfer Protocol. DXP uses this server to send emails, such as password change notifications.
POP Password	The password DXP uses to log into the POP server.
POP User Name	The user ID DXP uses to log into the POP server.
SMTP Password	The password DXP uses to log into the SMTP server.
SMTP User Name	The user ID DXP uses to log into the SMTP server.
Store Protocol	The protocol used to receive emails
Transport Protocol	The protocol used to send emails