Overdue notices fail at one of four points, and they fail in a predictable order of likelihood:
- The cron job never ran — nothing was generated.
- The notice was never generated — the job ran, but nothing matched.
- The mail server rejected it — generated but not sent.
- It was delivered to spam — sent successfully, and never read.
Work through them in that order. Each step below tells you how to confirm whether the problem is there before moving on.
Step 1 — Is the message queue processing?
Koha does not send mail at the moment a notice is created. It writes the message to a queue, and a separate scheduled job sends what is waiting.
Look at the queue in the staff interface. What you find tells you where you are:
- Messages sitting as pending → notices are being generated but not sent. Jump to step 4.
- Messages marked sent → Koha handed them to a mail server. Go to step 5.
- Messages marked failed → the mail server rejected them. Step 4.
- Queue empty → nothing is being generated at all. Continue to step 2.
An empty queue is the most common finding, and it means the problem is upstream of email entirely.
Step 2 — Are the cron jobs running?
Two separate jobs matter, and confusing them wastes hours: one generates overdue notices, another sends whatever is queued. Either can be missing.
Confirm they actually ran rather than assuming. Check the crontab for the Koha instance user — not root, which is a frequent mistake — and look for evidence of execution in the logs. "No error email arrived" proves nothing; a job that was never scheduled sends no errors either.
Our guide to Koha cron jobs covers the full set and what each one silently breaks.
Step 3 — Is the notice being generated at all?
If the jobs run and the queue stays empty, nothing is matching. Check, in order:
- Overdue notice triggers — configured per patron category and per branch. A category with no trigger generates nothing, silently. This is the single most common cause.
- The patron has an email address. No address, no message.
- Messaging preferences — patrons can have email notices switched off, and defaults for a category may be off.
- The delay actually elapsed. A trigger at 7 days generates nothing on day 3.
- The notice template exists for the letter code the trigger references.
Step 4 — Is SMTP configured correctly?
If messages are pending or failed, the problem is between Koha and your mail server. Deliverability is one of the things a hosting arrangement either solves for you or leaves entirely on your desk.
- SMTP host, port and encryption — 587 with STARTTLS is the usual modern combination
- Authentication credentials, if the server requires them
- The sending address — many providers refuse to send as an address you do not own
- Firewall — outbound SMTP is blocked by default on some hosts
Test independently of Koha. Send a message from the server using a command-line mail client with the same settings. If that fails, the problem is not Koha and no amount of Koha configuration will fix it.
Step 5 — Are you being delivered to spam?
The hardest to diagnose, because Koha reports complete success. The message left your server; it simply never reached a human.
Three DNS records decide this:
- SPF — declares which servers may send mail for your domain. Without it, mail from your server claiming to be your domain looks forged.
- DKIM — cryptographically signs outgoing mail so receivers can verify it.
- DMARC — tells receivers what to do when SPF or DKIM fails.
Send a test to a Gmail or Outlook address you control, then view the message headers and look for SPF and DKIM results. "Pass" on both is what you need. Free mail-testing services will grade all three and tell you exactly what to add.
This is a DNS problem, not a Koha problem, which is why it defeats so many libraries — they keep reconfiguring Koha.
Fixing the notice templates
Sometimes notices arrive and are useless. Common causes:
- Placeholders showing as literal text — a misspelled field name, or one that does not exist for that notice type.
- Empty fields — the data genuinely is not there for that patron or item.
- HTML rendering as source — the notice is not flagged as HTML.
- Item lists not repeating — the repeating section is not marked correctly, so only the first overdue item appears.
Always test a template against a real record before it goes to 400 patrons. Create a test patron with your own address and an overdue loan.
A pre-flight checklist
Re-run this after any upgrade or server move — these are exactly the things that quietly break:
- Overdue triggers configured for every patron category in use
- Notice templates exist and are current
- Generation cron job scheduled and confirmed running
- Queue-processing cron job scheduled and confirmed running
- SMTP settings correct and tested independently
- SPF, DKIM and DMARC records present and passing
- Test notice received in an external inbox — not the spam folder
- Patron messaging defaults sensible for new members
Why this keeps happening
Notices depend on a scheduled job, a mail server, three DNS records and a template. Those are owned by different people — or, more often, by nobody in particular.
And nothing warns you when one stops. There is no alert for "no overdue notices generated this week". Libraries discover it when a parent says they never received anything, months later, and by then the fines are disputed.
On Koha Cloud that chain is set up and monitored: the mail server, the deliverability records, the scheduled jobs and the templates are ours, and the library never has to diagnose any of it. Notices that just work, because we run the server side.
We make server handling easy — you look after your students, we look after the server.
Notices still not arriving? Send us what you found at each step above and we will tell you where the chain is broken. We fix this on other people's Koha installations regularly.