Configuration

Everything your server reads comes from wrangler.jsonc, from Worker secrets, or from rows in D1. This page lists all of it, then covers the optional features: notifications, Swiftly signatures, Gmail import, backups and the JMAP endpoint for other clients.

After editing wrangler.jsonc, deploy again with pnpm run deploy. Secrets take effect without a deploy.

Variables

Set these under vars in wrangler.jsonc.

DEV_ORIGIN and SWIFTLY_BASE also exist, for local development against a dev server or a local Swiftly. Leave them unset in production.

Serving the UI yourself

Your Worker serves the full UI too, not only the API. If you set APP_ORIGIN to your Worker's own origin and RP_ID to its host or parent domain, you can use Mailopus at your Worker's URL with no mailopus.net involved. On workers.dev, RP_ID has to be the full host, mailopus.<your subdomain>.workers.dev, because workers.dev is a public suffix. A custom domain such as mail.example.com can use example.com.

Passkeys made for mailopus.net don't work at the new origin. Make a new one with an invite link whose base URL is the new origin:

MAILOPUS_DB=mailopus node scripts/invite.mjs sam@example.com https://mail.example.com

This setup works in the code, but the supported and tested path is app.mailopus.net.

Secrets

Set each with npx wrangler secret put <NAME> from your clone. Wrangler asks for the value, so it stays out of your shell history. Remove one with npx wrangler secret delete <NAME>.

Bindings and the rest of wrangler.jsonc

The template has no services entry. app.mailopus.net binds its private spam Worker there. See Spam.

Settings in D1

Some state lives in the instance_settings table:

Per-account settings, such as blocked senders, address groups and highlight exclusions, live in their own tables and are edited in Settings.

Notifications

Settings > This device > Notifications turns on a push notification for each new Inbox message, per browser. On iPhone and iPad, add Mailopus to the home screen first. Safari only allows notifications there.

Mail filed in Junk, mail you sent yourself, and imported mail never notify. The message is encrypted for your browser, so Apple's and Google's push services carry it without being able to read it.

Push needs no setup. On first use the server makes a VAPID key pair and keeps it in D1. Set VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY only to bring an existing key pair, for example when moving to a new server with existing subscriptions. Changing the keys breaks every existing subscription, so each browser has to turn notifications off and on again.

Swiftly signatures

Swiftly keeps email signatures up to date across a team. Mailopus can let Swiftly manage an address's signature.

1. Settings > Addresses, then an address's menu > Signature…
2. Pick Swiftly and connect. Your browser goes to swiftly.biz to approve, then comes back.
3. Choose whether Swiftly manages this address only or all your addresses.

The connection uses an authorization code with PKCE. The Swiftly token stays on your Worker and never reaches the browser. The 5-minute cron syncs each managed address at most every 30 minutes.

While Swiftly manages a signature, the dialog shows it read-only. Swiftly refuses to sync over an edit made somewhere else. Turning Swiftly on keeps what you wrote, and Swiftly adds its own part. Disconnect stops the updates and leaves the signatures as they are.

Gmail import

Mailopus can copy a Google Workspace mailbox into an account. It's built for Workspace, not personal Gmail. It reads mail through a Google service account with domain-wide delegation, which only a Workspace admin can grant. There's no UI. You drive it with scripts/import.mjs.

What comes over:

• Every message, as its original raw file
• Read and starred state, and drafts
• Inbox, Sent, Drafts, Spam and Trash into the matching mailboxes
• Your Gmail labels as labels

It's safe to run again. Each message is stored once per account, so a rerun skips what's already there.

1. Make a service account

In Google Cloud:

1. Create a project, or use one you have.
2. Enable the Gmail API.
3. Create a service account with no roles. Create a JSON key for it and download it.
4. Note the service account's numeric client ID.

2. Grant domain-wide delegation

As the Workspace's admin, open admin.google.com > Security > Access and data control > API controls > Manage domain-wide delegation. Add the client ID with exactly one scope:

https://www.googleapis.com/auth/gmail.readonly

This lets the key read every mailbox in the Workspace. Treat the key file like a password, and delete it after the next step.

3. Store the key as a secret

Pick a short name for the Workspace, such as work. From your clone:

npx wrangler secret put GOOGLE_SA_WORK < path/to/key.json

Then delete the downloaded key file.

4. Start an import

MAILOPUS_DB=mailopus node scripts/import.mjs start work sam@company.example sam@example.com

The arguments are the secret's name without GOOGLE_SA_, the Gmail address to read, and any address the target Mailopus account sends as. The 5-minute cron picks up the job, and the queue fetches 100 messages per page.

Watch and control it

MAILOPUS_DB=mailopus node scripts/import.mjs status

A job id prefix is enough. Every command needs MAILOPUS_DB=mailopus.

When you're done, delete the secret with npx wrangler secret delete GOOGLE_SA_WORK and remove the delegation in the admin console.

Backups

Mailopus has no backup feature of its own. Your data is in two places, and both need covering:

• D1 holds accounts, addresses, the message index, flags, mailboxes, sessions and passkeys.
• R2 holds each message's raw file.

The Account Durable Objects hold only scheduling state, nothing you'd need to restore.

D1

D1 Time Travel keeps a restore point for every minute of the last 30 days on Workers Paid. To undo a mistake:

npx wrangler d1 time-travel info mailopus

npx wrangler d1 time-travel restore mailopus --timestamp=<unix time or RFC 3339>

A restore replaces the whole database. For a copy outside Cloudflare, export it to a file on a schedule:

npx wrangler d1 export mailopus --remote --output=mailopus-$(date +%F).sql

R2

R2 keeps no versions of its own. To copy the bucket somewhere else, make an R2 API token with read access in the dashboard under R2 > Manage API tokens, then use any S3 tool. With rclone set up for R2 as a remote called r2:

rclone sync r2:mailopus-mail /path/to/backup/mailopus-mail

Each file is a standard .eml that any mail program opens. Together with a D1 export, that's a full copy of your mail.

JMAP for other clients

Mailopus speaks JMAP, RFC 8620 and RFC 8621, so a JMAP client can use it directly with no proxy.

Methods: Mailbox/get, Mailbox/changes, Mailbox/set, Thread/get, Email/get, Email/query, Email/changes, Email/set, Email/import, Identity/get, Identity/set, EmailSubmission/get and EmailSubmission/set.

Limits: 25 MB per upload, 10 MB per request, 32 calls per request, 500 objects per get or set, 4 concurrent requests.

What's missing or partial:

• The session gives its URLs as paths, not full URLs. Clients that expect absolute URLs may fail.
• It lists an eventSourceUrl, but /jmap/eventsource isn't served yet, so push over EventSource doesn't work.
• The web UI gets live updates over a WebSocket at /jmap/ws. The session doesn't announce the JMAP WebSocket capability, so other clients won't find it.
• Mailbox/set renames and destroys labels. It can't create one, and the standard mailboxes can't be renamed or destroyed. Labels appear when mail is filed into them.
• Calendars and contacts aren't there.

Browsers can't call the API from another site. CORS answers only APP_ORIGIN. Native and server-side clients aren't affected.