Koha How-To

Using the Patron Emailer Plugin in Koha

In this Koha tutorial Kelly and Jessie will walk you through using the Patron Emailer Plugin. Below, you will find a video as well as the steps to install the plugin and configure and run the tool in your system.

Steps to Uploading a Plugin to your Koha System

  1. In Global System Preferences – useKohaplugins – set this system preference to allow.
  2. The location of the Patron Emailer plugin is on the Bywater Git Hub website.
  3. Go to the release page of the plugin.
  4. Download the .kpz file
  5. Back to Koha- in the Administration Module- choose Manage Plugins
  6. Choose Upload File
  7. Choose the .kpz file you downloaded from the Bywater GitHub website
  8. Once this has successfully been accomplished- now you can use the Plugin.

Using the Patron Emailer Plugin

  1. The Plugin option is found in both the Tools and Administration Module.
  2. Click Manage Plugins from the Administration Module.
  3. The Patron Emailer Plugin will be listed.
  4. There are three actions with this plugin- Run Tool, Configure, and Uninstall.
  5. This plugin takes a CSV file containing patron information, and sends emails to the patrons based on the fields in the CSV file and a template specified in the tool configuration.  
  6. Create a report (in the Koha Report Module) for this plugin to use- this report must be in a CSV file and must also have the header line which names the columns use and also must have a column titled cardnumber.  
  7. For example – your SQL report could look like this:  

SELECT cardnumber, surname, firstname, email, format(sum(a.amountoutstanding),2) AS  ‘fines’

FROM borrowers

LEFT JOIN accountlines a USING (borrowernumber)

GROUP BY a.borrowernumber

HAVING sum(a.amountoutstanding) >= <<Owe more than>>

ORDER BY surname, firstname

  1. Create and Save the report
  2. Run report and save as a CSV file
  3. Go into Tools and select Tool Plugins
  4. From the dropdown select configure
  5. The email must be configured how you want your notice to be sent.
  6. Make sure to include the column name from the report. In this case, the column name for amountoutstanding is ‘fines’

Hey [% firstname %],

A friendly reminder that you now have an outstanding bill at the library.

[% fines %]

Please call the library to resolve this issue.


Library Staff

  1. Click save configuration
  2. Once you save, you will be taken back to the main plugin screen where you can select Run tool from the actions dropdown menu
  3. Next, choose CSV file you saved from your report
  4. Click upload
  5. You will receive a message saying “ Your emails have been scheduled for delivery!”

Checking the Email Status

  1. You will not receive an error message or confirmation that a particular message was sent.
  2. These will show in the notices tab in the patron’s account on the staff client
  3. You can create a report to show you the messages that were sent

SELECT * FROM message_queue

WHERE DATE(time_queued) = CURDATE() AND subject = <<Subject>>

Questions and Answers:

Questions & Answers

Q:  What if the library wants to use this Patron Emailer for multiple emails?

A:  The Patron Emailer only currently has the functionality to have one email set up at a time.  You can copy and paste each specific version in a notepad or google doc for easy retrieval.


Q: What happens if my patron doesn’t have email?

A:  The Patron Emailer does not give you an error message if there wasn’t an email on the patron details page.  The email that it will use, is the primary email listed.  We recommend to use a report (as soon in the step by step instructions & video) for seeing the success of the report.


Q: What if some patrons don’t have card numbers?  So for example the Inter-Library Loan accounts?

A:  The key to this plugin is the card number – it is essential to have this work correctly.  You may have to put in card numbers for these account to enable this to work correctly.


Bywater Staff are always here to help your library through this process – please submit a ticket and we would be happy to help!

For more Koha Tips and Tricks – please visit this link at Bywatersolutions.com!

For more tutorial videos- visit or subscribe to our Bywater Youtube Channel!


Read more by Kelly McElligott

Tags plugin, reports, tutorial