https://github.com/newben420/mailicia

Self-hosted email manager with rich composer, templates, analytics & full data ownership
https://github.com/newben420/mailicia

analytics email email-marketing email-tracking newsletter nextjs nodemailer self-hosted smtp sqlite tailwindcss typescript

Last synced: 15 days ago
JSON representation

Self-hosted email manager with rich composer, templates, analytics & full data ownership

• Host: GitHub
• URL: https://github.com/newben420/mailicia
• Owner: newben420
• License: mit
• Created: 2026-01-16T03:04:30.000Z (23 days ago)
• Default Branch: main
• Last Pushed: 2026-01-18T05:48:43.000Z (21 days ago)
• Last Synced: 2026-01-18T06:58:56.939Z (21 days ago)
• Topics: analytics, email, email-marketing, email-tracking, newsletter, nextjs, nodemailer, self-hosted, smtp, sqlite, tailwindcss, typescript
• Language: TypeScript
• Homepage:
• Size: 612 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Mailicia - Self-Hosted Email Manager

Mailicia is a modern, self-hosted email management solution designed for freelancers, small agencies, and community managers. It bridges the gap between simple email clients and complex marketing platforms, offering robust tools for mass communication, list management, and analytics with full data ownership.

![Mailicia Compose Page](public/screenshots/compose-page.png)

## ✨ Features

- **Dashboard**: At-a-glance overview of your email performance.

- **Inbox**: Full-featured inbox with batch actions (mark read/unread, delete), pagination, and attachment support.

- **Compose**: Rich text editor (Visual & HTML) with variable personalization (`{{name}}`, `{{email}}`).

- **Templates**: Save and reuse email layouts for consistent branding.

- **Recipients & Groups**: Manage contacts and organize them into segmentable groups.

- **Attachments**: Drag-and-drop file management for email attachments.

- **Analytics**: Track opens, clicks, and engagement metrics (requires configured webhook).

- **Internationalization**: Full support for English, French, Spanish, and German.

- **Dark Mode**: Sleek, eye-friendly interface.

## 🛠️ Tech Stack

- **Framework**: Next.js 14 (App Router)

- **Language**: TypeScript

- **Database**: SQLite (via `better-sqlite3`) or Supabase (PostgreSQL)

- **Storage**: Local File System or Supabase Storage

- **UI**: Tailwind CSS, Lucide Icons, Shadcn/ui

- **Auth**: JWT-based authentication

- **Email**: Nodemailer (SMTP, Resend, Brevo support)

- **Inbound**: Cloudflare Workers + PostalMime

## 🚀 Getting Started

### Prerequisites

- Node.js 18+

- npm or pnpm

### Installation

1.  **Clone the repository**

    ```bash

    git clone https://github.com/yourusername/mailicia.git

    cd mailicia

    ```

2.  **Install dependencies**

    ```bash

    npm install

    ```

3.  **Configure Environment**

    Copy `.env.example` to `.env` and update the values.

    ```bash

    cp .env.example .env

    ```

    

    > **Note**: The default admin credentials are:

    > - Username: `admin`

    > - Password: `password`

    >

    > **Change these in your `.env` file immediately for production use!**

4.  **Initialize Database**

    Run the initialization script to create tables and seed sample data (like the "Hello World" template).

    ```bash

    npm run db:init

    ```

5.  **Start the Development Server**

    ```bash

    npm run dev

    ```

    Open [http://localhost:3000](http://localhost:3000) in your browser.

## ⚙️ Configuration

The `.env` file controls all major settings. See `.env.example` for a complete list.

### Providers

You can choose between **Local** (SQLite + File System) or **Supabase** (PostgreSQL + S3 Storage) for data persistence.

**Local Mode (Default)**

```env

DB_PROVIDER=sqlite

STORAGE_PROVIDER=local

DB_PATH=./email-manager.sqlite

```

**Supabase Mode**

1. Create a Supabase project.

2. Run the SQL schema provided in `scripts/setup-supabase.ts` (or run the script if connected).

3. Configure `.env`:

```env

DB_PROVIDER=supabase

STORAGE_PROVIDER=supabase

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co

SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

```

### Other Settings

- **Authentication**: `JWT_SECRET`, `USERNAME`, `PASSWORD`

- **Email Provider**: Choose between `smtp`, `resend`, or `brevo`.

- **Public URL**: `APP_URL` is critical for tracking pixel and link redirect functionality.

- **Inbound Settings**: `INBOUND_SAVE_ATTACHMENTS` (enable/disable file saving), `INBOUND_MAX_ATTACHMENT_SIZE` (limit file size).

## 📥 Inbound Email Setup (Cloudflare Workers)

![Mailicia Inbox](public/screenshots/inbox.png)

To receive emails and have them appear in your Inbox, you need to set up a Cloudflare Worker that forwards incoming emails to your Mailicia instance.

1.  **Create a Cloudflare Worker**:

    - Go to your Cloudflare Dashboard -> Workers & Pages -> Create Application -> Create Worker.

    - Name it (e.g., `mailicia-inbound`).

2.  **Deploy the Worker Code**:

    - Copy the content of [`cloudflare-worker-example.js`](./cloudflare-worker-example.js) from this repository.

    - Paste it into your Worker's code editor (usually `worker.js`).

    - Add the `postal-mime` dependency in `package.json` within the Cloudflare editor or upload it if using Wrangler.

3.  **Configure Environment Variables**:

    In the Worker settings (Settings -> Variables), add:

    - `APP_URL`: The full URL of your deployed Mailicia app (e.g., `https://mail.yourdomain.com`).

    - `INBOUND_API_KEY`: A secret key. **Must match** the `INBOUND_API_KEY` in your Mailicia `.env` file.

    - `SENDER_ADDRESSES`: (Optional) Comma-separated list of email addresses you want to receive emails *to*.

    - `INBOUND_SAVE_ATTACHMENTS`: (Optional) Set to `true` to enable attachment forwarding (forwarded as base64).

    - `INBOUND_MAX_ATTACHMENT_SIZE`: (Optional) Max size per attachment in bytes (default 2MB).

4.  **Configure Email Routing**:

    - Go to your domain in Cloudflare -> Email -> Email Routing.

    - Enable Email Routing.

    - Go to **Routes** -> **Create Rule**.

    - **Action**: "Send to a Worker".

    - **Destination**: Select your `mailicia-inbound` worker.

    - **Match**: "All emails" or specific addresses like `admin@yourdomain.com`.

Now, emails sent to your domain will be parsed by the Worker and pushed to your Mailicia Inbox!

## 📖 Usage Guide

### Logging In

Access the login page at `/login`. Use the credentials defined in your `.env`.

### Inbox Management

- **Read Emails**: Click on any row to view full email details and attachments.

- **Batch Actions**: Select multiple emails using checkboxes to bulk **Delete**, **Mark Read**, or **Mark Unread**.

- **Pagination**: Use the pagination controls at the bottom to navigate large lists. You can also customize the number of rows per page (persisted in your browser).

### Sending Emails

1.  Go to **Compose**.

2.  Enter a subject and select recipients (individuals or groups).

3.  Write your content. Use the **Personalization** feature to add dynamic data like `{{name}}`.

4.  Optionally attach files from the **Attachments** library.

5.  Click **Send**.

### Creating Templates

1.  Draft an email in the **Compose** page.

2.  Click **Save as Template**.

3.  Give it a name.

4.  Future emails can load this template instantly.

### Tracking Analytics

Mailicia embeds a tracking pixel in every sent email. 

- **Opens**: Recorded when images are loaded in the recipient's email client.

- **Clicks**: Links in emails are wrapped to track click-throughs before redirecting.

- View aggregate stats on the **Analytics** page or per-email details on the **Sent** page.

## 🌍 Localization

Mailicia is fully localized. Toggle the language from the login screen or the sidebar.

- **English** (`en`)

- **Français** (`fr`)

- **Español** (`es`)

- **Deutsch** (`de`)

## 🤝 Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

## 📄 License

MIT License.