MailNest Documentation

Free self-hosted email inbox on Cloudflare

Quick Start

Get your own email inbox in minutes.

Clone Repository

Clone the MailNest repository from GitHub.

git clone https://github.com/arosyihuddin/mailnest.git && cd mailnest

Run Installer

The installer handles everything: Cloudflare auth, D1 database, DNS, and email routing.

./install.sh

Access Dashboard

Open your browser and navigate to your custom domain.

https://mail.yourdomain.com

Receive Emails

Start receiving emails at any address on your domain.

anything@yourdomain.com → your dashboard

Prerequisites

A Cloudflare account (free tier)
A domain added to Cloudflare with Email Routing enabled
Bun runtime installed (installer handles this)
Git installed

API Endpoints

REST API reference for MailNest.

Method	Endpoint	Description	Auth
POST	`/api/auth`	Login (password verification)	-
PUT	`/api/auth`	Reset password (requires secret key)	-
DELETE	`/api/auth`	Logout (session cleanup)	-
GET	`/api/auth`	Check session validity	Required
GET	`/api/emails`	List emails (paginated, filtered by folder/search/address)	Required
GET	`/api/emails/:id`	Get single email with attachments	Required
PATCH	`/api/emails/:id`	Update email (read, starred, folder)	Required
DELETE	`/api/emails/:id`	Permanently delete email	Required
PATCH	`/api/emails/bulk`	Bulk update emails	Required
DELETE	`/api/emails/bulk`	Bulk delete emails	Required
GET	`/api/emails/counts`	Unread/total counts per folder	Required
GET	`/api/addresses`	List all email addresses	Required
POST	`/api/addresses`	Create new email address	Required
PATCH	`/api/addresses/:id`	Update address	Required
DELETE	`/api/addresses/:id`	Delete address	Required
GET	`/api/attachments/:id`	Download attachment from R2	Required
GET	`/api/routing-rules`	List routing rules	Required
POST	`/api/routing-rules`	Create routing rule	Required
PATCH	`/api/routing-rules/:id`	Update routing rule	Required
DELETE	`/api/routing-rules/:id`	Delete routing rule	Required

Cloudflare Free Tier

MailNest fits entirely within Cloudflare's free tier.

Resource	Free Limit	Typical Usage
Workers Requests	100K/day	Dashboard views + email processing
D1 Reads	5M/day	Email queries
D1 Writes	100K/day	Storing incoming emails
D1 Storage	5 GB	~50K emails with full HTML
R2 Storage	10 GB	Attachments (optional)
R2 Reads	10M/month	Attachment downloads
Email Routing	Unlimited	All inbound emails

Architecture

How MailNest works as a single Cloudflare Worker.

Architecture

someone@gmail.com                    You (browser)
sends email to                       open mail.yourdomain.com
you@yourdomain.com                          │
       │                                    │
       ▼                                    ▼
┌─────────────────────────────────────────────┐
│        Single Cloudflare Worker             │
│              "mailnest"                     │
│                                             │
│  email() handler          fetch() handler   │
│  ├─ Resolve recipient     ├─ SvelteKit SPA  │
│  ├─ Unknown? Reject       ├─ API endpoints  │
│  └─ Known? Parse & store  └─ Static assets  │
└─────────────────────────────────────────────┘
                    │
                    ▼
             Cloudflare D1
           (your emails)