Felixx Mail - Documentation

Overview

Felixx Mail is a static UI paired with Vercel serverless functions that handle Lark OAuth and mailbox proxy calls. The frontend never stores refresh tokens; those stay in encrypted, HttpOnly cookies managed by the backend.

Architecture

Browser → /api/auth/lark → Lark OAuth → /api/auth/callback Browser → /api/mail/messages → Lark Mail API Session: HttpOnly cookie (AES-GCM, SESSION_SECRET)

The mail UI uses mock data if the backend is not configured.

Login with Lark (No IMAP)

Use Lark Open Platform OAuth (Authorization Code flow). After the user authorizes, your backend exchanges the code for a user access token and refresh token, then stores them securely. The refresh token lets you keep users signed in without IMAP credentials.

1. Create a Lark app and enable OAuth in the developer console.

2. Set the redirect URL to https://YOUR_DOMAIN/api/auth/callback.

3. Deploy and set the environment variables below.

4. Send users to /api/auth/lark to start login.

Environment Variables

LARK_APP_ID=your_app_id LARK_APP_SECRET=your_app_secret LARK_REDIRECT_URI=https://your-domain/api/auth/callback SESSION_SECRET=long_random_secret ALLOWED_EMAILS=felix@felixx.dev LARK_USER_INFO_URL=<from Lark console> LARK_BASE_URL=<from Lark console> LARK_AUTHORIZE_URL=<from Lark console> LARK_ACCESS_TOKEN_URL=<from Lark console> LARK_REFRESH_TOKEN_URL=<from Lark console> LARK_APP_ACCESS_TOKEN_URL=<from Lark console> LARK_MAIL_LIST_URL=<from Lark console> LARK_MAIL_MESSAGE_URL=<from Lark console; use :id>

Use the exact endpoints and scopes shown in your Lark developer console for your tenant.

API Contracts (Backend)

GET /api/mail/messages → { messages: [ ... ] }

GET /api/mail/messages/:id → { message }

DELETE /api/mail/messages/:id → { success: true }

Single-User Allowlist

Only approved emails can complete OAuth login. Set ALLOWED_EMAILS to a comma-separated list (default is felix@felixx.dev).

If a user is not on the allowlist, they are redirected to /access.html?denied=1.

Aliases

Alias handling is configured in aliases.js. The inbox UI lets you switch aliases, and the selected alias is sent as ?alias= to the backend.

Landing Stats

Landing stats update once per day for the felixx.dev domain, driven by landing.js. Other domains show static demo values.

Private Access

Access is limited to the felixx.dev domain. Use the template on the access page to request credentials.