What happens when you receive an email?
This article describes the complete journey of an inbound email — from the moment a remote mail server connects to Cleanbox, through spam analysis and rule evaluation, to final delivery or rejection.
Architecture overview
Inbound email is handled by two systems working together:
- Node.js SMTP server — Accepts SMTP connections, orchestrates the processing pipeline, handles IMAP delivery and SMTP forwarding
- PHP backend (Symfony) — Provides business logic via HTTP endpoints for address validation, spam evaluation, and message storage
Two external services assist during processing:
- Rspamd — Spam scanning with Bayes classifier and custom Cleanbox symbols
- ClamAV — Virus scanning (relay addresses only)
Phase 1: SMTP connection — recipient validation
When a remote mail server connects to deliver an email, the first thing Cleanbox does is validate the recipient address (during the SMTP RCPT TO command).
The backend checks:
- Address exists — Is this a valid alias or relay address in Cleanbox?
- Address is active — Is the alias enabled (not toggled off)?
- Mailbox is active — Is the connected mailbox reachable?
- Weekly quota — Has the team exceeded their weekly email limit?
If any check fails, the sending server receives an SMTP error code and the connection is dropped. No email data is transferred.
Phase 2: Email data — spam analysis
Once the recipient is validated, the sending server transmits the full email. Cleanbox then runs multiple analyses:
Step 1: Parse the email
The raw email is parsed to extract sender address, sender name, subject, body text, and message properties (newsletter headers, attachments, calendar invites, etc.).
Step 2: Check sender reputation
The sender address and domain are checked against the crowd-sourced reputation database. The result (accept, greylist, quarantine, or block) is passed to Rspamd as context.
Step 3: Rspamd spam scan
The full email is sent to Rspamd for content analysis. Rspamd checks authentication (SPF, DKIM, DMARC), analyzes URLs, evaluates content with its Bayes classifier, and applies the Cleanbox reputation symbols. The result is a numerical spam score and a detailed report of every rule that triggered.
Step 4: ClamAV virus scan (relay only)
If the recipient is a relay address with virus scanning enabled, the email is scanned for malware by ClamAV. If a virus is found, the email is rejected immediately in the next phase.
Phase 3: Evaluation — the decision chain
With all analysis complete, Cleanbox evaluates the email against your personal rules. The checks run in strict priority order — the first match wins:
| # | Check | Result if triggered | Status |
|---|---|---|---|
| 1 | Virus detected | Reject immediately | rejected |
| 2 | Contact blocked | Deny | denied |
| 3 | Shield: Gatekeeper | Sender not on approved list → deny | denied |
| 4 | Shield: Rate limiter | Contact exceeded rate limit → deny | denied |
| 5 | Spam threshold | Score above reject threshold → reject | rejected |
| 6 | Quarantine threshold | Score above quarantine threshold → flag for quarantine | (flagged) |
| 7 | Filter rules (deny) | Matching filter with deny action → deny | denied |
| 8 | Filter rules (allow) | Matching filter with allow action → apply delivery options | — |
| 9 | Contact state | Apply muted (mark read) or prioritized (flag important) | — |
| 10 | Quarantine intercept | If flagged in step 6 → quarantine | quarantined |
| 11 | Shield: Snoozer | Outside delivery window → hold | snoozed |
| 12 | Default | No rule matched → deliver | delivered |
How contact states affect the chain
The sender contact state changes which checks are applied:
| State | Skips | Effect |
|---|---|---|
| Blocked | Everything after step 2 | Denied immediately, no cloud storage |
| Whitelisted | Gatekeeper, Limiter, Spam check | Full trust — immediate delivery (filters still apply) |
| Prioritized | Snoozer | Delivered with \Flagged IMAP flag, immediate delivery |
| Muted | — | Delivered with \Seen IMAP flag (marked as read) |
| Unset | — | All checks apply normally |
Phase 4: Delivery
Based on the evaluation result, one of the following happens:
Aliases (IMAP delivery)
Clean messages are delivered to your connected mailbox via IMAP. Cleanbox appends the email to your configured destination folder with the appropriate IMAP flags (\Seen for muted, \Flagged for prioritized, or as specified by filter options).
Relay addresses (SMTP forwarding)
Clean messages are forwarded via SMTP to your mail server. The envelope sender is rewritten using SRS (Sender Rewriting Scheme) to ensure SPF authentication passes at the destination. A validation header (X-Cleanbox-Validation) is added for bypass prevention.
If SMTP forwarding fails, the message is queued for automatic retry with exponential backoff (up to ~4 days before marking as failed).
Phase 5: Storage
Regardless of the outcome, every processed email is stored:
- Message metadata — sender, subject, status, spam score, spam report, virus result, matched filter, delivery options — stored in the database
- Raw email — the full RFC822 message (with injected Cleanbox headers) is uploaded to encrypted cloud storage
- Contact update — the sender Contact entity is created or updated (name history, email count, last seen, category)
- Usage counter — the team weekly email counter is incremented (for delivered messages)
Injected headers
Before storage, Cleanbox adds these headers to the email:
X-Cleanbox-Id— unique message identifierX-Cleanbox-Spamscore— the calculated spam scoreX-Cleanbox-Virusscan— SAFE, INFECTED, or UNSCANNEDAuthentication-Results— SPF, DKIM, DMARC results (relay addresses only)
Forwarding (filter option)
If a matching allow-filter has the forward_to option configured, the message is also sent via SMTP to each specified forward address — in addition to normal delivery. The forwarded copy includes a Reply-To header pointing to the original sender.
