# Email Logger UI — Specification

This document defines the **emailloggerui** web application: layout, views, API usage, mailbox settings, and compose behavior.

Backend specification: [`../../crmapi/innerdoc/EMAIL_LOGGER_SPEC.md`](../../crmapi/innerdoc/EMAIL_LOGGER_SPEC.md)

End-to-end overview: [`SYSTEM_OVERVIEW.md`](SYSTEM_OVERVIEW.md)

---

## 1. Purpose

**emailloggerui** is a read-only email browser for logged company mail. It does **not** send mail or replace Outlook/Gmail — it displays messages captured by the backend IMAP poller and links them to CRM Actions when contacts match.

Users can:

- Browse **Inbox** and **Sent**
- Switch to **Conversations** view (grouped by contact / counterparty)
- Search and filter logged mail
- Configure company **IMAP mailboxes** for the cron fetcher
- **Refresh inbox** manually (trigger fetch for selected mailbox)
- **Compose email** via the user’s **local email client** (not in-app)

---

## 2. UI mockups

### Inbox view (folder list + message preview)

![Inbox view](ui/emaillogger_inbox_view.png)

- Left sidebar: folder navigation
- Center: message list (subject, sender, date)
- Right: selected message preview
- Top: search, filter, Refresh inbox, Compose email

### Conversation view (grouped by contact)

![Conversation view](ui/emaillogger_conversation_view.png)

- Left sidebar: **Conversations** selected
- Center: list of contacts / counterparties (name, last subject, date)
- Right: full thread with one counterparty
- **CLIENT** badge when counterparty matches a CRM contact (`typename = client`)

---

## 3. App structure

### 3.1 Files (to be implemented)

| File | Purpose |
|------|---------|
| `EmailLogger.html` | Single-page shell, three-pane layout |
| `EmailLogger.css` | Module-specific styles |
| `EmailLogger.js` | Logic, API calls, view switching |

Shared dependencies (same as [`whatsapploggerui`](../../whatsapploggerui/) and [`banksui`](../../banksui/)):

- [`../../crmui/css/base.css`](../../crmui/css/base.css)
- [`../../crmui/js/Common.js`](../../crmui/js/Common.js) — `apipost`, `apikeyin`, `saveapikey`, `toggletheme`
- jQuery 3.x

### 3.2 URL

Example: `http://localhost/WebSite/emailloggerui/EmailLogger.html`

API base: `http://localhost/WebSite/crmapi/EmailLogger.php`

---

## 4. Layout

```
┌─────────────────────────────────────────────────────────────────────────┐
│  Messages          [ Search........................... ]  [Compose email]│
├─────────────────────────────────────────────────────────────────────────┤
│  [Email]  [search box]  [Filter ▼]                    [Refresh inbox]    │
├──────────┬──────────────────────────┬───────────────────────────────────┤
│ Sidebar  │  Message / conversation │  Preview pane                    │
│          │  list                     │                                  │
│ Inbox    │  Subject line             │  FOLDER: INBOX                   │
│ Drafts   │  Sender · date            │  — or —                          │
│ Outbox   │  ...                      │  CONVERSATION WITH {name}        │
│ Sent     │                           │  [CLIENT] badge if CRM match     │
│──────────│                           │  Subject, date, body             │
│Conversat.│                           │                                  │
│          │                           │                                  │
│  ⚙       │                           │                                  │
└──────────┴──────────────────────────┴───────────────────────────────────┘
```

### 4.1 Top header

| Element | Behavior |
|---------|----------|
| **Messages** + home icon | Title; optional return to default folder |
| **Global search** | Filters current view (`showlist` or `listconversations` with `search`) |
| **Compose email** | Opens external client — see §8 |
| **Email** chip | Active module indicator (future: multi-channel apps) |
| **Filter** | Date range, mailbox account, sync status |
| **Refresh inbox** | `fetchaccount` for selected mailbox; show loading toast |

### 4.2 Left sidebar

| Item | View mode | API |
|------|-----------|-----|
| Inbox | Folder | `showlist` + `folder=inbox` |
| Sent | Folder | `folder=sent` |
| Conversations | Thread | `listconversations` |
| ⚙ Settings | Settings panel | Mailbox CRUD |

Drafts and Outbox are not used — backend only polls Inbox and Sent from IMAP.

Highlight active item (purple accent per mockup).

### 4.3 Center pane

**Folder mode:** vertical list of emails

- Each row: **subject** (bold), **sender name · date/time**
- Click row → load preview in right pane (`get` or use row data)

**Conversation mode:** vertical list of counterparties

- Each row: **contact/name**, **last subject preview**, **date**
- Click row → load thread in right pane (`getconversation`)

### 4.4 Right pane

**Folder mode header:** `FOLDER: INBOX` (or SENT, etc.)

**Conversation mode header:** `CONVERSATION WITH {counterpartyname}`

Message display:

- Entity badge: `CLIENT`, `LEAD`, `VENDOR` from CRM `typename` when matched
- Date/time
- Subject (bold)
- Body: prefer `bodyhtml` sanitized display; fallback `bodytext`
- Metadata footer (optional): sync status, action id, message id

Empty state: *Select a message or compose a new email.*

---

## 5. Login

Same pattern as [`whatsapploggerui/WhatsAppLogger.html`](../../whatsapploggerui/WhatsAppLogger.html):

1. Show login card with API key field.
2. On Connect: `saveapikey()` → validate with `listaccounts`.
3. On success: load mailbox selector, default to Inbox, `showlist`.

Error: *Invalid API key or Email Logger API unavailable.*

---

## 6. API integration

All calls via `apipost(emailloggerapi, obj, callback)` with `X-API-Key` header.

### 6.1 Commands used by UI

| UI action | command | Key parameters |
|-----------|---------|----------------|
| Validate login | `listaccounts` | — |
| Load folder list | `showlist` | `folder`, `emailaccountid`, `search`, `datefrom`, `dateto`, `limit` |
| Preview one email | `get` | `id` |
| Conversation list | `listconversations` | `emailaccountid`, `search`, `limit` |
| Conversation thread | `getconversation` | `counterpartyemail`, `emailaccountid` |
| Dashboard counts | `stats` | `emailaccountid` |
| Refresh inbox | `fetchaccount` | `emailaccountid` |
| Settings list | `listaccounts` | — |
| Add mailbox | `add` | IMAP fields |
| Update mailbox | `update` | `id` + fields |
| Delete mailbox | `delete` | `id` |
| Test IMAP | `testconnection` | IMAP fields |

### 6.2 Mailbox selector

Dropdown at top of toolbar (like WhatsApp Logger phone filter):

- Populated from `listaccounts`
- Label: `{label} ({emailaddress})`
- Option “All mailboxes” with empty value
- Changing selection reloads current view

---

## 7. Settings panel (mailbox setup)

Opened via ⚙ in sidebar.

### 7.1 List view

Show all `EmailAccounts` for tenant:

- Email address, label, IMAP host
- Last checked, status (ok/error)
- Edit / Delete buttons

### 7.2 Add / Edit form

| Field | Required | Notes |
|-------|----------|-------|
| Email address | Yes | Company mailbox |
| Label | No | Display name |
| IMAP host | Yes | |
| IMAP port | Yes | Default 993 |
| Encryption | Yes | ssl / tls / none |
| Username | Yes | |
| Password | Yes on add | Optional on update (leave blank to keep) |
| Inbox folder | No | Default INBOX |
| Sent folder | No | Default Sent |
| Drafts folder | No | Default Drafts |
| Outbox folder | No | Optional |

Buttons:

- **Test connection** → `testconnection` (no save required if passing form values)
- **Save** → `add` or `update`
- **Back** → return to previous view

Password field: type password; never display stored password on edit.

---

## 8. Compose email (external only)

The **Compose email** button does **not** open an in-app composer.

### 8.1 Default behavior: mailto

```javascript
window.location.href = 'mailto:' + encodeURIComponent(toAddress);
```

- From folder view with no selection: `mailto:` (blank compose)
- From conversation view: pre-fill `to` with `counterpartyemail`

### 8.2 Optional: web compose URL

Store in `localStorage` key `emaillogger_composeurl`:

- Example: `https://outlook.office.com/mail/deeplink/compose?to={to}`
- Placeholder `{to}` replaced with counterparty email
- Settings → “Compose URL (optional)” field

### 8.3 Not in v1

- Rich text editor
- Send via SMTP from browser
- Draft creation in emailloggerui

---

## 9. Read-only policy

- No delete email from logger UI
- No edit subject/body
- No mark read/unread on IMAP server
- No move between folders on server

Logged mail reflects what the backend captured; server state is unchanged by this app.

---

## 10. JavaScript module pattern

Follow [`whatsapploggerui/WhatsAppLogger.js`](../../whatsapploggerui/WhatsAppLogger.js) and project `.cursorrules`:

```javascript
emaillogger = new EmailLogger();
emaillogger.setup();

function EmailLogger() {
	this.setup = setup;
	this.validatekey = validatekey;
	this.loadfolder = loadfolder;
	this.loadconversations = loadconversations;
	this.openmessage = openmessage;
	this.openconversation = openconversation;
	this.refreshinbox = refreshinbox;
	this.composeemail = composeemail;
	this.opensettings = opensettings;
	// ...
}
```

- Lowercase function names
- Full if/else blocks (no early return from function for flow control)
- Explicit variable steps (no chained ternary one-liners)
- `$.post` / `apipost` for API calls

---

## 11. Styling notes

Match mockups:

- White/light gray background, purple accent (`#7c3aed` or CRM theme primary)
- Rounded search bar and buttons
- Three-column flex/grid layout
- Responsive: on narrow screens stack sidebar behind menu toggle (future)

Reuse CSS variables from `base.css` where possible (`--border-color`, `--surface`, `--muted`).

Conversation thread: stack messages vertically with subtle separators (chat-style within email content).

---

## 12. Actions backfill (Actions app — not this UI)

Missed Action registration is recovered from **actionsui** settings, not emailloggerui:

1. Open Actions → ⚙ Settings
2. Click **Check on Email Logger**
3. Calls `Actions.php` → `command=syncemaillogger`, `days=60`
4. Toast shows `{ total, synced, skipped, errors }`

See [`SYSTEM_OVERVIEW.md`](SYSTEM_OVERVIEW.md) §8.

---

## 13. Failure modes (UI)

| Symptom | Check |
|---------|--------|
| Empty inbox | Mailboxes configured? Cron running? Try Refresh inbox |
| Refresh fails | IMAP credentials, `lastfetcherror` on account |
| No CLIENT badge | Counterparty email not in CRM Contacts |
| Conversation empty | `counterpartyemail` normalized mismatch |
| Login fails | API key, `$EmailLogger = 'yes'`, tables exist |

---

## 14. Related documentation

| Document | Location |
|----------|----------|
| Backend spec | [`../../crmapi/innerdoc/EMAIL_LOGGER_SPEC.md`](../../crmapi/innerdoc/EMAIL_LOGGER_SPEC.md) |
| Schema SQL | [`../../crmapi/innerdoc/emaillogger_schema.sql`](../../crmapi/innerdoc/emaillogger_schema.sql) |
| System overview | [`SYSTEM_OVERVIEW.md`](SYSTEM_OVERVIEW.md) |
| WhatsApp UI reference | [`../../whatsapploggerui/`](../../whatsapploggerui/) |