Mail Services Monitoring Guide

Comprehensive guide to monitoring your IMAP IDLE mail services.

Quick Status Check

One-Command Overview

mail-status

Shows:

Status of all mail services (running/failed/inactive)
When each service started
Memory usage
Recent mail activity (last 30 minutes)
Quick action commands

Example Output

=== Mail Services Status ===

✓ imapfilter (IMAP IDLE filtering) (imapfilter.service)
  Started: Mon 2026-01-14 10:23:15 CET
  Memory: 12MB

✓ goimapnotify (iCloud IDLE sync) (goimapnotify-icloud.service)
  Started: Mon 2026-01-14 10:23:18 CET
  Memory: 8MB

✓ imapfilter rules updater (timer) (imapfilter-rules-update.timer)
  Started: Mon 2026-01-14 10:23:15 CET

=== Recent Mail Activity ===

Recent mbsync activity:
  Jan 14 11:05:32 athena goimapnotify[1234]: mbsync icloud
  Jan 14 11:05:35 athena goimapnotify[1234]: mu index --quiet

Live Log Monitoring

Watch All Mail Logs

mail-logs

Follows logs from:

imapfilter.service
goimapnotify-*.service
imapfilter-rules-update.service

Press Ctrl+C to exit.

Individual Service Logs

# imapfilter only
journalctl --user -u imapfilter.service -f

# goimapnotify only
journalctl --user -u goimapnotify-icloud.service -f

# Rules updater
journalctl --user -u imapfilter-rules-update.service -f

Filter for Specific Events

# Only show mail sync events
journalctl --user -u "goimapnotify-*.service" | grep -i "mbsync\|new mail"

# Only show indexing
journalctl --user -u "goimapnotify-*.service" | grep -i "mu index"

# Only show IDLE events
journalctl --user -u imapfilter.service | grep -i "IDLE"

Connection Status

Check IMAP IDLE Connections

mail-idle-status

Shows:

Active TCP connections to IMAP servers (port 993)
Expected connections (iCloud, Gmail if configured)
Service status for each mail service

Manual Connection Check

# Show all connections to port 993 (IMAPS)
ss -tn | grep :993

# Expected output:
# ESTAB  0  0  192.168.1.100:45678  17.42.251.72:993   # iCloud
# ESTAB  0  0  192.168.1.100:45679  142.250.185.108:993 # Gmail

Testing Mail Delivery

Interactive Test

mail-test

Helps you:

Send a test email
Watch logs for delivery
Verify instant sync works

Manual Testing

# Start watching logs
journalctl --user -f -u "goimapnotify-*.service" | grep -i "new mail\|mbsync"

# In another terminal or phone, send email to yourself

# You should see within seconds:
# - "new mail detected" or similar from goimapnotify
# - "mbsync icloud" execution
# - "mu index" execution

Standard systemd Commands

Service Status

# Check if service is running
systemctl --user is-active imapfilter.service
systemctl --user is-active goimapnotify-icloud.service

# Full status with details
systemctl --user status imapfilter.service
systemctl --user status goimapnotify-icloud.service

Start/Stop/Restart

# Restart a service
systemctl --user restart imapfilter.service
systemctl --user restart goimapnotify-icloud.service

# Stop a service
systemctl --user stop imapfilter.service

# Start a service
systemctl --user start imapfilter.service

View Logs

# Last 50 lines
journalctl --user -u imapfilter.service -n 50

# Since boot
journalctl --user -u imapfilter.service -b

# Since specific time
journalctl --user -u imapfilter.service --since "1 hour ago"
journalctl --user -u imapfilter.service --since "2026-01-14 10:00"

# Follow live (like tail -f)
journalctl --user -u imapfilter.service -f

Troubleshooting

Service Not Running

Check why it failed:

systemctl --user status imapfilter.service
journalctl --user -u imapfilter.service -n 50

Common issues:

Password authentication failure → Check passage password
Network connectivity → Check internet connection
Configuration error → Check logs for syntax errors

Fix and restart:

systemctl --user restart imapfilter.service

Mail Not Arriving Instantly

1. Check IDLE connections are established:

mail-idle-status

2. Check for errors in logs:

journalctl --user -u goimapnotify-icloud.service -n 50

3. Test manually:

# Trigger manual sync
mbsync icloud
mu index

4. Verify services are running:

mail-status

Database Lock Errors

If you see “already locked” errors:

# Check if mu4e is running in Emacs
pgrep -u $UID mu

# If yes, that's expected - goimapnotify should use emacsclient
# Check goimapnotify logs to verify it's using emacsclient:
journalctl --user -u goimapnotify-icloud.service | grep -i "emacsclient\|mu index"

High Memory Usage

# Check memory usage
systemctl --user show imapfilter.service --property=MemoryCurrent
systemctl --user show goimapnotify-icloud.service --property=MemoryCurrent

# Restart if needed
systemctl --user restart imapfilter.service

Metrics to Watch

Service Uptime

# How long has the service been running?
systemctl --user show imapfilter.service --property=ActiveEnterTimestamp

Restart Count

# How many times has it restarted?
systemctl --user show imapfilter.service --property=NRestarts

Last Sync Time

# When did goimapnotify last sync?
journalctl --user -u goimapnotify-icloud.service | grep "mbsync" | tail -1

Mail Delivery Latency

To measure how fast mail arrives:

Note the time you send a test email
Watch logs: journalctl --user -f -u goimapnotify-icloud.service
Note when you see “mbsync” run
Calculate difference

Expected: < 30 seconds from send to sync

Alerting Setup

Failure Notifications

The mail-monitor.nix includes automatic failure logging:

Failures are logged to ~/.local/share/mail-service-failures.log
Check this file periodically

# View failure log
cat ~/.local/share/mail-service-failures.log

# Monitor for new failures
tail -f ~/.local/share/mail-service-failures.log

Optional: ntfy Integration

Uncomment in mail-monitor.nix to send push notifications on failure:

ExecStart = "${pkgs.ntfy-sh}/bin/ntfy publish --token $(passage show ntfy/token) topic 'Mail service %i failed'";

Daily Health Check

Run this once a day or add to your morning routine:

# Quick status check
mail-status

# Check for any failures in last 24 hours
journalctl --user -u "imapfilter.service" --since "24 hours ago" | grep -i "error\|failed" || echo "No errors"
journalctl --user -u "goimapnotify-*.service" --since "24 hours ago" | grep -i "error\|failed" || echo "No errors"

# Verify IDLE connections
mail-idle-status

Performance Benchmarks

Expected Behavior

Metric	Expected Value
Mail delivery latency	< 30 seconds
Service memory usage	8-15 MB per service
CPU usage (idle)	~0%
IMAP connections	2 (iCloud + imapfilter)
Service restarts	0 per day normally

When to Investigate

Mail takes > 1 minute to arrive
Services restart > 3 times per day
Memory usage > 50 MB
No IDLE connections shown
Errors in logs

Useful Aliases

Add to your shell config:

# Quick mail status
alias ms='mail-status'

# Watch mail logs
alias ml='mail-logs'

# Check IDLE connections
alias mi='mail-idle-status'

# Test mail delivery
alias mt='mail-test'

Integration with mu4e

Verify Emacs Integration

When mail arrives, you should see in Emacs:

Modeline updates (if configured)
New mail appears in mu4e headers view automatically

Check mu4e Update Function

In Emacs:

;; Manually trigger update (should work even with automatic updates)
M-x mu4e-update-index

;; Check update interval (should be nil)
C-h v mu4e-update-interval
;; Should show: nil

Monitoring Checklist

Run mail-status - all services green
Run mail-idle-status - connections established
Send test email - arrives within 30 seconds
Check logs - no errors in last 24 hours
Verify mu4e updates automatically
Check failure log is empty