Email for professionals and teams
Update readme #15
Hieu Nguyen (Jack)d600403aaa07
diff --git a/README.md b/README.mdindex 44d28e9..6dd4ca2 100644--- a/README.md+++ b/README.md@@ -1,262 +1,65 @@-+<p align="center">+ <img src="/public/icon-96.png" alt="Mailflare" width="72" />+</p>+# Mailflare-A self-hosted, AI-powered email inbox with custom domains, powered by Cloudflare+Mailflare is a self-hosted email inbox for custom domains, built on Cloudflare.[](https://deploy.workers.cloudflare.com/?url=https://github.com/hieunc229/mailflare)-+++## What you can do+- Connect domains and set up Cloudflare Email Routing from the dashboard.+- Create personal and shared mailboxes with delegated access.+- Send and receive email with attachments, rich formatting, signatures, and automatic replies.+- Organize mail with search, custom folders, stars, snoozing, archive, spam, and trash.+- Create routing rules to store, forward, reject, or categorize incoming messages.+- Get real-time inbox updates and new-message notifications.+- Import and export mail, manage contacts, and block unwanted senders.+- Manage accounts, permissions, API keys, webhooks, audit logs, and database backups.-### Roadmap+## How it works-- [x] Domain onboarding through Cloudflare, including inbound Email Routing DNS and sending DNS setup.-- [x] Domain removal cleanup for linked Cloudflare routing rules and sending subdomain resources.-- [x] Mailbox creation with automatic Cloudflare Email Routing rules.-- [x] Mailbox management with a grid view, mailbox detail page, and editable display name.-- [x] Inbox, sent, drafts, spam, and trash folders backed by a shared mail list component.-- [x] Popup composer with autosaved drafts and draft resume from the drafts folder.-- [x] Outbound send API, API keys, message read status, spam/trash moves, and seeded demo data.-- [x] Inbound and outbound attachments stored in R2 with authenticated downloads.-- [x] Real-time new-email updates and in-app notifications over WebSockets.-- [x] Search, filtering, and richer mailbox/folder counts.-- [x] Attachment support and richer compose formatting.-- [ ] Advanced routing rules for catch-all addresses, forwarding, reject/block rules, and priorities.-- [ ] Webhook management UI and delivery retry visibility.+Mailflare runs in your Cloudflare account. Email Routing delivers incoming messages to the app, while Cloudflare's email service handles outgoing messages. Your mail data stays in your own D1 database and attachments are stored in your own R2 bucket.-#### Email agent+## How much does it cost?-- [ ] Message intelligence with summaries, intent classification, urgency scoring, and extracted entities.-- [ ] Agent task queue for proposed replies, follow-ups, triage actions, and missing-information requests.-- [ ] Human-approved actions for draft replies, folder moves, forwarding, contact creation, and webhook calls.-- [ ] Agent rules for learned post-receipt policies such as prioritization, auto-triage, and reply templates.-- [ ] Agent inbox view organized by action state, including needs reply, waiting on me, waiting on them, FYI, auto-handled, and needs approval.-- [ ] Thread and contact memory for prior summaries, user preferences, relationship notes, commitments, and open loops.-- [ ] Tool execution for trusted actions such as sending email, creating drafts, updating message status, calling webhooks, and creating contacts.+You can setup Mailflare and receive email for free-## Domain API+A [Paid Worker](https://developers.cloudflare.com/workers/platform/pricing/) plan ($5/month) is required to send email (and it's recommend to have a smooth experience)-Domains are **not** dashboard-only. This app calls Cloudflare when you add/remove a domain:+## Deploy-| Action | Cloudflare API |-|--------|----------------|-| List DNS / status | `GET /zones/{zone_id}/email/routing/dns` |-| Enable inbound routing + MX/SPF/DKIM | `POST /zones/{zone_id}/email/routing/dns` |-| Disable routing | `DELETE /zones/{zone_id}/email/routing/dns` |-| Enable subdomain sending + DNS | `POST /zones/{zone_id}/email/sending/subdomains` |-| Remove subdomain sending | `DELETE /zones/{zone_id}/email/sending/subdomains/{tag}` |-| Subdomain sending DNS records | `GET .../subdomains/{tag}/dns` |+The easiest way to get started is with the **Deploy to Cloudflare** button above. You will need:-**Requirements:** Prefer `CF_TOKEN` with Zone Read + Email Routing Edit + Email Sending Edit + Email Routing Rules Write (or broader). If you use a legacy Global API Key instead, set `CF_API_KEY` and `CF_EMAIL`. The hostname must be the account's Cloudflare zone apex or a subdomain under that zone. Root-domain sending uses the Cloudflare Email Service binding, while subdomain sending can also provision the sending-subdomain DNS records. Mailbox creation creates a Cloudflare Email Routing rule that sends that address to `CF_EMAIL_WORKER_NAME`.+- A Cloudflare account.+- A domain managed by Cloudflare.+- A Cloudflare API token that Mailflare can use to configure email routing.-App routes:+After deployment, open your Mailflare URL and follow the first-run setup. The setup checks your Cloudflare configuration, creates the initial account, and helps you connect your first domain.-- `GET/POST /api/domains` — list / add (calls Cloudflare)-- `GET/DELETE /api/domains/[id]` — get / remove (disables routing & sending on CF)-- `GET /api/domains/[id]/dns` — routing + sending DNS snapshot+See the [deployment guide](docs/deployment.md) for required permissions, manual deployment, backups, updates, and custom Worker names.-## Setup+## Local development```bashcp .dev.vars.example .dev.vars-# Add CF_TOKEN and optionally CF_AID.-# For a legacy Global API Key, use CF_API_KEY + CF_EMAIL instead.-npm installnpm run db:migrate:localnpm run dev```-### Attachments--The dashboard composer accepts up to 10 attachments, with a 10 MB per-file limit and a 20 MB-combined limit. Attachment metadata is stored in D1 and file content is stored in the configured-`BUCKET` R2 binding. Apply migration `0008_add_message_attachments.sql` before using attachments.--`POST /api/v1/send` accepts optional JSON attachments:--```json-{- "from": "[email protected]",- "to": "[email protected]",- "subject": "Report",- "text": "Attached.",- "attachments": [- {- "filename": "report.pdf",- "type": "application/pdf",- "contentBase64": "<base64 data>"- }- ]-}-```--Received MIME attachments are extracted automatically. Downloads require access to the mailbox-containing the message.--### Real-time email notifications--Mailflare uses a Cloudflare Durable Object WebSocket hub to notify connected users immediately after-an inbound message is stored. The inbox and unread counts refresh without waiting for polling, and-an in-app popup links directly to the new message. Mailbox owners, the domain admin, and delegated-users receive events for mailboxes they can access.--The `REALTIME` Durable Object binding and its initial migration are declared in `wrangler.jsonc`.-Deploy with Wrangler or the Cloudflare Git integration so the Durable Object class is provisioned.-When the socket is temporarily unavailable, the client retries automatically and uses a slower-fallback refresh until the connection recovers.--Complete first-run configuration at `/setup`, or seed dev data. The first setup step checks the-required Cloudflare runtime configuration and initializes the schema when the bound D1 database is-empty. Existing databases are never migrated by the setup page; apply later migrations with the-normal Wrangler migration command.--```bash-curl -X POST http://localhost:3000/api/seed-```--## Deploy--### One-click Cloudflare deploy---[](https://deploy.workers.cloudflare.com/?url=https://github.com/hieunc229/mailflare)--Publish this repository to GitHub, then replace `hieunc229/mailflare` in the button at the top of this README with the public repository path.--The deploy flow reads `wrangler.jsonc`, provisions the Worker bindings, prompts for values from `.dev.vars.example`, runs D1 migrations, builds the OpenNext Worker, and deploys it.--Keep `wrangler.jsonc` committed. Cloudflare's deploy button uses it to detect the Worker entrypoint and required bindings. Do not commit `.dev.vars`; deploy-time secrets should be entered through Cloudflare's setup flow or set locally in `.dev.vars`.--Required setup values:--- `CF_TOKEN` — runtime scoped Cloudflare API token with Zone Read, Email Routing Edit, Email Sending Edit, and Email Routing Rules Write. This is separate from Cloudflare's deploy/build token; Cloudflare does not automatically expose the deploy token to this app.-- `CF_AID` — optional unless your token can access multiple accounts.-- `CF_EMAIL_WORKER_NAME` — must match the deployed Worker name. If the one-click deploy flow asks for a different Worker name, enter that same value here.--Activate a purchased Pro or Team key from **Admin → Licenses**. Mailflare sends the key directly to-Paymug and stores only a one-way key hash with the activation state. Without an active license,-Mailflare uses the original app name, icon, and favicon and custom branding remains unavailable.-Apply all D1 migrations before activating a license.--### Database backup workflow binding--Manual and scheduled database backups require the `DATABASE_BACKUP_WORKFLOW` binding declared in-`wrangler.jsonc`. If the backup page reports that the binding is missing, deploy the complete Worker-with `npm run deploy`; `next dev` and source-only updates may not provision new Cloudflare bindings.-The backup also requires `CF_AID` and `D1_DATABASE_ID` at runtime. It uses `D1_BACKUP_TOKEN` when-configured, otherwise it reuses `CF_TOKEN`; whichever token is used must be allowed to export the D1-database.--### Dashboard updates--The admin overview includes an **Update Mailflare** button. `POST /api/admin/update` dispatches-`.github/workflows/update.yml` in the installation repository. The workflow fetches the latest-changes from the default branch of `hieunc229/mailflare`, merges them into the installation-branch, applies pending D1 migrations, and pushes the updated source. It does not build or deploy-the Worker.--The dashboard first calls `GET /api/admin/update` and compares the running app's `package.json`-version with the target repository's version. The update button is enabled only when the target-version is newer. Checking never starts a workflow; deployment occurs only after an admin clicks-the button.--Configure these Worker runtime secrets/variables once:--- `GITHUB_UPDATE_TOKEN` — fine-grained GitHub token scoped to the installation repository with- **Actions: write** permission.-- `GITHUB_UPDATE_REF` — optional update branch; the repository default branch is used when omitted.--Configure these GitHub Actions repository secrets:--- `CLOUDFLARE_API_TOKEN` — Cloudflare token allowed to read and migrate D1.-- `CLOUDFLARE_ACCOUNT_ID` — Cloudflare account ID.-- `MAILFLARE_UPSTREAM_TOKEN` — required only when the upstream source repository is private.- Store this under the installation repository's **Settings → Secrets and variables → Actions → Repository secrets**.- For a classic PAT, enable the `repo` scope and ensure the token owner has accepted collaborator- access to the upstream repository.--If an installation already contains an older failing updater, manually copy the latest-`.github/workflows/update.yml` into that installation repository once. The updater cannot update-its own workflow until it can successfully read the upstream repository.--Optional GitHub Actions repository variables:--- `MAILFLARE_UPSTREAM_REPOSITORY` — upstream source in `owner/repository` format. Defaults to- `hieunc229/mailflare`.-- `MAILFLARE_UPSTREAM_BRANCH` — upstream branch to merge. Defaults to `main`.--The workflow resolves the `mailflare` D1 database ID at runtime and applies migrations before-pushing the updated source. If migration fails, the source is not pushed. A connected Cloudflare-Git integration may build and deploy after the successful push.--If you rename the Worker, also update related literal resource names in `wrangler.jsonc`: `name`, `services[].service` for `WORKER_SELF_REFERENCE`, `CF_EMAIL_WORKER_NAME`, and any D1/R2/Queue names you want renamed. Cloudflare service bindings require the target Worker name to exist exactly; they cannot currently reference `name` dynamically.--### Worker name and Email Routing--`CF_EMAIL_WORKER_NAME` is the Worker script name that Mailflare sends to Cloudflare's Email Routing API when creating mailbox routing rules. It must match the deployed Worker name exactly. The app now fails with a clear setup error if this variable is missing instead of silently defaulting to `mailflare`.--Cloudflare service bindings also require a literal Worker name in `wrangler.jsonc` (`services[].service`). Cloudflare's service binding configuration uses `service: "<WORKER_NAME>"`, so `WORKER_SELF_REFERENCE` cannot automatically inherit the top-level `name` field. If you rename the Worker during one-click deployment, make sure the deployed Worker name, `CF_EMAIL_WORKER_NAME`, and `services[].service` agree.--After deployment, route inbound mail to the Worker in Cloudflare Email Routing.--## Troubleshooting--### Cloudflare API 403 ... code 9109: Invalid access token--**Resolution:** The Deploy to Cloudflare flow can authenticate and deploy the Worker, but it does not create a runtime `CF_TOKEN` for Mailflare's onboarding API calls. Create `CF_TOKEN` manually from Cloudflare dashboard user API tokens and enter it as a deploy secret/variable.--Verify the token:--```bash-curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \- -H "Authorization: Bearer <CF_TOKEN>"-```--The response should include `"success": true` and `"status": "active"`. In `.dev.vars` or deploy settings, set `CF_TOKEN` to the token secret value only. Do not include the word `Bearer`, do not use the token ID, and do not put a Global API Key in `CF_TOKEN`. For a Global API Key, set both `CF_EMAIL` and `CF_API_KEY` instead.--Also check whether the token has an expiration, a `not_before` time, or client IP restrictions. If you changed deploy variables in Cloudflare, redeploy so the Worker receives the new values.--#### Cloudflare API 403 on /zones/{zone_id}/email/routing/dns: code 10000--This error indicate API Key is missing some permissions. Update `CF_TOKEN` minimum permissiongs--For Account: Email Sending:Edit, DNS Settings:Edit, Email Routing Addresses:Edit-For Zone: DNS Settings:Edit, Email Routing Rules:Edit, Zone Settings:Edit, DNS:Edit--### Manual deploy--```bash-npm run deploy-```--`npm run deploy` builds and deploys the Worker. Cloudflare's deploy button can auto-provision the D1 database, R2 bucket, and queues declared in `wrangler.jsonc`; for manual deployments, create or update those bindings in Cloudflare if they do not already exist.--The deploy script intentionally builds with OpenNext and uploads with Wrangler. Do not replace the-Wrangler step with `opennextjs-cloudflare deploy`: Mailflare's `worker.ts` wrapper exports the-`RealtimeHub` Durable Object and handles email and queue events in addition to the generated Next.js-worker.--For an existing remote D1 database with a committed `database_id`, use:--```bash-npm run deploy:with-migrations-```--### Cloudflare D1 7404: database could not be found--If automatic deployment fails with:--```text-The database <uuid> could not be found [code: 7404]-```+Add your Cloudflare credentials to `.dev.vars`, then open [http://localhost:3000](http://localhost:3000). For sample local data, run `npm run db:seed` while the development server is running.-remove any committed `database_id` from `wrangler.jsonc`. D1 database IDs are account-specific; committing one from another account makes Wrangler look up a database that does not exist in the deploying account. This project declares the `DB` binding with `database_name` only so Wrangler/Cloudflare can provision the D1 database for the target account.+## Documentation-Remote migration commands need a concrete D1 `database_id` in local config. With one-click deploy, Cloudflare provisions the database during deploy, and that generated ID is available in the Cloudflare dashboard, not automatically written back to the repository. After the first successful one-click deploy:+- [Deployment and configuration](docs/deployment.md)+- [API and integrations](docs/api.md)+- [Troubleshooting](docs/troubleshooting.md)-1. Go to Cloudflare dashboard → Workers & Pages → your Worker → Settings → Bindings.-2. Open the `DB` D1 binding and copy the database ID.-3. Add that ID to `wrangler.jsonc` only for your deployment/account if you want to run `npm run db:migrate:remote` or `npm run deploy:with-migrations`.+## License-Do not commit an account-specific D1 ID to a reusable public template.+See [LICENSE](LICENSE).diff --git a/docs/api.md b/docs/api.mdnew file mode 100644index 0000000..94bf28b--- /dev/null+++ b/docs/api.md@@ -0,0 +1,45 @@+# API and integrations++Mailflare exposes APIs for domain management and sending email. Authentication and mailbox permissions still apply to these routes.++## Domain management++Adding or removing a domain from Mailflare also updates Cloudflare Email Routing and sending resources.++| Mailflare route | Purpose |+| --- | --- |+| `GET /api/domains` | List connected domains |+| `POST /api/domains` | Connect a domain and configure Cloudflare |+| `GET /api/domains/[id]` | Get a connected domain |+| `DELETE /api/domains/[id]` | Remove a domain and clean up its Cloudflare resources |+| `GET /api/domains/[id]/dns` | View its routing and sending DNS status |++The hostname must be the apex of a zone available to the configured Cloudflare credentials, or a subdomain of that zone. Creating a mailbox also creates the Cloudflare Email Routing rule that delivers its address to `CF_EMAIL_WORKER_NAME`.++## Sending email++Send email through `POST /api/v1/send`. Attachments are optional and use Base64-encoded content:++```json+{+ "from": "[email protected]",+ "to": "[email protected]",+ "subject": "Report",+ "text": "Attached.",+ "attachments": [+ {+ "filename": "report.pdf",+ "type": "application/pdf",+ "contentBase64": "<base64 data>"+ }+ ]+}+```++The dashboard composer accepts up to 10 attachments, with a 10 MB limit per file and a 20 MB combined limit. Attachment metadata is stored in D1 and file content is stored in R2. Downloads require access to the mailbox containing the message.++## Real-time updates++Mailflare uses a Durable Object WebSocket hub to notify connected users after an inbound message is stored. Mailbox owners, the domain administrator, and delegated users receive events for mailboxes they can access.++The `REALTIME` binding and its migration are declared in `wrangler.jsonc`. When a WebSocket is temporarily unavailable, the app retries the connection and uses a slower refresh until it recovers.diff --git a/docs/deployment.md b/docs/deployment.mdnew file mode 100644index 0000000..4ebc640--- /dev/null+++ b/docs/deployment.md@@ -0,0 +1,105 @@+# Deployment and configuration++This guide covers Cloudflare deployment, runtime configuration, database backups, and application updates.++## One-click deployment++[](https://deploy.workers.cloudflare.com/?url=https://github.com/hieunc229/mailflare)++The deployment flow reads `wrangler.jsonc`, provisions the required Worker bindings, builds the OpenNext Worker, applies D1 migrations, and deploys the app.++Keep `wrangler.jsonc` committed. Do not commit `.dev.vars`; enter secrets during Cloudflare setup or keep them in a local `.dev.vars` file.++## Required configuration++Mailflare needs these runtime values:++- `CF_TOKEN` — a scoped Cloudflare API token with Zone Read, Email Routing Edit, Email Sending Edit, and Email Routing Rules Write access for the domains you will connect. This is separate from the token Cloudflare uses to deploy the app.+- `CF_EMAIL_WORKER_NAME` — the deployed Worker name. It must match the Worker name exactly so Mailflare can create Email Routing rules.+- `CF_AID` — the Cloudflare account ID. This is optional for normal mail use but required for database backups.++You can use a legacy Global API Key instead of `CF_TOKEN` by setting both `CF_API_KEY` and `CF_EMAIL`.++Copy `.dev.vars.example` when configuring a local environment:++```bash+cp .dev.vars.example .dev.vars+```++Paste only the token value into `CF_TOKEN`; do not include `Bearer` and do not use the token ID.++## First-run setup++Open `/setup` after deployment. Mailflare checks the required runtime configuration and initializes an empty D1 database. It never applies later migrations to an existing database from the setup page.++Use the normal migration command when updating an existing installation:++```bash+npm run db:migrate:remote+```++## Manual deployment++Install dependencies, configure the Cloudflare bindings in `wrangler.jsonc`, and run:++```bash+npm install+npm run deploy+```++The deploy command builds the OpenNext application and uploads the complete Worker with Wrangler. The complete Worker is required because `worker.ts` also handles inbound email, queues, workflows, and the real-time Durable Object.++To migrate an existing remote D1 database before deploying, use:++```bash+npm run deploy:with-migrations+```++Remote migrations require the target account's `database_id` in your local `wrangler.jsonc`. Do not commit an account-specific database ID to a reusable repository.++## Custom Worker names++If you rename the Worker, keep these values aligned:++- `name` in `wrangler.jsonc`+- `services[].service` for the `WORKER_SELF_REFERENCE` binding+- `CF_EMAIL_WORKER_NAME`++Cloudflare service bindings use a literal Worker name and cannot inherit the top-level `name` value automatically.++## Database backups++Manual and scheduled backups use the `DATABASE_BACKUP_WORKFLOW` binding declared in `wrangler.jsonc`. Deploy the complete Worker with `npm run deploy` whenever this binding is added or changed.++Backups require:++- `CF_AID`+- `D1_DATABASE_ID`+- `D1_BACKUP_TOKEN`, or a `CF_TOKEN` that is also allowed to export the D1 database++## Updating Mailflare++The **Update Mailflare** button in the admin dashboard dispatches `.github/workflows/update.yml` in the installation repository. The workflow merges the latest upstream source, applies pending D1 migrations, and pushes the updated source. A connected Cloudflare Git integration can then build and deploy the change.++Configure these Worker values:++- `GITHUB_UPDATE_TOKEN` — a fine-grained GitHub token for the installation repository with Actions write permission.+- `GITHUB_UPDATE_REPO` — the installation repository in `owner/repository` format.+- `GITHUB_UPDATE_REF` — an optional update branch. The repository's default branch is used when omitted.++Configure these GitHub Actions repository secrets:++- `CLOUDFLARE_API_TOKEN` — a Cloudflare token allowed to read and migrate D1.+- `CLOUDFLARE_ACCOUNT_ID` — the Cloudflare account ID.+- `MAILFLARE_UPSTREAM_TOKEN` — required only when the upstream repository is private.++Optional repository variables:++- `MAILFLARE_UPSTREAM_REPOSITORY` — the upstream repository. Defaults to `hieunc229/mailflare`.+- `MAILFLARE_UPSTREAM_BRANCH` — the upstream branch. Defaults to `main`.++If an older installation contains a failing updater, copy the latest `.github/workflows/update.yml` into that installation once. An updater that cannot read upstream cannot update its own workflow.++## Branding license++Activate a purchased Pro or Team key from **Admin → Licenses**. Mailflare sends the key to Paymug and stores only a one-way hash and the activation state. Apply all D1 migrations before activating a license.diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdnew file mode 100644index 0000000..770bccf--- /dev/null+++ b/docs/troubleshooting.md@@ -0,0 +1,55 @@+# Troubleshooting++## Cloudflare error 9109: Invalid access token++The Deploy to Cloudflare flow can deploy the Worker, but its deployment token is not exposed to Mailflare at runtime. Create a separate Cloudflare API token and set it as `CF_TOKEN`.++Verify the token:++```bash+curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \+ -H "Authorization: Bearer <CF_TOKEN>"+```++The response should report `success: true` and an active status. Check that:++- `CF_TOKEN` contains the token secret, not its ID.+- The value does not include the word `Bearer`.+- The token is currently valid and its IP restrictions allow the Worker.+- You redeployed after changing Cloudflare variables or secrets.++If you use a legacy Global API Key, set `CF_EMAIL` and `CF_API_KEY` instead of placing it in `CF_TOKEN`.++## Cloudflare error 10000 on Email Routing++Update the token so it can read the zone and manage its DNS, Email Routing settings, and Email Routing rules. The recommended scoped permissions are listed in the [deployment guide](deployment.md#required-configuration).++## D1 error 7404: Database could not be found++D1 database IDs belong to a specific Cloudflare account. This error commonly means `wrangler.jsonc` contains an ID copied from another account.++For a reusable one-click deployment repository, remove the committed `database_id` and keep only `database_name`. Cloudflare can then provision the database in the target account.++For remote migrations after the first deployment:++1. Open the Worker's **Settings → Bindings** page in Cloudflare.+2. Open the `DB` D1 binding and copy its database ID.+3. Add that ID to your local `wrangler.jsonc`.+4. Run `npm run db:migrate:remote`.++Do not commit that account-specific ID to a reusable public repository.++## Backup binding is missing++Deploy the complete Worker with `npm run deploy`. A local Next.js server or a source-only update does not provision the `DATABASE_BACKUP_WORKFLOW` binding.++Also confirm that `CF_AID` and `D1_DATABASE_ID` are set, and that `D1_BACKUP_TOKEN` or `CF_TOKEN` can export the database.++## Inbound mail is not arriving++Confirm that:++- `CF_EMAIL_WORKER_NAME` exactly matches the deployed Worker name.+- `services[].service` in `wrangler.jsonc` uses the same name.+- Email Routing is enabled for the domain in Cloudflare.+- The mailbox has an Email Routing rule pointing to the Worker.