CeyMail exposes server metrics in Prometheus exposition format, letting you build custom Grafana dashboards for your mail infrastructure.
Prometheus metrics export is available on the Business plan and above.
Setup
1. Generate a token
Go to Settings > Security > Prometheus Metrics and click Generate Token. Copy the token immediately — it is only shown once.
2. Configure Prometheus
Add CeyMail as a scrape target in your prometheus.yml:
scrape_configs:
- job_name: ceymail
scheme: https
metrics_path: /api/stats/metrics
scrape_interval: 30s
static_configs:
- targets: ['your-server.com']
bearer_token: 'your-token-here'
Replace your-server.com with your dashboard hostname and your-token-here with the token you generated.
3. Connect Grafana
In Grafana, add your Prometheus instance as a data source, then build dashboards using the CeyMail metrics listed below.
Available metrics
System
| Metric | Type | Description |
|---|---|---|
ceymail_cpu_idle_jiffies |
counter | CPU idle time (use rate() to compute usage) |
ceymail_cpu_total_jiffies |
counter | Total CPU time (use rate() to compute usage) |
ceymail_memory_used_bytes |
gauge | Memory currently in use |
ceymail_memory_total_bytes |
gauge | Total system memory |
ceymail_disk_used_bytes |
gauge | Disk space used on root partition |
ceymail_disk_total_bytes |
gauge | Total disk space |
Mail queue
| Metric | Type | Description |
|---|---|---|
ceymail_queue_active |
gauge | Messages being delivered |
ceymail_queue_deferred |
gauge | Messages waiting to retry |
ceymail_queue_bounce |
gauge | Permanent delivery failures |
ceymail_queue_hold |
gauge | Manually held messages |
Services
| Metric | Type | Description |
|---|---|---|
ceymail_service_up{name="..."} |
gauge | 1 if running, 0 if down |
Monitored services include Postfix, Dovecot, OpenDKIM, MariaDB, SpamAssassin, Nginx/Apache, Unbound, Rsyslog, Fail2ban, and the CeyMail AI Filter (if enabled).
Counts
| Metric | Type | Description |
|---|---|---|
ceymail_domains_total |
gauge | Number of configured mail domains |
ceymail_mailboxes_total |
gauge | Number of mailbox accounts |
ceymail_aliases_total |
gauge | Number of email aliases |
Grafana dashboard examples
CPU usage
To calculate real-time CPU usage percentage from the counter metrics:
100 - (rate(ceymail_cpu_idle_jiffies[5m]) / rate(ceymail_cpu_total_jiffies[5m]) * 100)
Memory usage percentage
ceymail_memory_used_bytes / ceymail_memory_total_bytes * 100
Disk usage percentage
ceymail_disk_used_bytes / ceymail_disk_total_bytes * 100
Service status panel
Use ceymail_service_up with a stat or table panel. Alert when any value drops to 0:
ceymail_service_up == 0
Mail queue depth
ceymail_queue_active + ceymail_queue_deferred + ceymail_queue_bounce + ceymail_queue_hold
Token management
- One active token at a time — generating a new token revokes the previous one
- Revoke anytime from Settings > Security > Prometheus Metrics
- Last used timestamp shows when Prometheus last scraped successfully
- Tokens are stored as SHA-256 hashes — the plaintext is never saved
Rate limits
The metrics endpoint allows 12 requests per minute per IP. Prometheus default scrape intervals (15-60 seconds) fit well within this limit.