How to configure SMTP in Koha so notices actually send

Koha does not send email when a notice is generated. It writes the notice to a queue, and a cron job delivers the queue every 15 minutes. So "notices are not sending" is almost always one of three things: no SMTP server configured, email not enabled for the instance, or the queue job not running. Fix them in that order.

Since Koha 20.05 the mail server is configured in the database, not in a config file. Every instance starts with one implicit default — localhost on port 25, no encryption — which works only if a mail transfer agent is running on the same box and is allowed to relay. Most servers have neither.

1. 1Go to Administration → Additional parameters → SMTP servers.
2. 2Click New SMTP server.
3. 3Name — anything you will recognise later, e.g. Library mail.
4. 4Host — your provider's server, e.g. smtp.example.org.
5. 5Port — 587 for STARTTLS, 465 for SSL, 25 only for an unauthenticated relay on your own network.
6. 6SSL mode — STARTTLS with port 587, SSL with port 465, Disabled with port 25.
7. 7User name and Password — leave both blank for an unauthenticated relay; otherwise the mailbox credentials.
8. 8Tick Default so every library uses it, then Submit.

A message with no sender is rejected by most receiving servers before it reaches a mailbox. Koha takes the from-address from the branch first and falls back to a system preference.

1. 1Set Administration → Libraries → your library → Email address. This is what patrons see and reply to.
2. 2Set Administration → System preferences → KohaAdminEmailAddress as the fallback.
3. 3If your provider only accepts mail from an address it hosts, both must be an address at that domain — not a personal address forwarded to it.

This is the step almost every published guide leaves out, and the reason a correctly configured SMTP server still sends nothing. The package's cron entry runs the queue only for instances that have email enabled, which is a flag file on disk — not a setting in the staff interface.

$ sudo koha-email-enable library

Replace library with your instance name; sudo koha-list prints it. Confirm the flag took:

$ sudo koha-list --email library

If your instance is not in that list, the delivery job is skipping it and nothing else you change will matter.

Do not wait 15 minutes to find out. Run the delivery job by hand, with verbose output:

$ sudo koha-foreach --chdir --enabled --email \    /usr/share/koha/bin/cronjobs/process_message_queue.pl -v

A working run prints one line per message sent. A run that prints nothing at all means the queue is empty — generate a test notice first, for example by triggering a password reset or checking an item out to a patron with an email address and messaging preferences set.

Koha queues rather than sends because sending is slow and unreliable and the thing that triggered it is not. A checkout that had to wait for an SMTP handshake would block the circulation desk every time the mail server was busy, and would fail the checkout outright when the mail server was down. Writing a row and moving on means a delivery problem is a delivery problem, never a circulation one.

The cost is that email has three independent failure points instead of one, and none of them reports to the screen where the notice was generated. The queue is the seam: anything before it is a Koha configuration problem, anything after it is a mail problem, and the status column tells you which side you are on.

The per-instance email flag exists because one server runs many instances. A test instance restored from a production backup still holds every real patron address, and an operator who did not want it emailing them would have no way to stop it if delivery were simply always on.

If you are using a Gmail or Google Workspace mailbox as the sending account, the credentials work differently — see using a Gmail account as Koha's SMTP server.