Configuring Gmail SMTP for DSpace 9 on Ubuntu Linux Server

Email functionality in DSpace is not optional. It is a core requirement for system notifications, workflow alerts, feedback messages, and most importantly, new user account creation.
When SMTP is not configured correctly, newly added E-Persons never receive their welcome email or password, effectively locking them out of the system.

Recently, while working with DSpace 9.1 on Ubuntu 24.04, I encountered exactly this issue. This post documents the complete process I followed to configure Gmail SMTP using Google Workspace, along with explanations so others can reproduce it without guesswork.

Why SMTP Configuration Is Critical in DSpace

DSpace relies on email for:

• User registration and password delivery
• Workflow and submission notifications
• Feedback form messages
• System alerts and administrative communication

If SMTP is broken:

• Users cannot log in after account creation
• Admin notifications fail silently
• The repository appears functional but is not operational

Hence, SMTP must be configured before a production rollout.

Prerequisites

• Ubuntu 24.04
• DSpace 9.1 installed and running
• Admin access to the DSpace server
• Access to a Google Workspace or Gmail account

Create a Dedicated Gmail Account for DSpace

Do not use your personal or primary institutional email account.

Instead:

• Create a dedicated email address, such as
  [email protected]
• This account will act as the sender for all DSpace-generated emails

This separation is cleaner, safer, and easier to manage.

Enable 2-Step Verification in Google Account

Google does not allow SMTP access using your normal account password.

To proceed, you must enable 2-Step Verification.

1. Go to: https://myaccount.google.com
2. Open Security
3. Under How you sign in to Google, enable 2-Step Verification

If the account is managed by your organization, your Google Workspace admin must allow 2-Step Verification.

Generate an App Password

App Passwords are required for legacy or third-party services like DSpace.

1. Open Google Account → Security
2. Scroll to App passwords
   • If you don’t see it, use the search bar and type App passwords
3. Create a new app password
   • Name it something like: DSpace Email
4. Google will generate a 16-character password
5. Copy it immediately
   (you will not be able to see it again)

This password will be used in the DSpace configuration.

Edit DSpace Email Configuration

Log in to your DSpace server and open the local.cfg file.

sudo nano /dspace/local.cfg

Locate or add the EMAIL CONFIGURATION section.

Basic SMTP Settings

#######################
# EMAIL CONFIGURATION #
#######################

mail.server = smtp.gmail.com
mail.server.username = [email protected]
mail.server.password = abcdefghijklmnop
mail.server.port = 465

Replace:

• [email protected] with your DSpace sender email
• abcdefghijklmnop with the App Password

Configure Sender and Admin Addresses

Update all relevant email fields so messages originate consistently.

mail.from.address = [email protected]
mail.admin = [email protected]
feedback.recipient = [email protected]
mail.helpdesk = ${mail.admin}
mail.helpdesk.name = Help Desk
alert.recipient = ${mail.admin}

This ensures:

• System emails use the same sender
• Admin alerts are delivered properly
• Feedback messages are received

Enforce SSL for Gmail SMTP (Port 465)

To force DSpace to use Gmail’s SSL-based SMTP connection, add the following:

mail.extraproperties = mail.smtp.socketFactory.port=465, \
                       mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory, \
                       mail.smtp.socketFactory.fallback=false

This configuration instructs JavaMail to use SSL for secure communication with Gmail, while avoiding the STARTTLS fallback.

Note:
Gmail also supports Port 587 with STARTTLS, which is the modern standard. However, Port 465 with SSL works reliably with DSpace and JavaMail and is widely used.

Restart Tomcat

DSpace 9.1 requires a backend restart for configuration changes to take effect.

sudo systemctl restart tomcat10

Always restart Tomcat after modifying local.cfg.

Test Email Configuration

DSpace provides a built-in command to test SMTP.

Run:

sudo /dspace/bin/dspace test-email

Your expected Output should be

About to send test email:
 - To: [email protected]
 - Subject: DSpace test email
 - Server: smtp.gmail.com

Email sent successfully!

If configured correctly, you will receive the test email immediately.

Final Result

Once SMTP is working:

• New users receive welcome emails and passwords
• Workflow and submission notifications function correctly
• Feedback forms send messages
• System alerts reach administrators

Your DSpace installation is now production-ready from an email perspective.

SMTP configuration in DSpace is often underestimated, but it directly impacts usability and trust in the system. Using Google Workspace with App Passwords is a secure and reliable solution, provided the configuration is done carefully.

This guide reflects a real-world troubleshooting and implementation process, not a theoretical setup. If you follow the steps exactly, you should have Gmail SMTP working smoothly with DSpace 9.1.

Happy repository managing.