mail-forwarding-ui

Next.js frontend for managing forwarding aliases via the Mail Forwarding API

This project (maintained by a member of Haltman.io) is the web UI for the Free Mail Forwarding Service. It is a Next.js application that talks to the Mail Forwarding API (Node.js/Express) to let users request and confirm:

  • alias creation (subscribe)

  • alias removal (unsubscribe)

This UI is not standalone: it must point to a working API instance, and it must be configured with the list of domains that are authorized in the database.

Tech stack (as shipped):

  • Next.js (next dev, next build, next start)

  • React

  • TailwindCSS

  • Radix UI components

Prerequisites (mandatory)

  • A running Mail Forwarding API (already deployed and reachable)

  • Domains already present/authorized in the Base Stack database (domain table)

  • Node.js (current LTS recommended)

  • npm (or compatible package manager)

Installation

git clone https://github.com/haltman-io/mail-forwarding
cd ./mail-forwarding/mail-forwarding-ui/
npm install
npm run dev

Configuration

To run this UI, you must have a .env.local file in the project root.

.env.local (required)

NEXT_PUBLIC_API_HOST=<API URL WITHOUT SLASH ON END>

Example:

NEXT_PUBLIC_API_HOST=https://mail.haltman.io

Important notes:

  • NEXT_PUBLIC_API_HOST must not end with /

  • These variables are NEXT_PUBLIC_*, meaning they are embedded into the frontend build and visible to users (do not put secrets here)

Running

Development

npm run dev

Production build

npm run build

Scripts available:

  • dev → next dev

  • build → next build

  • start → next start

  • lint → eslint

Possible problems / Important notes

  • UI loads but actions fail: most common cause is NEXT_PUBLIC_API_HOST wrong, unreachable, or with a trailing slash.

  • Domain not selectable / blocked: NEXT_PUBLIC_DOMAINS does not include the domain, or the domain is not present/active in the database.

  • Mixed content / CORS issues: serve UI and API over HTTPS, and ensure the API is configured to allow the UI origin.

  • Wrong environment values in production: if you change .env.local, you must rebuild (npm run build) for production deployments.

Updated on
mail-forwarding-api
DB Cleanup Cronjob (optional)