Inbox Architecture & Technical Specs
AI spam detection, Gmail-like search, rules engine, and email drafting.
1. AI-Powered Spam Detection & Drafting
| Score Range | Label | Action |
|---|---|---|
| 0-30 | safe | Deliver to inbox |
| 31-70 | suspicious | Deliver with warning banner |
| 71-100 | spam | Route to spam folder |
2. Gmail-Like Search
| Operator | Description | Example |
|---|---|---|
| `from:` | Sender email contains | `from:boss@company.com` |
| `to:` | Recipient email contains | `to:support@company.com` |
| `subject:` | Subject contains | `subject:invoice` |
| `has:attachment` | Has attachments | `has:attachment` |
| `is:starred` | Starred conversations | `is:starred` |
| `is:unread` | Unread conversations | `is:unread` |
| `is:pinned` | Pinned conversations | `is:pinned` |
| `is:muted` | Muted conversations | `is:muted` |
| `before:` | Before date | `before:2026-04-01` |
| `after:` | After date | `after:2026-03-01` |
| `label:` | Has tag/label | `label:finance` |
| `in:sent` | In sent folder | `in:sent` |
| `in:drafts` | In drafts folder | `in:drafts` |
| `in:archive` | In archive | `in:archive` |
| `in:trash` | In trash | `in:trash` |
| Query | What it matches | |
| ---------------------------------------- | --------------------------------------------------- | |
| `from:boss@company.com` | Messages from that sender | |
| `subject:invoice has:attachment` | Invoices with attachments | |
| `is:unread from:client after:2026-04-01` | Unread messages from "client," sent after April 1st | |
| `quarterly report is:starred` | Starred conversations matching "quarterly report" | |
3. Smart Rules Engine
| Operator | Use Case | Example | |
|---|---|---|---|
| `contains` | General match | from contains "@acme.com" | |
| `equals` | Exact match | subject equals "Invoice" | |
| `starts_with` | Prefix | subject starts_with "RE:" | |
| `ends_with` | Suffix | from ends_with "@vendor.com" | |
| `not_contains` | Exclude | body not_contains "unsubscribe" | |
| Action | Effect | ||
| ---------------- | ------------------------------- | ||
| `move_to_folder` | Files the message into a folder | ||
| `mark_read` | Marks the message read | ||
| `star` | Stars the conversation | ||
| `delete` | Deletes the message | ||
| `forward_to` | Forwards to another address | ||
| Rule Name | Conditions | Actions | Priority |
| -------------- | ------------------------------ | ------------------------ | -------- |
| VIP Customer | from contains "enterprise.com" | star, move_to_folder:VIP | 1 |
| Invoice Filing | subject contains "invoice" | move_to_folder:Finance | 2 |
| Spam Suspect | from contains "noreply" | delete | 1 |
4. Outbound Delivery
Outgoing mail goes through a queue that renders templates, tracks delivery, and retries on transient failure.
Sending an email (API):
bash
POST /inbox/messages/send
{
"accountId": "acct-xxx",
"to": ["client@company.com"],
"subject": "Meeting Request",
"body": "Hi,\n\nI would like to schedule a meeting to discuss the quarterly results."
}
Response:
json
{
"data": {
"id": "msg-xxx",
"direction": "outbound",
"subject": "Meeting Request",
"folder": "DRAFTS"
}
}
The message is queued for delivery and its status updates to sent once the outbound worker dispatches it. Passing a future scheduledFor timestamp holds the send until that time instead of dispatching immediately.
Templates: stored with {{variable}} placeholders (e.g. {{customerName}}, {{orderId}}) that get filled in at send time.
5. Conversation Threading
Messages are grouped into conversations by thread, ordered oldest-to-newest, with participant tracking and status kept in sync across the whole thread.
Get a conversation with its messages (API):
bash
GET /inbox/threads/{conversationId}
Response:
json
{
"id": "conv-xxx",
"subject": "Q2 Project Update",
"status": "open",
"messages": [
{
"id": "msg-001",
"from": { "name": "Client", "email": "client@acme.com" },
"subject": "Q2 Project Update",
"textBody": "Hi,\n\nHere are the updates for Q2...",
"attachments": [],
"createdAt": "2026-05-10T14:00:00Z"
}
]
}
A conversation carries subject, participants, tags, priority (low / medium / high), status (open / closed / snoozed / archived / trash / sent / draft), an assignee, and read/star/pin/mute flags — everything a shared-inbox team needs to coordinate without stepping on each other.
1. **Spam check** — the message is scored 0-100. Above the spam threshold, it's routed straight to the spam folder and tagged with its score; below it, processing continues.
2. **Rules evaluation** — enabled rules run in priority order against the message, applying folder moves, star/delete, mark-read, or forwarding.
3. **Notification** — the assigned owner (or conversation owner) is notified through their configured channels (push / email / in-app).
```
from:"john smith@company.com" → exact sender match, quotes preserved
is:unread from:client subject:report after:2026-04-01 → all operators combine
quarterly report is:starred from:boss → free text + operators together
before:2026-04-01 after:2026-01-01 → date range
```
```
priority 1: Spam Suspect (delete)
priority 2: VIP Customer (star, move_to_folder:VIP)
priority 3: Invoice Filing (move_to_folder:Finance)
# Evaluation order: Spam Suspect → VIP Customer → Invoice Filing
# Disabling a rule (enabled: false) removes it from evaluation
# without deleting its configuration.
```
Outbound sends that fail transiently (network blip, provider rate-limit) are retried automatically with exponential backoff. If every retry is exhausted, the message is marked failed and the failure reason is recorded on the delivery record — nothing fails silently.