How to Configure Email and SMTP for Koha on AWS

Overview

Koha uses SMTP to deliver all patron-facing communications: hold pickup notifications, overdue notices, account confirmation emails, password reset links, and newsletter-style notices. Without SMTP configured, these emails silently fail — Koha won’t report an error to the patron, and staff may not notice until patrons start complaining about missing notifications.

Koha 22.11 and later includes a built-in SMTP server management page under Administration → SMTP Servers. This is the easiest way to configure email and supports multiple SMTP servers if needed. Older versions (22.05 and earlier) require editing the koha-conf.xml configuration file directly.

Which email provider should I use?

For libraries running on the KohaSupport AWS Marketplace AMI, Amazon SES is the recommended choice. It integrates with your existing AWS account, has excellent deliverability, and costs a fraction of a cent per email at typical library volumes.

Method 1: Amazon SES (Recommended for AWS Deployments)

Why SES

Amazon Simple Email Service (SES) integrates directly with your AWS account, has very low cost, and delivers strong inbox placement rates. The main caveat: new SES accounts start in sandbox mode, which restricts sending to only verified email addresses. You must request production access before emails can reach real patron inboxes.

Step 1: Verify your sending email address or domain

Before SES will send any email on your behalf, it must confirm you own the address or domain.

1. Open the AWS SES Console and select your region (use the same region as your EC2 instance — typically us-east-1).
2. Go to Verified identities → Create identity.
3. Choose one of:
   • Email address — verify a single address (e.g., [email protected]). SES sends a confirmation link to that address; click it to verify. Simpler to set up, but limits you to one sender address.
   • Domain — verify your entire domain (e.g., yourdomain.com). SES provides DNS records (CNAME entries) to add to your domain’s DNS. Once propagated, any address at that domain can send. Better deliverability and recommended for production libraries.

For domain verification, add the CNAME records shown in the SES console to your DNS provider. Verification typically propagates within a few minutes to an hour.

Step 2: Request production access (exit sandbox)

In sandbox mode, SES can only send to other verified addresses — not to arbitrary patron email addresses. For a real library deployment, you must exit sandbox mode.

1. In the SES Console, go to Account dashboard.
2. In the “Production access” section, click Request production access.
3. Fill out the request form:
   • Email type: Transactional
   • Website URL: your library’s website
   • Use case description: explain that you are a public library using Koha ILS to send patron hold notifications, overdue notices, and account emails
   • Expected daily volume: estimate based on your patron count (most libraries can start with a low estimate)
4. Submit. AWS typically approves within 24 hours, sometimes faster.

Until approved, test SMTP connectivity by sending test emails to your own verified address only.

Step 3: Create SMTP credentials

SES does not use your regular AWS access keys for SMTP. You must generate dedicated SMTP credentials.

1. In the SES Console, go to SMTP settings.
2. Click Create SMTP credentials.
3. SES creates an IAM user with the appropriate SES send permissions and displays the SMTP username and password.
4. Download or copy the password now — you cannot retrieve it again after closing this dialog.
5. Note the SMTP endpoint for your region. Common endpoints:
   • US East (N. Virginia): email-smtp.us-east-1.amazonaws.com
   • US West (Oregon): email-smtp.us-west-2.amazonaws.com
   • EU (Ireland): email-smtp.eu-west-1.amazonaws.com
6. The port for STARTTLS is 587.

Step 4: Configure in Koha (22.11 and later)

1. Log in to the Koha staff interface.
2. Go to Administration → SMTP Servers.

3. Click New SMTP server and fill in the following:

   Field	Value
   Name	Amazon SES
   Host	email-smtp.<your-region>.amazonaws.com
   Port	587
   SSL	STARTTLS
   Authentication	Yes
   Username	The SMTP username from SES (begins with AKIA...)
   Password	The SMTP password from SES
   Sender address	Your verified email or From address

4. Click Save.
5. Click Send test email to verify the connection. Enter an email address you can check and confirm delivery.
6. Click Set as default to make this server the active sender for all Koha notices.

Step 4 (Alternative): koha-conf.xml for Koha 22.05 and older

If your Koha version predates the SMTP Servers administration page, configure the connection in koha-conf.xml:

sudo nano /etc/koha/sites/library/koha-conf.xml

Find the <smtp_server> block (or add one) and set:

<smtp_server>
  <host>email-smtp.us-east-1.amazonaws.com</host>
  <port>587</port>
  <ssl_mode>STARTTLS</ssl_mode>
  <user_name>AKIAXXXXXXXXXXXXXXXX</user_name>
  <password>your-ses-smtp-password</password>
  <debug>0</debug>
</smtp_server>

Save the file, then restart Koha:

sudo koha-common restart
# or, if using Apache directly:
sudo service apache2 restart

Method 2: Gmail or Google Workspace

Prerequisites

You cannot use your regular Gmail account password with SMTP. Google requires an App Password — a separate 16-character password generated specifically for third-party applications. App Passwords require two-factor authentication to be enabled on the Google account first.

Generate a Gmail App Password

1. Go to myaccount.google.com and sign in with the library Gmail account.
2. Go to Security.
3. Under “How you sign in to Google,” enable 2-Step Verification if not already on (required).
4. Return to Security → 2-Step Verification → scroll to the bottom → App passwords.
5. Click Create a new app password, give it a name like Koha Library, and click Create.
6. Copy the 16-character password displayed. When entering it in Koha, enter it without spaces.

Configure in Koha (22.11+) — Administration → SMTP Servers

Save and use Send test email to verify.

Google Workspace (G Suite)

The configuration is identical to Gmail above, with the following differences:

• Username: your Workspace email address (e.g., [email protected])
• App Password: generated from your Google Workspace account at myaccount.google.com while signed in to the Workspace account

The SMTP host remains smtp.gmail.com — Workspace routes through the same Gmail infrastructure.

Gmail sending limits

Gmail free accounts are limited to 500 emails per day. Google Workspace accounts allow up to 2,000 emails per day. For libraries with large patron populations or frequent notice campaigns, consider Amazon SES or a dedicated transactional mail service to avoid hitting these limits.

Method 3: Other SMTP Providers (Mailgun, SendGrid, Zoho, etc.)

Most transactional email providers expose a standard SMTP relay interface. The configuration pattern is the same regardless of provider.

Collect the following from your provider’s dashboard (usually under “SMTP Relay,” “SMTP Settings,” or “Transactional Email”):

• SMTP Host / Server (e.g., smtp.sendgrid.net)
• Port: 587 for STARTTLS (most common), 465 for SSL/TLS, or 25 for plain (generally avoid plain)
• SSL type: STARTTLS or SSL
• SMTP Username and Password (often a generated API key used as the password)

Then in Koha Administration → SMTP Servers, create a new server entry using those values.

Most providers require you to verify a sending domain or email address before they will relay mail on your behalf — check your provider’s documentation for that step.

Configure Koha notices and system preferences

After SMTP is working, confirm Koha’s notice-related system preferences are set correctly:

1. Go to Administration → System Preferences and search for the following:

   Preference	Description	Recommended value
   KohaAdminEmailAddress	The From address Koha uses for outgoing email	Your library’s email address
   ReplyToDefault	Address patrons reply to	Same as above, or a staffed inbox
   ReturnpathDefault	Address that receives bounced/undeliverable mail	Your admin email; monitor this

2. Save preferences after updating.

Confirm cron jobs are running

Koha sends most notices via scheduled cron jobs — the SMTP connection alone is not enough. The most important jobs:

Check the current cron schedule for the Koha system user:

sudo crontab -l -u koha-library

You should see entries running these scripts on a daily or configured schedule. If the crontab is empty, cron jobs are not running and no notices will be sent regardless of SMTP configuration. Contact KohaSupport if you need assistance enabling the cron schedule.

Trigger a test notice

1. In the Koha staff interface, go to Patrons and open any patron record.
2. Go to the Notices tab for that patron.
3. Review the notice history — a sent notice confirms the full pipeline (cron → SMTP → delivery) is working.

Verify email is working

To manually trigger advance notices and see verbose output, run:

sudo -u koha-library koha-shell -c "perl /usr/share/koha/misc/cronjobs/advance_notices.pl --verbose" 2>&1 | head -50

To check for SMTP errors in the Koha error log, watch it while triggering a test:

sudo tail -f /var/log/koha/library/koha-error.log

To check pending mail in the Koha message queue from the database level, you can run:

sudo -u koha-library koha-shell -c "perl -e 'use C4::Letters; use Koha::Notice::Messages; my \$msgs = Koha::Notice::Messages->search({status => \"pending\"}); printf \"Pending: %d\\n\", \$msgs->count;'"

Or query the message_queue table directly in your Koha database to see pending, sent, and failed message statuses.

Troubleshooting

“Could not connect to SMTP server” The EC2 instance cannot reach the SMTP server on port 587. Check your EC2 Security Group’s outbound rules — all outbound traffic should be allowed (0.0.0.0/0 on all ports). AWS Marketplace instances have this open by default, but custom VPC configurations may restrict outbound traffic. Also verify the SMTP hostname is correct.

“Authentication failed” The username or password is wrong. For Gmail, ensure you are using the 16-character App Password, not your Google account password. For SES, verify you copied the SMTP password at credential creation time (not your AWS secret access key — those are different).

“Message rejected: Email address is not verified” SES is still in sandbox mode and the recipient address has not been verified. Either verify the recipient address in the SES console (for testing), or complete the production access request (Step 2 above).

“535 Authentication Credentials Invalid” (SES) The SES SMTP credentials may have been rotated or the IAM user may have been modified. Return to the SES console, go to SMTP settings, and create a new set of SMTP credentials. Update Koha’s SMTP server entry with the new credentials.

Emails not arriving in patron inboxes (but no errors) Check spam/junk folders first. For domain-verified SES senders, AWS configures DKIM automatically — confirm the DKIM records are present in your DNS. If using a single verified email address (not domain), consider upgrading to domain verification and adding an SPF record (v=spf1 include:amazonses.com ~all) to your DNS. Poor SPF/DKIM configuration is the most common cause of deliverability issues.

Koha notice crons not running Confirm the cron schedule: sudo crontab -l -u koha-library. If no jobs are listed, the cron schedule needs to be restored. On a KohaSupport AMI, the standard cron schedule is installed automatically — if it is missing, contact KohaSupport support.

Test email succeeds, but patron notices are not sent SMTP connectivity is working, but the notice pipeline has a separate issue. Check that:

• The correct SMTP server is set as default in Administration → SMTP Servers
• KohaAdminEmailAddress is set to a valid sending address
• Cron jobs are running (see above)
• The patron record has a valid email address on file

Reference

• Koha Community Manual — SMTP Servers
• Amazon SES — Getting Started
• Google — Sign in with App Passwords