A robust, scalable, and well-documented REST API for sending emails, built with TypeScript and professional software engineering principles. This project serves as a template for creating enterprise-grade Node.js applications.
In modern software development, sending emails is a common requirement, but building a service that is reliable, maintainable, and testable can be challenging. This project was created to demonstrate best practices in:
- Clean Architecture: Separating concerns into distinct layers (API, Controllers, Services).
- Test-Driven Development (TDD): Ensuring code quality and reliability through comprehensive unit and integration tests.
- Professional Documentation: From in-code TSDoc to interactive API docs with Swagger.
- TypeScript First: Leveraging static typing for a more robust and developer-friendly experience.
- ✅ RESTful API for sending emails.
- ✅ TypeScript for type safety and scalability.
- ✅ Clean Architecture for separation of concerns.
- ✅ Unit & Integration Tests with Jest.
- ✅ Auto-generated API Documentation with Swagger (OpenAPI).
- ✅ Environment-based Configuration using
.envfiles. - ✅ Professional Linting and Formatting with ESLint and Prettier (to be added).
- ✅ Ready for Dockerization and container-based deployment.
- Backend: Node.js, Express.js
- Language: TypeScript
- Email: Nodemailer (connects to any SMTP server, e.g., Papercut for local dev)
- Testing: Jest, Supertest
- API Documentation: Swagger (OpenAPI),
swagger-ui-express
Before you begin, ensure you have the following installed on your system:
- Node.js (v16.x or higher recommended)
- npm or yarn
- An SMTP server for development. We recommend Papercut SMTP for a simple local email server.
Follow these steps to get the project up and running on your local machine.
git clone https://github.com/your-username/pro-email-service.git
cd pro-email-servicenpm installCreate a .env file in the root of the project by copying the example file:
cp .env.example .envOpen the .env file and ensure the variables match your local setup (especially the SMTP server details).
This command starts the server with hot-reloading using ts-node-dev.
npm run devThe server will be running at http://localhost:3001 (or the port you specified in .env).
To run the full test suite (unit and integration tests), use the following command:
npm testThis will execute all test files ending in .test.ts or .spec.ts.
The following environment variables are used to configure the application. They should be placed in a .env file in the project root.
| Variable | Description | Default Value |
|---|---|---|
PORT |
The port the server will listen on. | 3001 |
EMAIL_HOST |
The hostname of your SMTP server. | localhost |
EMAIL_PORT |
The port of your SMTP server. | 25 |
EMAIL_DEFAULT_FROM |
The default "from" address for outgoing emails. | "Pro App" <[email protected]> |
This project uses Swagger to automatically generate interactive API documentation from the in-code comments.
Once the server is running (npm run dev), you can access the API documentation at:
http://localhost:3001/api-docs
From there, you can view all available endpoints, see their request/response schemas, and even send test requests directly from your browser.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
Please read our CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests to us.
This project is licensed under the MIT License. See the LICENSE file for more details.
This README was generated with ❤️ and best practices.