TPT Open Source

TPT-Email-Provider

TypeScript

DIY self-hosted email server for Windows — full SMTP/IMAP stack you own and run yourself, no subscriptions, no third-party access. Built with TypeScript. MIT licensed.

0 stars0 forks0 watchersMIT License
email-serverimapmail-serveropen-sourceprivacyself-hostedsmtptypescriptwindows
View on GitHub

Languages

TypeScript68.8%JavaScript14.2%CSS12.0%PowerShell3.3%HTML1.7%
README

TPT Email Provider

License: MIT Node.js Version TypeScript

A full-featured email service provider built natively for Windows using Node.js and TypeScript. This project provides a complete email server solution with SMTP, IMAP, REST API, and web dashboard - an alternative to Gmail and SendGrid that you can host yourself.

🚀 Features

Email Protocols

  • SMTP Server - Receive emails on port 25, send via submission on port 587
  • IMAP Server - Full IMAP4rev1 implementation (RFC 3501 compliant)
  • STARTTLS & SSL - Secure connections on all protocols
  • Authentication - LOGIN, PLAIN, and CRAM-MD5 support

Management & API

  • REST API - Complete API for sending emails, managing users, domains, templates
  • Web Dashboard - Modern vanilla JS interface with dark mode
  • JWT & API Keys - Flexible authentication options
  • Rate Limiting - Built-in protection against abuse

Windows Integration

  • Windows Service - Runs as a native Windows service
  • Event Log - Integration with Windows Event Viewer
  • Firewall Setup - Automated PowerShell scripts
  • Process Management - Health monitoring and auto-restart

Deliverability

  • DNS Validation - SPF, DKIM, DMARC record checking
  • IP Reputation - Blacklist monitoring
  • Queue Management - Retry logic with exponential backoff
  • Bounce Handling - Automatic processing of delivery failures

📋 Requirements

  • Windows 10/11 or Windows Server 2019+
  • Node.js 20+ (LTS recommended)
  • Static IP Address (essential for email deliverability)
  • Business Internet Connection (residential IPs often blocked)
  • PTR/Reverse DNS Record (set by your ISP)

🛠️ Installation

Quick Start (Development)

# Clone the repository
git clone https://github.com/tptsolutions/tpt-email-provider.git
cd tpt-email-provider

# Install dependencies
npm install

# Run setup wizard
node scripts/setup-wizard.js

# Start development server
npm run dev

Production Installation

# Run as Administrator
.\scripts\install.ps1

# Configure Windows Firewall
.\scripts\firewall-setup.ps1

# Install as Windows Service
ts-node src/windows/service.ts install

📖 Documentation

🔧 Configuration

Create a .env file in the project root:

NODE_ENV=production
PORT=3000
DOMAIN=email.tptsolutions.co.nz

# SMTP
SMTP_PORT=25
SMTP_SUBMISSION_PORT=587
SMTP_SSL_PORT=465

# IMAP
IMAP_PORT=143
IMAP_SSL_PORT=993

# Database
DB_PATH=./data/email.db

# Security
JWT_SECRET=your-secret-key-here

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

🌐 API Endpoints

Authentication

  • POST /api/v1/auth/register - Register new user
  • POST /api/v1/auth/login - User login
  • GET /api/v1/auth/me - Get current user
  • POST /api/v1/auth/refresh - Refresh access token

Email

  • POST /api/v1/emails/send - Send email
  • GET /api/v1/emails/sent - List sent emails
  • GET /api/v1/emails/status/:id - Check delivery status

Management

  • GET /api/v1/stats/dashboard - Dashboard statistics
  • POST /api/v1/domains - Add domain
  • GET /api/v1/domains - List domains
  • POST /api/v1/templates - Create template
  • POST /api/v1/webhooks - Create webhook

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     CLIENT APPLICATIONS                      │
│         (Web Dashboard, Mobile Apps, Third-party)            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    API GATEWAY (Express)                     │
│  - Rate limiting  - Authentication  - Request validation     │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐  ┌──────────────┐  ┌──────────────┐
│   SMTP Server   │  │  IMAP Server │  │  REST API    │
│   (Port 25/587) │  │  (Port 993)  │  │  (Port 3000) │
└─────────────────┘  └──────────────┘  └──────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    MESSAGE PROCESSOR                         │
│  - Queue management (Bull/Redis)  - Spam filtering          │
│  - Routing (local vs remote)      - Retry logic             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    DATA LAYER                                │
│  SQLite: users, domains, emails, queues, logs              │
│  Filesystem: email bodies (maildir), attachments            │
└─────────────────────────────────────────────────────────────┘

⚠️ Important Notes

Email Deliverability

  • Residential IPs are often blocked by major email providers
  • PTR record is essential - must be set by your ISP
  • Gradual IP warming is required for new servers
  • Monitor blacklists regularly (Spamhaus, Barracuda, etc.)

Windows Specific

  • Ports < 1024 require Administrator privileges
  • Windows Defender may interfere - add exclusions for data directory
  • Real-time antivirus scanning can slow down mail processing

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

What MIT License Means:

  • ✅ Commercial use allowed
  • ✅ Modification allowed
  • ✅ Distribution allowed
  • ✅ Private use allowed
  • ✅ Sublicensing allowed
  • ⚠️ No warranty provided
  • ⚠️ No liability accepted

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

  • [x] SMTP Server (send/receive)
  • [x] IMAP Server (full implementation)
  • [x] REST API
  • [x] Web Dashboard
  • [x] Windows Service integration
  • [ ] CalDAV/CardDAV support
  • [ ] Advanced spam filtering (Rspamd integration)
  • [ ] WebSocket real-time updates
  • [ ] Mobile app
  • [ ] Multi-domain support enhancements

Made with ❤️ by TPT Solutions

Empowering you to own your email infrastructure