AI Email Screening
Screen inbound and outbound email for spam and threats using cloud-based Gemini AI or a local Ollama model.
AI Email Screening adds an intelligent filtering layer to your mail server. Emails are scored by an AI model and classified as ham (legitimate), suspicious, or spam. You can choose to reject, tag, or quarantine detected spam, and maintain allow/block lists for manual overrides.
Pro feature
AI Email Screening is available on the Pro plan and above.
Screening modes
CeyMail supports two screening backends. Choose the one that fits your environment:
| Mode | Backend | Requirements |
|---|---|---|
| Cloud | Google Gemini API | Gemini API key (configured in Settings > AI) |
| Local | Ollama with DistilBERT | Minimum 2 GB system RAM |
Cloud mode
Cloud mode sends email content to the Gemini API for classification. It uses minimal server resources and is the recommended option for most setups. You need a Gemini API key -- enter it in Settings > AI or directly on the Screening settings tab.
Local mode
Local mode runs a DistilBERT model on your server via Ollama. No email content leaves your server, making it suitable for privacy-sensitive environments. When you enable local mode for the first time, CeyMail downloads and installs the model automatically (approximately 64 MB).
RAM requirement
Local mode requires at least 2 GB of total system RAM. The dashboard checks your server's available memory and warns you if it's insufficient.
Configuration
Navigate to the AI Screening page and open the Settings tab to configure:
| Setting | Default | Description |
|---|---|---|
| Spam threshold | 75 | Score at or above this value is classified as spam (0--100) |
| Suspicious threshold | 50 | Score at or above this value is classified as suspicious (0--100) |
| Action on spam | Reject | What to do with spam: reject (bounce back), tag (add headers, deliver anyway), or quarantine (hold for review) |
| Max body characters | 4,000 | How much of the email body to send to the AI model (500--15,000) |
| Screen outbound | On | Whether to also screen outgoing emails |
The suspicious threshold must be lower than the spam threshold. Emails scoring between the two thresholds are flagged as suspicious but not actioned.
Screening logs
The Screening Logs tab shows every email that was screened. The table columns are:
- Time -- when the email was processed
- Sender and Subject -- who sent the email and what it's about
- Score -- the AI confidence score (0--100)
- Classification -- ham, suspicious, or spam
- Action taken -- accepted, tagged, rejected, or tempfail
Click the expand arrow on any row to see additional details including direction (inbound, outbound, or internal) and the AI's reasoning.
Use the filters to narrow down by classification, action, or direction. The search bar searches across sender, subject, and reason fields.
Allow and block lists
The Allow/Block Lists tab lets you override AI decisions for specific senders:
- Allow list -- emails from these addresses or domains bypass screening entirely
- Block list -- emails from these addresses or domains are always rejected
Adding an entry
- Click Add Entry
- Choose Allow or Block
- Choose Email (specific address) or Domain (all addresses at that domain)
- Enter the value
- Optionally add a note explaining why
- Click Add
Entries take effect immediately. Duplicates are not allowed -- if an entry already exists, you'll see an error.
How screening works
When screening is enabled, CeyMail inserts an AI milter into the Postfix mail processing chain. Each incoming (and optionally outgoing) email passes through the milter, which:
- Checks the sender against allow/block lists
- If not listed, sends the email content to the configured AI backend
- Receives a spam score and classification
- Applies the configured action (reject, tag, or quarantine)
- Logs the result
The milter runs as a systemd service (ceymail-ai-filter) and integrates with Postfix alongside OpenDKIM and SpamAssassin.
Overview statistics
The Overview section at the top of the Screening page shows:
- Total Screened -- all-time count of emails processed
- Accepted -- emails that passed screening
- Tagged -- emails that were tagged as suspicious/spam but delivered
- Rejected -- emails that were bounced
- Average Score -- the mean spam score across all screened emails
- Screened Today and Rejected Today -- current day counts
- 24-Hour Activity -- a chart showing screening activity over the past 24 hours