{"id":34791453,"url":"https://github.com/imsks/chitthi","last_synced_at":"2025-12-25T10:00:17.374Z","repository":{"id":297366957,"uuid":"996503742","full_name":"imsks/Chitthi","owner":"imsks","description":"Send emails without limits. Self-hosted. Built in Go.","archived":false,"fork":false,"pushed_at":"2025-10-19T05:05:34.000Z","size":48310,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"production","last_synced_at":"2025-10-19T17:04:52.006Z","etag":null,"topics":["apis","contribute","go","golang","opensource","opensource-projects","sendgrid"],"latest_commit_sha":null,"homepage":"https://chitthi-by-tbe.netlify.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imsks.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-05T03:37:12.000Z","updated_at":"2025-10-19T13:21:17.000Z","dependencies_parsed_at":"2025-06-05T07:16:17.139Z","dependency_job_id":"0846013f-6355-41b1-9e30-86e49281273e","html_url":"https://github.com/imsks/Chitthi","commit_stats":null,"previous_names":["imsks/chitthi"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/imsks/Chitthi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsks%2FChitthi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsks%2FChitthi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsks%2FChitthi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsks%2FChitthi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imsks","download_url":"https://codeload.github.com/imsks/Chitthi/tar.gz/refs/heads/production","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsks%2FChitthi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28026682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apis","contribute","go","golang","opensource","opensource-projects","sendgrid"],"created_at":"2025-12-25T10:00:02.795Z","updated_at":"2025-12-25T10:00:17.317Z","avatar_url":"https://github.com/imsks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📬 Chitthi\n\n[![Version](https://img.shields.io/badge/Version-v1.0.0-green.svg)](https://github.com/imsks/chitthi)\n[![Go Version](https://img.shields.io/badge/Go-1.24.3-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://docker.com)\n\nA lightweight, production-ready email microservice built in Go with **BYOK (Bring Your Own Key)** approach and multi-provider support.\n\n---\n\n## 📋 Table of Contents\n\n-   [Overview](#overview)\n-   [Features](#features)\n-   [Quick Start](#quick-start)\n-   [API Documentation](#api-documentation)\n-   [Email Providers](#email-providers)\n-   [Configuration](#configuration)\n-   [Development](#development)\n-   [Deployment](#deployment)\n-   [Contributing](#contributing)\n\n---\n\n## 🎯 Overview\n\nChitthi is a modern email microservice designed for developers who want simplicity without sacrificing power. Built with Go, it provides a clean REST API for sending emails through multiple providers while maintaining complete control over your API keys.\n\n### Key Benefits\n\n-   **🔐 BYOK Security**: Bring Your Own Key approach ensures your API keys stay secure\n-   **🔄 Multi-Provider**: Support for Breevo, SendGrid, MailerSend, and SMTP\n-   **⚡ Header-based Credentials**: Secure credential management via HTTP headers\n-   **🧠 Smart Routing**: Automatic provider detection based on credentials\n-   **📊 Comprehensive Logging**: PostgreSQL-based email tracking and analytics\n-   **🚀 Production Ready**: Redis caching, error handling, and monitoring\n\n---\n\n## ✨ Features\n\n-   ✅ **Multi-Provider Support**: Breevo, SendGrid, MailerSend, SMTP\n-   ✅ **BYOK (Bring Your Own Key)**: Users provide their own API keys\n-   ✅ **Header-based Credentials**: Secure credential management\n-   ✅ **Automatic Provider Detection**: Smart routing based on credentials\n-   ✅ **Redis Caching**: Performance optimization\n-   ✅ **PostgreSQL Logging**: Comprehensive email tracking\n-   ✅ **Docker Ready**: Containerized deployment\n-   ✅ **Production Ready**: Error handling, logging, monitoring\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n-   **Docker \u0026 Docker Compose**\n-   **Go 1.24.3+** (for development)\n-   **Node.js 18+** (for web frontend)\n-   **Git**\n\n### Option 1: Using the Development Script (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/imsks/chitthi.git\ncd chitthi\n\n# Run the development script\n./dev.sh\n\n# Or run specific commands\n./dev.sh full      # Full setup\n./dev.sh infra     # Start infrastructure only\n./dev.sh install   # Install web dependencies\n./dev.sh backend   # Start Go backend\n./dev.sh frontend  # Start web frontend\n```\n\n### Option 2: Manual Setup\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/imsks/chitthi.git\ncd chitthi\n```\n\n#### 2. Start Infrastructure\n\n```bash\n# Start Redis and PostgreSQL\ndocker compose up redis db -d\n```\n\n#### 3. Install Web Dependencies\n\n```bash\ncd web\nnpm install\ncd ..\n```\n\n#### 4. Run the Services\n\n```bash\n# Terminal 1: Start Go backend\ngo run cmd/main.go\n\n# Terminal 2: Start web frontend\ncd web\nnpm run dev\n```\n\n#### 5. Access the Applications\n\n-   **Backend API**: http://localhost:8080\n-   **Web Frontend**: http://localhost:3000\n-   **Documentation**: http://localhost:3000/docs\n-   **Quick Start Guide**: http://localhost:3000/quick-start\n\n#### 6. Test the API\n\n```bash\ncurl -X POST http://localhost:8080/send-email \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-SMTP-Host: smtp.gmail.com\" \\\n  -H \"X-SMTP-Port: 587\" \\\n  -H \"X-SMTP-Username: your-email@gmail.com\" \\\n  -H \"X-SMTP-Password: your-app-password\" \\\n  -H \"X-SMTP-From: your-email@gmail.com\" \\\n  -H \"X-SMTP-Use-TLS: true\" \\\n  -d '{\n    \"from_email\": \"sender@example.com\",\n    \"to_email\": \"recipient@example.com\",\n    \"subject\": \"Test Email\",\n    \"html_content\": \"\u003ch1\u003eHello World!\u003c/h1\u003e\"\n  }'\n```\n\n---\n\n## 📚 API Documentation\n\n### Endpoints\n\n| Method | Endpoint      | Description                 |\n| ------ | ------------- | --------------------------- |\n| `POST` | `/send-email` | Send email via any provider |\n| `GET`  | `/email-logs` | Retrieve email logs         |\n| `GET`  | `/`           | Health check                |\n\n### Send Email\n\n**Endpoint**: `POST /send-email`\n\n**Headers**:\n\n-   `Content-Type: application/json`\n-   `X-SMTP-*` (for SMTP)\n-   `X-SendGrid-API-Key` (for SendGrid)\n-   `X-Breevo-API-Key` (for Breevo)\n-   `X-MailerSend-API-Key` (for MailerSend)\n\n**Request Body**:\n\n```json\n{\n    \"from_email\": \"sender@example.com\",\n    \"from_name\": \"Sender Name\",\n    \"to_email\": \"recipient@example.com\",\n    \"to_name\": \"Recipient Name\",\n    \"subject\": \"Email Subject\",\n    \"html_content\": \"\u003ch1\u003eHello World!\u003c/h1\u003e\u003cp\u003eThis is a test email.\u003c/p\u003e\"\n}\n```\n\n**Response**:\n\n```json\n{\n    \"status\": true,\n    \"message\": \"Email sent successfully\",\n    \"data\": {\n        \"sent_to\": \"recipient@example.com\",\n        \"sent_from\": \"sender@example.com\",\n        \"subject\": \"Email Subject\",\n        \"provider\": \"smtp\",\n        \"log_saved\": true,\n        \"log_id\": 123\n    }\n}\n```\n\n### Get Email Logs\n\n**Endpoint**: `GET /email-logs`\n\n**Query Parameters**:\n\n-   `limit` (optional): Number of logs to return (default: 10)\n-   `offset` (optional): Number of logs to skip (default: 0)\n\n**Response**:\n\n```json\n{\n    \"status\": true,\n    \"data\": [\n        {\n            \"id\": 1,\n            \"recipient_email\": \"recipient@example.com\",\n            \"subject\": \"Test Email\",\n            \"provider\": \"smtp\",\n            \"status\": \"sent\",\n            \"created_at\": \"2024-01-01T12:00:00Z\"\n        }\n    ]\n}\n```\n\n---\n\n## 📧 Email Providers\n\n### Supported Providers\n\n| Provider       | Header Key             | Description               |\n| -------------- | ---------------------- | ------------------------- |\n| **SMTP**       | `X-SMTP-*`             | Direct SMTP with STARTTLS |\n| **SendGrid**   | `X-SendGrid-API-Key`   | SendGrid v3 API           |\n| **Breevo**     | `X-Breevo-API-Key`     | Breevo Email API          |\n| **MailerSend** | `X-MailerSend-API-Key` | MailerSend API            |\n\n### Provider Examples\n\n#### SendGrid\n\n```bash\ncurl -X POST http://localhost:8080/send-email \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-SendGrid-API-Key: your-sendgrid-api-key\" \\\n  -d '{\n    \"from_email\": \"sender@example.com\",\n    \"to_email\": \"recipient@example.com\",\n    \"subject\": \"Test Email\",\n    \"html_content\": \"\u003ch1\u003eHello World!\u003c/h1\u003e\"\n  }'\n```\n\n#### Breevo\n\n```bash\ncurl -X POST http://localhost:8080/send-email \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Breevo-API-Key: your-breevo-api-key\" \\\n  -d '{\n    \"from_email\": \"sender@example.com\",\n    \"to_email\": \"recipient@example.com\",\n    \"subject\": \"Test Email\",\n    \"html_content\": \"\u003ch1\u003eHello World!\u003c/h1\u003e\"\n  }'\n```\n\n#### MailerSend\n\n```bash\ncurl -X POST http://localhost:8080/send-email \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-MailerSend-API-Key: your-mailersend-api-key\" \\\n  -d '{\n    \"from_email\": \"sender@example.com\",\n    \"to_email\": \"recipient@example.com\",\n    \"subject\": \"Test Email\",\n    \"html_content\": \"\u003ch1\u003eHello World!\u003c/h1\u003e\"\n  }'\n```\n\n### Provider Priority\n\n1. **Header-based providers** (highest priority)\n2. **Request body API keys** (legacy support)\n3. **Environment-configured providers** (fallback)\n\n---\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```env\n# Server Configuration\nPORT=8080\n\n# Database Configuration\nDATABASE_URL=postgres://postgres:postgres@localhost:5432/chitthi?sslmode=disable\n\n# Redis Configuration\nREDIS_URL=redis://localhost:6543\n\n# Email Provider Configuration (Optional - for fallback)\nBREEVO_API_KEY=your_breevo_api_key\nSENDGRID_API_KEY=your_sendgrid_api_key\nSENDGRID_REGION=global\nMAILERSEND_API_KEY=your_mailersend_api_key\n\n# SMTP Configuration (Optional - for fallback)\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USERNAME=your-email@gmail.com\nSMTP_PASSWORD=your-app-password\nSMTP_FROM=your-email@gmail.com\nSMTP_USE_TLS=true\n```\n\n---\n\n## 🛠️ Development\n\n### Project Structure\n\n```\nchitthi/\n├── cmd/                    # Application entry point\n│   └── main.go\n├── internal/               # Core business logic\n│   ├── config/            # Configuration management\n│   ├── database/          # Database connections\n│   ├── email/             # Email provider implementations\n│   ├── handler/           # HTTP handlers\n│   ├── model/             # Data models\n│   └── modules/           # Business logic modules\n├── migrations/            # Database migrations\n├── docker-compose.yml     # Infrastructure setup\n├── Dockerfile            # Container configuration\n└── go.mod               # Go dependencies\n```\n\n### Development Commands\n\n```bash\n# Run with hot reload (requires air)\nair\n\n# Run directly\ngo run cmd/main.go\n\n# Run tests\ngo test ./...\n\n# Build for production\ngo build -o main cmd/main.go\n```\n\n### Database Migrations\n\n```bash\n# Run migrations\nmigrate -path migrations -database \"postgres://postgres:postgres@localhost:5432/chitthi?sslmode=disable\" up\n\n# Rollback migrations\nmigrate -path migrations -database \"postgres://postgres:postgres@localhost:5432/chitthi?sslmode=disable\" down\n```\n\n---\n\n## 🚀 Deployment\n\n### Docker Deployment\n\n```bash\n# Start all services\ndocker compose up --build\n\n# Run in background\ndocker compose up -d --build\n\n# View logs\ndocker compose logs -f\n```\n\n### Production Deployment\n\n```bash\n# Build production image\ndocker build -t chitthi-app .\n\n# Run with environment variables\ndocker run -p 8080:8080 \\\n  -e DATABASE_URL=\"postgres://...\" \\\n  -e REDIS_URL=\"redis://...\" \\\n  chitthi-app\n```\n\n### Production Checklist\n\n-   [ ] Set `APP_ENV=production`\n-   [ ] Configure database URLs\n-   [ ] Set API keys for email providers\n-   [ ] Set up Redis for caching\n-   [ ] Configure logging levels\n-   [ ] Set up monitoring and alerting\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these steps:\n\n### 1. Fork the Repository\n\n```bash\ngit clone https://github.com/imsks/chitthi.git\ncd chitthi\n```\n\n### 2. Create a Feature Branch\n\n```bash\ngit checkout -b feature/your-feature-name\n```\n\n### 3. Make Your Changes\n\n-   Follow the existing code style\n-   Add tests for new functionality\n-   Update documentation as needed\n\n### 4. Test Your Changes\n\n```bash\ngo test ./...\n```\n\n### 5. Submit a Pull Request\n\n-   Provide a clear description of your changes\n-   Include any relevant issue numbers\n-   Ensure all tests pass\n\n### Development Guidelines\n\n-   **Code Style**: Follow Go conventions\n-   **Documentation**: Update README and API docs\n-   **Testing**: Add tests for new features\n-   **Security**: Follow security best practices\n-   **Performance**: Consider performance implications\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🆘 Support\n\n### Getting Help\n\n1. **Check Documentation**: Review this README and API docs\n2. **Search Issues**: Look for similar issues in the repository\n3. **Create Issue**: Open a new issue with detailed information\n4. **Community**: Join our community discussions\n\n### Common Issues\n\n-   **Database Connection**: Ensure PostgreSQL is running and accessible\n-   **Email Delivery**: Check provider API keys and credentials\n-   **Redis Connection**: Verify Redis is running on the correct port\n\n### Contact\n\n-   **Email**: sachinkshuklaoo7@email.com\n-   **Issues**: [GitHub Issues](https://github.com/imsks/chitthi/issues)\n-   **Discussions**: [GitHub Discussions](https://github.com/imsks/chitthi/discussions)\n\n---\n\n## 🎯 Roadmap\n\n-   [ ] **Rate Limiting**: Redis-based rate limiting\n-   [ ] **Queue System**: RabbitMQ integration for async processing\n-   [ ] **Admin Dashboard**: Web interface for monitoring\n-   [ ] **Email Templates**: Template management system\n-   [ ] **Bulk Sending**: Support for bulk email operations\n-   [ ] **Analytics**: Email delivery analytics and reporting\n-   [ ] **Multi-tenant**: Support for multiple organizations\n\n---\n\n**Built with ❤️ by Sachin in 🇮🇳**\n\n_Chitthi - Empowering developers with simple email solutions_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsks%2Fchitthi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimsks%2Fchitthi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsks%2Fchitthi/lists"}