# Zimphony Webmail

Installable white-label webmail product built for organizations that already run Zimbra:

- Every package uses Zimbra Mail and Zimbra Contacts for the core `Mail` and `Contacts` features; end-user UI keeps those labels vendor-neutral.

- Backend: Python FastAPI, Zimbra SOAP API over `httpx`
- Frontend: Next.js, Tailwind CSS, TanStack Query
- UX: optimistic delete/move, drag email into folders, drag attachments into compose
- Editions: Mail Only, Mail + Google add-on, Mail + Native-Zimbra add-on
- Google-Connect includes Mail, Contacts, Google Calendar, Google Tasks, and Google Drive.

The customer-facing product path is webmail-first and on-prem. SaaS remains a
future deployment mode in the same codebase.

## Project Structure

```text
backend/
  app/
    main.py
    zimbra_service.py
    calendar_service.py
frontend/
  app/
  components/
  lib/
```

## Local Backend

```powershell
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
uvicorn app.main:app --reload
```

The login form accepts a mailbox account and talks to the customer's Zimbra through `/service/soap`.

## Local Frontend

```powershell
cd frontend
npm install
Copy-Item .env.example .env.local
npm run dev
```

Open `http://localhost:3000`.

## Docker

The repository still supports the existing `systemd` deployment on this machine.
For customer installs, the packaged Docker bundles live under `deploy/docker/`
and are split into three editions:

- `mail-only`
- `mail-google`
- `mail-native-zimbra`

Create env files first:

```powershell
Copy-Item backend\.env.example backend\.env
Copy-Item frontend\.env.example frontend\.env.local
```

Then run:

```powershell
docker compose up --build
```

Open `http://localhost:3000`.

For the packaged edition bundles, see:

- [deploy/docker/README.md](deploy/docker/README.md)
- [docs/docker-deployment-guide.md](docs/docker-deployment-guide.md)
- [docs/customer-vm-installation.md](docs/customer-vm-installation.md)
- [docs/customer-admin.md](docs/customer-admin.md)

The fastest customer install path is the edition-specific Docker wizard,
which writes env files and starts the stack in one step. The backend Docker
image includes `imapsync`, so migration is available in the Docker packages
too.

For a cleaner customer handoff, the Docker pack includes one script per
edition:

- `deploy/docker/install-e1.sh`
- `deploy/docker/install-e2.sh`
- `deploy/docker/install-e3.sh`

For internal release builds, use:

- `deploy/docker/package-e1.sh`
- `deploy/docker/package-e2.sh`
- `deploy/docker/package-e3.sh`

## Linux Server Deployment

This repo now includes native Linux deployment helpers:

- [start-backend.sh](start-backend.sh)
- [start-frontend.sh](start-frontend.sh)
- [start-all.sh](start-all.sh)
- [start-public.sh](start-public.sh)
- [stop-all.sh](stop-all.sh)
- [restart-local.sh](restart-local.sh)
- [status-local.sh](status-local.sh)
- [deploy/linux/README.md](deploy/linux/README.md)
- [deploy/linux/zimphony-backend.service](deploy/linux/zimphony-backend.service)
- [deploy/linux/zimphony-frontend.service](deploy/linux/zimphony-frontend.service)
- [deploy/linux/zimphony.nginx.conf](deploy/linux/zimphony.nginx.conf)
- [deploy/linux/setup-nginx.sh](deploy/linux/setup-nginx.sh)
- [deploy/linux/issue-wildcard-cert.sh](deploy/linux/issue-wildcard-cert.sh)
- [deploy/linux/deploy-local.sh](deploy/linux/deploy-local.sh)

The Linux guide covers:

- backend virtualenv setup
- frontend production build
- `systemd` services
- Nginx reverse proxy
- Google OAuth redirect URI changes for production domains
- `PRODUCT_EDITION` selection for `mail_only`, `mail_google`, or `mail_native_zimbra`

For a public pilot on a VM with an existing public IP, use `./start-public.sh` to run the frontend and backend on public ports without needing `localhost`.

Recommended production host split for the customer bundle:

- `<webmail-host>` for the white-label webmail app
- `<platform-admin-email>` for whoever operates the install on that server

The on-prem customer package is webmail-first. Customer-facing admin surfaces stay out of the bundle; SaaS remains a future deployment mode in the same codebase.

For customer tenants, the same pattern applies as `mail.<customer-domain>` after their domain is onboarded. If that host only redirects into the canonical webmail host, it does not need its own SSL certificate.

## Product Editions

See [docs/product-editions.md](docs/product-editions.md) for the installable product plan, edition split, and provider boundaries.

## Notes

## Implemented Mail Actions

- Login against Zimbra with `AuthRequest`
- List folders and messages with Zimbra SOAP
- Read message detail in a sandboxed iframe
- Send mail through `SendMsgRequest`
- Send attachments from the compose dialog
- Delete messages with optimistic UI and rollback on failure
- Move messages by dragging them onto folders, with optimistic UI
- Mark read/unread and star/unstar with optimistic UI

## Production Notes

This is a real Zimbra SOAP webmail foundation, but production deployment should add persistent encrypted credential storage, CSRF protection, attachment streaming/download endpoints, background sync, durable session storage such as Redis, rate limiting, audit logging, and stricter HTML sanitization for message rendering.
