NodeMailServer
A self-hosted mail stack that receives mail on port 25, sends it from port 587 or a JSON API, handles bounces and serves mailboxes over IMAP.
NodeMailServer started as a fun experiment and has grown into a small mail platform you run yourself. It receives mail for your domains, checks who sent it, accepts mail from your own apps and mail clients, delivers it to the rest of the internet, and processes the bounces that come back.
Under development
Receiving mail, sending mail and IMAP mailboxes are implemented. Some plugins are not connected to the mail pipeline yet. Each page says what is ready and what is not.
What is in the box
| Part | Folder | Port | What it does |
|---|---|---|---|
| Mail server (Node + TypeScript) | server/ | 25 and 587 | Receives mail on 25 and checks it with rules you set in JSON. Accepts authenticated mail on 587 or through the JSON API, signs it with DKIM and queues it for delivery. |
| Bounce server and JSON API | server/ | 2525, 8025 and 8080 | Reads bounce reports, keeps a suppression list, and sends mail from one HTTP request. Both are off until you set a token. |
| Go MTA | server/go-mta/ | 2580 | Optional delivery service written in Go. |
| Sending MTA (KumoMTA) | outbound/ | 587 | Optional delivery engine with SMTP AUTH, per-domain rate limits, DKIM and delivery webhooks. The Node server can use it through SMTP or its HTTP API. |
| IMAP server (Go + Gluon) | server/imap/ | 143 and 993 | Lets mail clients such as Thunderbird, Outlook and phone apps read mailboxes. Mail received on port 25 is stored in it. See IMAP. |
| Documentation | docs/ | 3000 | This site. |
How mail flows
Where to start
Prerequisites
A domain, a static IP, reverse DNS and open ports.
Installation
Run the server with Bun or Docker.
DNS records
Generate and publish MX, SPF, DKIM and DMARC.
Receiving mail
What happens to a message that arrives on port 25.
Sending mail
Submission on port 587, the outbound queue and retries.
JSON send API
Send a message with one HTTP request.
Bounces
Return addresses, the DSN processor and the suppression list.
Configuration files
Turn checks on or off and change every SMTP reply, without a restart.
KumoMTA
Use KumoMTA as the sending engine.