Koha can send useful emails to patrons and staff, but the setup can feel confusing for beginners. A library may configure SMTP correctly and still not receive notices because system preferences, notices, patron messaging preferences, or cron jobs are missing.
This Koha Email Configuration Tutorial explains the full email setup in simple steps. You will learn how to add an SMTP server, configure sender addresses, enable email, prepare notices, run cron jobs, test safely, and fix common problems.
The guide is written for beginners who manage Koha on a Linux server, especially Debian or Ubuntu package-based installations. It covers the practical settings needed to help Koha send notices such as overdue reminders, due-date alerts, hold notices, welcome emails, and staff messages.
How Koha Email Works in Simple Words
Koha email is not only one setting. It works like a small delivery chain. First, Koha creates a notice. This may be an overdue notice, due-date reminder, hold reminder, welcome email, or account message. Then Koha places the message in the message queue. After that, a cron job processes the message queue and sends the email through the SMTP server.
The important point is simple: SMTP sends the email, but cron jobs often prepare and process the notices. If SMTP is correct but cron jobs are missing, emails may stay queued or may never be created.
What You Need Before Configuring Koha Email
Before you start, collect the basic details. This saves time and prevents mistakes during setup.
| Requirement | Example |
|---|---|
| Koha staff admin access | Superlibrarian or staff account with admin permission |
| Koha instance name | library |
| SMTP host | smtp.gmail.com or your institution’s mail server |
| SMTP port | 587 for STARTTLS or 465 for SSL |
| SMTP username | library@example.com |
| SMTP password | App password or SMTP password |
| Sender email | library@example.com |
| Test patron account | A safe test account with your own email |
| Server shell access | Needed for cron and package commands |
Do not test with real patron emails first. Use a safe test email address until you confirm that Koha sends messages correctly.
Best SMTP Options for Koha
Koha can use different SMTP providers. The best choice depends on your library size, budget, and technical support.
| SMTP Option | Best For | Pros | Cons |
|---|---|---|---|
| Gmail | Small test libraries | Easy to start and familiar | Sending limits and app password may be required |
| Google Workspace | Schools, colleges, and institutions | Professional domain email and reliable SMTP | Needs admin-managed account |
| Microsoft 365 | Institutions already using Outlook | Works well for organizations | SMTP authentication may need admin setup |
| Institutional SMTP | Universities and public libraries | Uses official library domain | Requires IT department support |
| SendGrid, Mailgun, Amazon SES | Larger email volume | Better deliverability tools | More technical setup |
| Local Postfix relay | Self-managed Linux servers | Full server control | Higher maintenance and deliverability work |
For beginners, Gmail or Google Workspace is often easiest for testing. For a live public or academic library, a domain-based institutional SMTP account is usually more professional.
You may also like to read: How to Make Koha Available in Network in 2026
Step 1: Find Your Koha Instance Name
Many Koha server commands need the instance name. The instance name is not always the same as your library branch name.
Run this command:
sudo koha-list --enabledIf the output is:
libraryThen your instance name is:
libraryYou will use this name in commands such as:
sudo koha-email-enable libraryStep 2: Prepare Your SMTP Email Account
Your SMTP account is the email account Koha uses to send messages. For example, a school library may use:
library@school.eduA public library may use:
notices@citylibrary.orgAvoid using a personal email address. Koha messages should come from a library-controlled inbox because patrons may reply to notices, and bounced emails may arrive there.
For Gmail or Google Workspace SMTP, the common SMTP server is smtp.gmail.com. Port 587 is commonly used for STARTTLS, while port 465 is commonly used for SSL. Many Google accounts require an app password instead of the normal account password.
Step 3: Add SMTP Server in Koha
Log in to the Koha staff interface.
Go to:
More → Administration → Additional parameters → SMTP serversClick:
New SMTP serverFill in the fields carefully.
| Field | What to Enter |
|---|---|
| Name | A clear name, such as Library Gmail SMTP |
| Host | SMTP host, such as smtp.gmail.com |
| Port | Usually 587 for STARTTLS or 465 for SSL |
| Timeout | Example: 30 or 60 seconds |
| SSL | Choose STARTTLS for port 587 or SSL for port 465 |
| Username | Full SMTP email address |
| Password | SMTP password or app password |
| Debug mode | Enable only while testing |
| Default server | Yes, if all libraries use this SMTP server |
Use secure SMTP settings where possible. Avoid sending production library emails through an unsecured configuration.
Step 4: Set the SMTP Server as Default
If your Koha installation has one library or one shared email account, set the SMTP server as the default server. This keeps the setup simple.
If your Koha system has multiple branches, each branch may use a different sender identity. A single-school library may use one default SMTP account. A large public library system may use separate emails for each branch.
For example:
central@library.org
northbranch@library.org
children@library.orgStep 5: Configure Koha Email System Preferences
SMTP is only part of the setup. You should also check Koha’s email-related system preferences.
Go to:
More → Administration → Global system preferencesSearch these preferences.
| Preference | What It Does | Beginner Recommendation |
|---|---|---|
KohaAdminEmailAddress | Default From/admin address | Use a shared library email |
ReplytoDefault | Default Reply-To address | Use an inbox staff check |
ReturnpathDefault | Bounce/undeliverable address | Use a monitored bounce inbox |
SendAllEmailsTo | Redirects all outgoing email to one address | Use only during testing |
EmailOverduesNoEmail | Sends overdue notices for patrons without email to staff | Use if staff need to handle no-email patrons |
The most important warning is about SendAllEmailsTo. It is useful for testing, but it should not remain enabled in production. If it stays active, real patrons may not receive their intended emails.
Step 6: Enable Email for the Koha Instance
On Debian package-based Koha installations, email can be enabled for an instance with this command:
sudo koha-email-enable libraryReplace library with your real Koha instance name.
If email is already enabled, Koha may warn that it is already enabled. That is fine.
Step 7: Configure Notices and Slips
Now check the email templates Koha will send.
Go to:
Tools → Notices and slipsCommon notices include:
| Notice Type | Purpose |
|---|---|
| Welcome email | Sent when a new patron account is created |
| Advance notice | Sent before an item becomes due |
| Item due notice | Sent when an item is due |
| Overdue notice | Sent when an item is late |
| Hold notice | Sent when a reserved item is ready |
| Account notice | Sent for account or payment messages |
Make sure each important notice has a clear subject and useful message body. A blank or confusing template makes the email look broken, even when SMTP is working.
A good notice should include the patron name, item title, due date, library name, contact email, and a short action message.
Example notice template:
Subject: Library item due soon
Hello <<borrowers.firstname>>,
This is a friendly reminder that the following library item is due soon:
Title: <<biblio.title>>
Due date: <<issues.date_due>>
Please return or renew it before the due date.
Thank you,
Your Library TeamStep 8: Configure Patron Messaging Preferences
Notices may not send if patron messaging preferences are not set correctly. Koha can send different message types depending on system preferences, patron category settings, and each patron’s preferences.
Check messaging-related settings in global system preferences and patron categories. Then open a test patron account and confirm the patron has a valid email address.
Also confirm the patron is allowed to receive the message type you want to test. For example, if you want to test advance notices, make sure advance notice messaging is enabled for that patron or patron category.
Step 9: Configure Overdue Notice Triggers
SMTP does not automatically decide when to send overdue emails. Koha needs overdue rules.
Go to:
Tools → Overdue notice/status triggersHere you can set when overdue notices should be generated.
| Delay | Notice |
|---|---|
| 3 days overdue | First reminder |
| 7 days overdue | Second reminder |
| 14 days overdue | Final reminder |
The overdue notice script creates and queues overdue notices according to these trigger rules. Another process then sends the queued emails.
Step 10: Set Up Cron Jobs for Email Sending
Cron jobs are the hidden part of Koha email configuration. Without them, Koha may create messages but never send them, or it may not create automated notices at all.
| Script | What It Does | Suggested Frequency |
|---|---|---|
advance_notices.pl | Prepares advance and due notices | Nightly |
overdue_notices.pl | Prepares overdue notices | Nightly |
process_message_queue.pl | Sends queued emails and SMS messages | Every 1 to 4 hours |
For package installs, Koha cron scripts are commonly found under:
/usr/share/koha/bin/cronjobs/Example cron entries may look like this:
0 1 * * * /usr/share/koha/bin/cronjobs/advance_notices.pl -c
15 1 * * * /usr/share/koha/bin/cronjobs/overdue_notices.pl
*/30 * * * * /usr/share/koha/bin/cronjobs/process_message_queue.plYour exact cron setup may vary by server, Koha version, package configuration, and local policy. Test commands manually before relying on scheduled jobs.
Step 11: Test Koha Email Safely Before Going Live
Use a test email first. Do not send to real patrons until the setup is checked.
- Create a test patron with your own email address.
- Set
SendAllEmailsToto your own test email. - Create or trigger a notice.
- Run the message queue.
- Confirm the email arrives.
- Clear
SendAllEmailsTobefore going live.
This is important because SendAllEmailsTo redirects all messages to one address. It is helpful during testing, but dangerous if forgotten in production.
Beginner Example: Gmail SMTP Setup for Koha
For Gmail or Google Workspace, your Koha SMTP settings may look like this:
| Field | Value |
|---|---|
| Name | Gmail SMTP |
| Host | smtp.gmail.com |
| Port | 587 |
| SSL | STARTTLS |
| Username | Your full Gmail or Google Workspace email |
| Password | Google app password |
| Default server | Yes, if used by all libraries |
Do not use your normal Gmail password if Google requires an app password for your account. Create an app password from your Google account security settings and use that password inside Koha.
Beginner Example: Institutional SMTP Setup
If your school, college, university, or city library has its own mail server, ask the IT team for these values:
| Question for IT Team | Example Answer |
|---|---|
| SMTP host? | smtp.school.edu |
| SMTP port? | 587 |
| Security type? | STARTTLS |
| Username? | library@school.edu |
| Password method? | SMTP password or app password |
| Allowed sender address? | library@school.edu |
| Sending limit? | Example: 500 messages per day |
| SPF/DKIM configured? | Yes |
This option usually looks more professional because patrons receive email from the library’s domain instead of a free email provider.
Read Also: Koha SQL Reports Generator
Common Koha Email Problems and Fixes
If Koha emails are not sending, use this troubleshooting table before changing random settings.
| Problem | Likely Cause | Fix |
|---|---|---|
| SMTP authentication failed | Wrong password or app password missing | Generate a correct SMTP or app password |
| Messages stay queued | process_message_queue.pl not running | Configure the message queue cron job |
| Overdue notices not created | Overdue triggers not configured | Set overdue notice/status triggers |
| Advance notices not created | Messaging preferences not enabled | Enable messaging settings and patron preferences |
| Patron does not receive email | No email in patron record | Add a valid patron email |
| All emails go to one inbox | SendAllEmailsTo still enabled | Clear it before production |
| Gmail blocks sending | Wrong authentication method or security setting | Use app password and correct port/security |
| Sender address looks wrong | KohaAdminEmailAddress or library email missing | Set admin and branch email addresses |
| Email goes to spam | SPF, DKIM, or DMARC missing | Ask domain admin to configure email authentication |
| Email body looks broken | Notice template issue | Edit Notices and slips |
Security and Deliverability Tips
Use a dedicated sender address for Koha notices. A shared inbox like library@domain.org or notices@domain.org is better than a personal staff email.
Use a strong password or app password and keep it private. Do not paste SMTP passwords into public tutorials, screenshots, tickets, or shared documents.
For domain-based email, ask your IT team to configure SPF, DKIM, and DMARC. These records help receiving mail servers trust your library’s messages and reduce the chance of notices landing in spam.
Use a monitored bounce address. If emails fail, bounced messages can help staff identify old, incorrect, or missing patron email addresses.
Koha Email Configuration Checklist
Before going live, check each item carefully.
| Task | Done |
|---|---|
| SMTP server added in Koha | ☐ |
| Correct SMTP host and port entered | ☐ |
| STARTTLS or SSL selected correctly | ☐ |
| SMTP username and password tested | ☐ |
| Default SMTP server selected | ☐ |
KohaAdminEmailAddress set | ☐ |
ReplytoDefault checked | ☐ |
ReturnpathDefault checked | ☐ |
SendAllEmailsTo used only for testing | ☐ |
| Email enabled for Koha instance | ☐ |
| Notices and slips reviewed | ☐ |
| Patron messaging preferences checked | ☐ |
| Overdue notice triggers configured | ☐ |
| Message queue cron job running | ☐ |
| Test email received | ☐ |
| Real patron sending tested carefully | ☐ |
Summary
A good Koha Email Configuration should not stop at SMTP settings. SMTP only gives Koha a way to send email. You also need correct system preferences, email templates, patron messaging settings, overdue triggers, cron jobs, and safe testing.
For beginners, the best workflow is simple: add SMTP in Koha, set the correct sender addresses, enable email for the instance, review notices, configure cron jobs, test withSendAllEmailsTo, and only then send real notices to patrons. This guide is based on Koha community guidelines.
FAQs About Koha Email Configuration
The easiest way is to use Koha’s SMTP servers page in the staff interface. Go to Administration → Additional parameters → SMTP servers, add your SMTP details, set the server as default, and then test notices.
Yes, Koha needs an email delivery method. In modern setups, SMTP is the cleanest option because it lets Koha send through Gmail, Google Workspace, Microsoft 365, institutional mail servers, or transactional email services.
The most common causes are wrong SMTP credentials, email not enabled for the instance, missing cron jobs, empty notices, disabled patron messaging preferences, or SendAllEmailsTo being misused.
process_message_queue.pl processes Koha’s message queue and sends outgoing emails and SMS messages. If this job is not running, messages may remain queued.
The overdue notice script creates and queues overdue notices based on overdue trigger settings. It does not directly send the email. The message queue processor sends queued messages afterward.
Yes, Gmail or Google Workspace can be used for SMTP when the account supports SMTP authentication. Use smtp.gmail.com, the correct port, the right security method, and an app password when required.
No. A personal email account is not ideal for library notices. Use a dedicated library-controlled address such as library@example.org or notices@example.org.
SendAllEmailsTo redirects all outgoing Koha email to one address. It is useful for testing, but it should not remain enabled in production because real patrons will not receive their intended messages.
Yes, for many automated notices. Cron jobs generate advance notices, overdue notices, and process the message queue. SMTP alone is not enough for a complete automated notice system.
Use a shared, monitored library email address. Good examples include library@domain.org, circulation@domain.org, or notices@domain.org.
