🕊️ Pigeon — Simple Mailing Microservice

Pigeon is a lightweight, secure, and efficient mailing microservice built with Express.js and Nodemailer. It supports bulk and single email sending with batching, API key protection, and easy integration for any backend or event-driven workflow.

---

📑 Table of Contents

1. Overview
2. Tech Stack
3. Packages & Libraries
4. Getting Started
5. Setup
6. Features
7. API Reference
8. Demo & Screenshots
9. Acknowledgments
10. License

---

🌟 Overview

Pigeon provides a simple REST API for sending emails in bulk or individually. It is designed for reliability, scalability, and security, making it ideal for notifications, newsletters, and transactional email use cases.

---

🧠 Tech Stack

Layer	Tech
Language	TypeScript
Framework	Express.js
Mailer	Nodemailer
Docs	Swagger UI
Package Tool	Bun / npm
Editor	VS Code

---

📦 Packages & Libraries

• Express.js
• Nodemailer
• Swagger UI Express
• dotenv

---

🚀 Getting Started

Prerequisites:

• Node.js or Bun
• Git
• VS Code

---

⚙️ Setup

1. Clone the repository:

   git clone https://github.com/Atmiya-Developer-Students-Club/Pigeon.git

2. Navigate into the project:

   cd pigeon

3. Install dependencies:

   bun install # or npm install

4. Copy .env.example to .env and fill in your SMTP and API key settings.
5. Start the service:

   bun run index.ts # or npm start

6. Visit Swagger API docs at http://localhost:3001/api-docs

---

🎯 Features

• 📧 Send bulk emails with batching (configurable batch size & delay)
• 📩 Send single emails with the same API
• 🔑 API key protection for all endpoints
• 📝 Swagger UI for interactive API docs
• 🪵 Request and error logging
• ⚡ Simple, fast, and production-ready

---

📚 API Reference

Authentication

All endpoints require an Authorization: Bearer <API_KEY> header.

POST /bulk

Send emails to multiple recipients in batches.

Request Body:

{
  "subject": "Hello!",
  "html": "<b>Welcome!</b>",
  "recipients": ["user1@example.com", "user2@example.com"],
  "attachments": [
    {
      "filename": "poster.png",
      "href": "https://example.com/poster.png"
    }
  ]
}

Response:

{
  "success": true,
  "sent": 2,
  "failed": 0
}

POST /single

Send an email to a single recipient.

Request Body:

{
  "subject": "Hi!",
  "html": "<b>Just you!</b>",
  "recipients": ["user@example.com"],
  "attachments": [
    {
      "filename": "poster.png",
      "href": "https://example.com/poster.png"
    }
  ]
}

Response:

{
  "success": true,
  "sent": 1,
  "failed": 0
}

API Docs

Visit http://localhost:3001/api-docs for full Swagger documentation and live testing.

---

📸 Demo & Screenshots

To be added.

---

🙏 Acknowledgments

• Nodemailer Docs
• Express.js Docs
• Swagger UI

---

📜 License

This project is licensed under the MIT License.

---

Pigeon – Reliable, secure, and simple email delivery for your apps.