mailer-advance 1.0.7 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -90
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,19 +1,24 @@
|
|
|
1
|
-
# mailer-advance
|
|
1
|
+
# 🚀 mailer-advance v2.0
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/mailer-advance)
|
|
4
|
-
[](https://www.npmjs.com/package/mailer-advance)
|
|
3
|
+
[](https://www.npmjs.com/package/mailer-advance)
|
|
4
|
+
[](https://www.npmjs.com/package/mailer-advance)
|
|
5
|
+
[](https://nodejs.org)
|
|
5
6
|
|
|
6
|
-
|
|
7
|
+
**mailer-advance** is a high-performance, production-ready Node.js email engine. It provides dynamic SMTP management, multi-database persistence (MongoDB, PostgreSQL, MySQL), and a premium, glassmorphic built-in UI for administration.
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
---
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
11
|
+
## ✨ Features
|
|
12
|
+
|
|
13
|
+
- 🗄️ **Persistence**: Multi-database support for storing SMTP configs (MongoDB, Postgres, MySQL).
|
|
14
|
+
- 🔄 **Hot-Swapping**: Switch SMTP servers at runtime via API or the Admin Dashboard.
|
|
15
|
+
- 🎨 **Premium UI**: Built-in dark-mode dashboard for sending tests and managing configs.
|
|
16
|
+
- 🔒 **Secure by Design**: Full STARTTLS/SSL/TLS support with configurable certificate validation.
|
|
17
|
+
- 📎 **Rich Media**: Support for attachments and inline images ($cid$ mapping).
|
|
18
|
+
- 📦 **Zero Overhead**: Ultra-lightweight (~12KB) ESM-only package with minimal dependencies.
|
|
19
|
+
- 📖 **Swagger Included**: Auto-generated API documentation for easy integration.
|
|
20
|
+
|
|
21
|
+
---
|
|
17
22
|
|
|
18
23
|
## 📦 Installation
|
|
19
24
|
|
|
@@ -22,13 +27,13 @@ npm install mailer-advance
|
|
|
22
27
|
```
|
|
23
28
|
|
|
24
29
|
> [!IMPORTANT]
|
|
25
|
-
>
|
|
30
|
+
> **ESM Only**: This package requires `"type": "module"` in your `package.json`.
|
|
26
31
|
|
|
27
|
-
|
|
32
|
+
---
|
|
28
33
|
|
|
29
|
-
|
|
34
|
+
## � Quick Start (Library Mode)
|
|
30
35
|
|
|
31
|
-
|
|
36
|
+
Integrate the email engine into your existing Express app in less than 2 minutes.
|
|
32
37
|
|
|
33
38
|
```javascript
|
|
34
39
|
import express from 'express';
|
|
@@ -43,93 +48,57 @@ import {
|
|
|
43
48
|
const app = express();
|
|
44
49
|
app.use(express.json());
|
|
45
50
|
|
|
46
|
-
//
|
|
47
|
-
const
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
// 2. Connect to your database
|
|
52
|
-
await repository.connect(process.env.DB_URI);
|
|
53
|
-
|
|
54
|
-
// 3. Register it with the shared dbService
|
|
55
|
-
dbService.setRepository(repository);
|
|
56
|
-
};
|
|
57
|
-
|
|
58
|
-
initDB().catch(console.error);
|
|
59
|
-
|
|
60
|
-
// --- Mounting Routes ---
|
|
61
|
-
// These routes handle contact form submissions and SMTP configuration management
|
|
62
|
-
app.use('/api/mail', contactRoutes);
|
|
63
|
-
app.use('/api/config', configRoutes);
|
|
64
|
-
|
|
65
|
-
// --- Programmatic Email Sending ---
|
|
66
|
-
app.post('/send-custom', async (req, res) => {
|
|
67
|
-
try {
|
|
68
|
-
await mailService.sendEmail({
|
|
69
|
-
to: req.body.to,
|
|
70
|
-
subject: 'Custom Notification',
|
|
71
|
-
text: 'This was sent using the mailService directly!',
|
|
72
|
-
// Optional: configId to use a specific stored SMTP configuration
|
|
73
|
-
// configId: 'my-custom-smtp'
|
|
74
|
-
});
|
|
75
|
-
res.json({ success: true });
|
|
76
|
-
} catch (err) {
|
|
77
|
-
res.status(500).json({ error: err.message });
|
|
78
|
-
}
|
|
79
|
-
});
|
|
80
|
-
|
|
81
|
-
app.listen(3000, () => console.log('Server running on port 3000'));
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
### 2. Standalone Service
|
|
51
|
+
// 1. Initialize Database
|
|
52
|
+
const repository = DatabaseFactory.createRepository('mongodb'); // or 'postgres', 'mysql'
|
|
53
|
+
await repository.connect(process.env.DB_URI);
|
|
54
|
+
dbService.setRepository(repository);
|
|
85
55
|
|
|
86
|
-
|
|
56
|
+
// 2. Mount Routes
|
|
57
|
+
app.use('/api/mail', contactRoutes); // Form submissions
|
|
58
|
+
app.use('/api/config', configRoutes); // SMTP Management
|
|
87
59
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
60
|
+
// 3. Access Admin UI (Optional)
|
|
61
|
+
// The UI is served relative to your static assets if configured
|
|
62
|
+
app.listen(3000, () => {
|
|
63
|
+
console.log('🚀 Mailer engine ready at http://localhost:3000');
|
|
64
|
+
console.log('📖 Documentation: http://localhost:3000/api-docs');
|
|
65
|
+
});
|
|
91
66
|
```
|
|
92
67
|
|
|
93
|
-
|
|
68
|
+
---
|
|
94
69
|
|
|
95
|
-
|
|
70
|
+
## 🖥 Admin Dashboard
|
|
96
71
|
|
|
97
|
-
|
|
98
|
-
PORT=3000
|
|
72
|
+
When serving the package, the following tools are available:
|
|
99
73
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
74
|
+
- � **Send Test**: `http://localhost:3000/contact.html`
|
|
75
|
+
- 📑 **Manage Configs**: `http://localhost:3000/list-configs.html`
|
|
76
|
+
- ➕ **Add New**: `http://localhost:3000/config.html`
|
|
77
|
+
- 📚 **Swagger Docs**: `http://localhost:3000/api-docs`
|
|
103
78
|
|
|
104
|
-
|
|
105
|
-
MAIL_HOST=smtp.example.com
|
|
106
|
-
MAIL_PORT=587
|
|
107
|
-
MAIL_SECURE=false
|
|
108
|
-
MAIL_USER=your-user
|
|
109
|
-
MAIL_PASS=your-password
|
|
110
|
-
MAIL_FROM_NAME="System Name"
|
|
111
|
-
MAIL_FROM_EMAIL=noreply@example.com
|
|
112
|
-
```
|
|
79
|
+
---
|
|
113
80
|
|
|
114
|
-
##
|
|
81
|
+
## ⚙️ Configuration (.env)
|
|
115
82
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
83
|
+
| Variable | Description | Default |
|
|
84
|
+
|----------|-------------|---------|
|
|
85
|
+
| `PORT` | Server port | `3000` |
|
|
86
|
+
| `DB_TYPE` | `mongodb`, `postgres`, `mysql` | `mongodb` |
|
|
87
|
+
| `DB_URI` | Connection string | - |
|
|
88
|
+
| `MAIL_HOST` | Fallback SMTP Host | - |
|
|
89
|
+
| `MAIL_PORT` | Fallback SMTP Port | `587` |
|
|
120
90
|
|
|
121
|
-
|
|
91
|
+
---
|
|
122
92
|
|
|
123
|
-
|
|
124
|
-
Send an email using standard or dynamic config.
|
|
125
|
-
- **Body**: `name`, `email`, `to`, `message`, `configId` (optional).
|
|
126
|
-
- **Files**: Supports `attachments` (multipart/form-data).
|
|
93
|
+
## 🔄 Migration to v2.0.0
|
|
127
94
|
|
|
128
|
-
|
|
129
|
-
|
|
95
|
+
V2 introduces breaking changes to improve library integration:
|
|
96
|
+
1. **Named Exports**: All modules now use named exports instead of a single default export.
|
|
97
|
+
2. **Relative UI Paths**: The built-in dashboard now uses relative API paths, allowing it to be mounted on any sub-path (e.g., `/admin/mailer/`).
|
|
98
|
+
3. **Safety Guards**: `DbService` now throws descriptive errors if used before initialization.
|
|
130
99
|
|
|
131
|
-
|
|
132
|
-
Save or update an SMTP configuration profile.
|
|
100
|
+
---
|
|
133
101
|
|
|
134
102
|
## 📜 License
|
|
135
|
-
|
|
103
|
+
|
|
104
|
+
MIT © [Pranay](https://github.com/pranay213)
|
package/package.json
CHANGED