Skip to content

Commit bb4aa07

Browse files
author
Timothy Dodd
committed
chore: Update README for clarity and organization of features and setup instructions
1 parent e600b96 commit bb4aa07

1 file changed

Lines changed: 69 additions & 142 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,183 +1,110 @@
11
# MailVoid
22

3-
MailVoid is a developer-focused email testing tool that simplifies managing multiple test email addresses without creating separate email accounts. It integrates with your mail server via webhooks to capture and organize test emails in a clean web interface.
3+
A developer email testing tool that captures and organizes test emails without creating separate email accounts. It integrates with your mail server via webhooks and provides a clean web interface for viewing and managing messages. It also includes a webhook capture feature for testing HTTP webhooks.
44

55
![image](https://github.com/user-attachments/assets/320b036f-b522-44d7-8be3-b23d3f610128)
66

7-
> [!WARNING]
7+
> [!WARNING]
88
> This project is currently in prototype status. Expect frequent changes and updates.
99
10-
## 🚀 Features
10+
## Features
1111

12-
- **Backend API**: RESTful API built with C# .NET 10
13-
- JWT-based authentication with refresh token rotation
14-
- Webhook integration for email capture from your mail server
15-
- Webhook capture feature for testing HTTP webhooks
16-
- Health check endpoints for monitoring
17-
- Real-time notifications via SignalR
12+
- Receive and store emails via mail server webhooks
13+
- Organize emails into groups with configurable retention policies
14+
- Capture and inspect arbitrary HTTP webhooks
15+
- Real-time notifications via SignalR
16+
- JWT authentication with refresh token rotation
17+
- Responsive Angular SPA with dark theme
1818

19-
- **Web Frontend**: Modern Angular 19 SPA
20-
- Clean, responsive interface for email management
21-
- Email grouping and organization
22-
- Webhook capture and inspection UI
23-
- User settings and password management
24-
- Real-time email and webhook notifications
25-
26-
- **Database**: MySQL with RoboDodd.OrmLite (Dapper-based)
27-
- Efficient email storage and retrieval
28-
- User management and authentication
29-
- Email grouping with retention policies
30-
- Webhook bucket organization
31-
32-
## 📋 Requirements
19+
## Requirements
3320

3421
- .NET 10 SDK
3522
- Node.js 22+ and npm
3623
- MySQL 8.0+
37-
- Mail server with webhook support (optional)
38-
39-
## 🛠️ Installation
4024

41-
### Clone the Repository
25+
## Getting Started
4226

4327
```bash
4428
git clone https://github.com/timothydodd/MailVoid.git
4529
cd MailVoid
4630
```
4731

48-
### Backend Setup
49-
50-
1. Navigate to the API directory:
51-
```bash
52-
cd src/MailVoidApi
53-
```
54-
55-
2. Configure your settings in `appsettings.json`:
56-
```json
57-
{
58-
"ConnectionStrings": {
59-
"DefaultConnection": "Server=localhost;Database=mailvoid;User=root;Password=yourpassword;"
60-
},
61-
"JwtSettings": {
62-
"Secret": "your-256-bit-secret-key-here",
63-
"Issuer": "MailVoidApi",
64-
"Audience": "MailVoidClient",
65-
"ExpiryMinutes": 15
66-
}
67-
}
68-
```
69-
70-
3. Start the API (tables are created automatically on startup):
71-
```bash
72-
dotnet run
73-
```
74-
75-
### Frontend Setup (Development)
76-
77-
1. Navigate to the web directory:
78-
```bash
79-
cd src/MailVoidWeb
80-
```
81-
82-
2. Install dependencies:
83-
```bash
84-
npm install
85-
```
86-
87-
3. Configure the API endpoint in `src/environments/environment.ts` if needed
88-
89-
4. Start the development server:
90-
```bash
91-
npm start
92-
```
93-
94-
## 🎯 Usage
95-
96-
1. Access the application at `http://localhost:8200` (development) or `http://localhost:5133` (production)
97-
2. Log in with default credentials:
98-
- Username: `admin`
99-
- Password: `admin`
100-
3. Configure your mail server to send webhooks to your API endpoint
101-
4. Start receiving and managing test emails!
102-
103-
## 📝 Available Scripts
104-
105-
### Backend (.NET API)
106-
```bash
107-
dotnet run # Run the API with frontend proxy
108-
dotnet build # Build the project
109-
dotnet test # Run tests
110-
```
32+
### Backend
11133

112-
### Frontend (Angular)
11334
```bash
114-
npm start # Start development server
115-
npm run build # Build for production
116-
npm run lint # Run ESLint
117-
npm run format # Format code with Prettier
118-
npm test # Run unit tests
35+
cd src/MailVoidApi
11936
```
12037

121-
## 🐳 Docker Support
38+
Configure `appsettings.json` with your MySQL connection and JWT settings:
39+
40+
```json
41+
{
42+
"ConnectionStrings": {
43+
"DefaultConnection": "Server=localhost;Database=mailvoid;User=root;Password=yourpassword;"
44+
},
45+
"JwtSettings": {
46+
"Secret": "your-256-bit-secret-key-here",
47+
"Issuer": "MailVoidApi",
48+
"Audience": "MailVoidClient",
49+
"ExpiryMinutes": 15
50+
}
51+
}
52+
```
12253

123-
Build and run with Docker:
54+
Start the API (database tables are created automatically):
12455

12556
```bash
126-
docker build -f src/MailVoidApi/Dockerfile -t mailvoid .
127-
docker run -p 5133:80 mailvoid
57+
dotnet run
12858
```
12959

130-
## 🧪 Development
60+
### Frontend
61+
62+
```bash
63+
cd src/MailVoidWeb
64+
npm install
65+
npm start
66+
```
13167

132-
### Technologies Used
68+
Update `src/environments/environment.ts` if your API is not running on the default port.
13369

134-
**Backend:**
135-
- .NET 10
136-
- RoboDodd.OrmLite (Dapper-based micro ORM)
137-
- JWT Authentication
138-
- SignalR for real-time updates
70+
### Default Credentials
13971

140-
**Frontend:**
141-
- Angular 19 with standalone components
142-
- RxJS for reactive programming
143-
- Lucide icons
144-
- Bootstrap-based custom styling
145-
- ngx-toastr for notifications
146-
- @ng-select for enhanced dropdowns
72+
- Username: `admin`
73+
- Password: `admin`
14774

148-
### Project Structure
75+
## Docker
14976

77+
```bash
78+
docker build -f src/MailVoidApi/Dockerfile -t mailvoid .
79+
docker run -p 5133:80 mailvoid
15080
```
151-
MailVoid/
152-
├── src/
153-
│ ├── MailVoidApi/ # .NET Backend API
154-
│ │ ├── Controllers/ # API endpoints
155-
│ │ ├── Services/ # Business logic
156-
│ │ ├── Models/ # Entity models
157-
│ │ └── Data/ # Database service
158-
│ └── MailVoidWeb/ # Angular Frontend
159-
│ ├── src/app/
160-
│ │ ├── Pages/ # Page components
161-
│ │ ├── _components/ # Shared components
162-
│ │ └── _services/ # Angular services
163-
│ └── src/styles/ # Global styles
164-
└── .github/workflows/ # CI/CD pipelines
165-
```
166-
167-
## 🤝 Contributing
16881

169-
This project is in prototype phase. Contributions are welcome but please wait until we're closer to v1.0 for major changes. Feel free to:
82+
## Tech Stack
17083

171-
1. Report bugs and issues
172-
2. Suggest new features
173-
3. Submit pull requests for fixes
84+
| Layer | Technology |
85+
| -------- | --------------------------------------------- |
86+
| Backend | .NET 10, RoboDodd.OrmLite (Dapper), SignalR |
87+
| Frontend | Angular 19, RxJS, Lucide, Bootstrap |
88+
| Database | MySQL 8.0+ |
17489

175-
## 📄 License
90+
## Project Structure
17691

177-
This project is licensed under the MIT License - see the LICENSE file for details.
92+
```
93+
src/
94+
├── MailVoidApi/ # .NET backend API
95+
│ ├── Controllers/ # REST endpoints
96+
│ ├── Services/ # Business logic
97+
│ ├── Models/ # Entity models
98+
│ └── Data/ # Database service
99+
├── MailVoidSmtpServer/ # SMTP server for local development
100+
├── MailVoidWeb/ # Angular frontend
101+
│ └── src/app/
102+
│ ├── Pages/ # Page components
103+
│ ├── _components/ # Shared components
104+
│ └── _services/ # API and auth services
105+
└── RoboDodd.OrmLite/ # ORM submodule
106+
```
178107

179-
## 🙏 Acknowledgments
108+
## License
180109

181-
- [Microsoft](https://microsoft.com/) for .NET and development tools
182-
- [Angular](https://angular.io/) for the frontend framework
183-
- [Dapper](https://github.com/DapperLib/Dapper) for the micro ORM foundation
110+
This project is licensed under the MIT License.

0 commit comments

Comments
 (0)