Configuration & operations
Using a Gmail account as Koha’s SMTP server
Gmail works as Koha’s mail server, but only with an app password and two-step verification on. Here are the exact settings, and the limits worth knowing before you rely on it.
Updated 2026-08-09 · Tested against Koha 26.05
Gmail works as Koha's SMTP server: host smtp.gmail.com, port 587, SSL mode STARTTLS, the full address as the user name, and a 16-character app password — not the account password. App passwords require two-step verification on the account first; there is no way around that any more.
Suitable for a small library, not a large one
- Under a few hundred notices a day: Gmail is fine and free.
- More than that: use a transactional mail provider, or your institution's own mail server.
Whichever you pick, the Koha side is identical — only the host, port and credentials change.
Step 1Create the app password
Google removed the "less secure app access" switch, so an ordinary password will be refused no matter how correct the rest of the configuration is. An app password is a per-application credential you generate once and paste into Koha.
- 1Sign in as the account that will send the notices — ideally a dedicated mailbox such as
library-notices@…, not a person's. - 2Turn on 2-Step Verification in the account's security settings. App passwords are not offered until you do.
- 3Open the App passwords page for that account.
- 4Name it
Kohaso you can revoke it later without guessing. - 5Copy the 16-character password it shows. It is displayed once.
Google Workspace administrators
Step 2Enter it in Koha
Go to Administration → Additional parameters → SMTP servers and either add a server or edit the one you have.
| Field | Value |
|---|---|
| Host | smtp.gmail.com |
| Port | 587 |
| SSL mode | STARTTLS |
| User name | The full address, e.g. library-notices@example.org |
| Password | The 16-character app password, with no spaces |
| Default | Ticked, unless you are testing a second server |
Google displays the app password in four groups of four. Paste it without the spaces. Port 465 with SSL mode SSL also works if 587 is blocked outbound on your network; do not mix the two.
Step 3Make the from-address match
Gmail will not send as an address it does not own. If your library email in Administration → Libraries is info@yourlibrary.org but the SMTP account is a @gmail.com address, Google rewrites the sender or rejects the message outright — and patrons reply into a mailbox nobody reads.
- Simplest: make the library email address and
KohaAdminEmailAddressthe same address as the SMTP account. - On Workspace with your own domain, that is already true and nothing further is needed.
- On consumer Gmail with a different reply-to domain, add the address in Gmail under Send mail as and verify it first.
Step 4Test it before you trust it
Enable email for the instance if you have not already, then run the delivery job by hand and watch it:
$ sudo koha-email-enable library$ sudo koha-foreach --chdir --enabled --email \ /usr/share/koha/bin/cronjobs/process_message_queue.pl -vNothing to send? Trigger a notice first — a patron password reset is the quickest. If messages sit in the queue rather than failing, the problem is the instance flag, not Gmail; the full sequence is in configuring SMTP in Koha.
Why an app password and not the real one
A password typed into a login form is protected by everything around it — the second factor, the device check, the sign-in alert. A password stored in a server's database has none of that, and Koha needs to present it unattended every 15 minutes. Google's position is that a credential used that way should be a different credential: scoped to one application, revocable on its own, and useless for signing in to the account.
That is worth taking seriously rather than working around. The app password lives in your Koha database, and anyone with database access can read it — so use a mailbox that sends notices and does nothing else, and revoke the credential rather than change the account password when someone leaves.
Common failures
| What you see | What it usually is |
|---|---|
| <code>Username and Password not accepted</code> | The account password was used instead of an app password, or the app password was pasted with its spaces. |
| App passwords option missing | Two-step verification is off, or a Workspace administrator has disabled app passwords for the organisation. |
| Connection times out | Outbound port 587 is blocked by a firewall. Try 465 with SSL mode SSL, or open the port. |
| Sends for a week, then stops | The daily sending limit was reached. Notices resume the next day and the queue is not lost, but this is the signal to move off Gmail. |
| Arrives in spam | The from-address domain has no SPF record naming Google as a sender. Fix it at your DNS host. |
Would rather not do this yourself? We do it as a service — and if you would rather it were already done, it is on Koha Cloud before you log in.
Related
More on configuration & operations
Answers to the questions that usually arrive with this one.
Koha internal server error: finding the line that caused it
A 500 page is Koha telling you nothing on purpose. The real message is in that instance's error log — here is which file to read, and the two causes that produce most of them.
Rebuilding the Zebra index when Koha search results go stale
A record you can open by its number but cannot find by searching means the index is behind, not that the record is missing. Here is how to rebuild it properly.
Backing up Koha with koha-dump — and restoring it
A package install already backs itself up nightly, keeps two days, and writes to a disk that dies with the server. Here is how to check it, and how to restore.
Koha cron jobs: which ones matter, and what breaks silently without each
A package install schedules about fifteen jobs. This is what each one does, when it runs, and the exact symptom a library sees when it stops.