{"id":46051305,"url":"https://github.com/pgokul695/protopost","last_synced_at":"2026-03-01T09:01:42.576Z","repository":{"id":340164914,"uuid":"1163717695","full_name":"pgokul695/ProtoPost","owner":"pgokul695","description":"Hackathon-ready email gateway — swap providers, debug sends, and mock emails without touching your app code. Built-in dashboard, sandbox mode, automatic failover, and support for Gmail, Resend, Mailtrap \u0026 custom SMTP.","archived":false,"fork":false,"pushed_at":"2026-02-23T15:05:09.000Z","size":324,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-23T23:02:56.447Z","etag":null,"topics":["email","email-gateway","gmail","hackathon","python","smtp"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgokul695.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2026-02-22T03:08:23.000Z","updated_at":"2026-02-23T16:53:53.000Z","dependencies_parsed_at":"2026-02-23T23:03:07.330Z","dependency_job_id":null,"html_url":"https://github.com/pgokul695/ProtoPost","commit_stats":null,"previous_names":["pgokul695/protopost"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pgokul695/ProtoPost","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgokul695%2FProtoPost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgokul695%2FProtoPost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgokul695%2FProtoPost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgokul695%2FProtoPost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgokul695","download_url":"https://codeload.github.com/pgokul695/ProtoPost/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgokul695%2FProtoPost/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29965419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T06:55:38.174Z","status":"ssl_error","status_checked_at":"2026-03-01T06:53:04.810Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["email","email-gateway","gmail","hackathon","python","smtp"],"created_at":"2026-03-01T09:01:41.902Z","updated_at":"2026-03-01T09:01:42.564Z","avatar_url":"https://github.com/pgokul695.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Python](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-MIT-green)\n![Platform](https://img.shields.io/badge/Works%20on-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)\n![Hackathon Ready](https://img.shields.io/badge/Hackathon-Ready-brightgreen)\n\n# 📧 ProtoPost — Hackathon Email Gateway\n\nA local email proxy that lets you switch providers, mock sends, and debug emails — without touching your app code.\n\n---\n\n## Why this exists\n\nBuilding at a hackathon and need email working in the next hour? You've got two problems: setting up an email provider is annoying, and debugging why your emails aren't sending is even more annoying.\n\nProtoPost solves both. Run one server locally, point your app at it, and you get:\n\n- A dashboard to see every email your app tries to send\n- Sandbox mode that captures emails without sending anything (great for testing)\n- Automatic switching to a backup provider if your primary one fails\n- Support for Resend, Mailtrap, Gmail, and any custom SMTP server\n\n---\n\n## Dashboard Preview\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  📧 ProtoPost               [SANDBOX MODE: OFF  ○──────●  ON]  │\n├─────────────────────────────────────────────────────────────────┤\n│  [Outbox \u0026 Logs]  [Providers]  [Routing]  [Test Send]           │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                  │\n│   Total Sent   Failed   Sandbox   Avg Time                      │\n│      142          2        58      340ms                        │\n│                                                                  │\n│  Timestamp    To                Subject         Provider  Status │\n│  12:04:32     user@example.com  Welcome!        Resend    ✓     │\n│  12:03:11     test@test.com     Reset link      Resend    ✓     │\n│  12:01:44     admin@co.com      Alert: down     [sandbox] 📦   │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Quick Start\n\n\u003e **Prefer Docker?** Skip the Python setup entirely — see [docs/DOCKER.md](docs/DOCKER.md).  \n\u003e **Need a shared team URL?** Deploy to Render or Railway — see [docs/HOSTING.md](docs/HOSTING.md).\n\n### Requirements\n\n- Nothing. Just a working computer.\n- (For the developer path: Python 3.11+)\n\n## Option A — Download \u0026 Run (Recommended, no Python needed)\n\n1. Go to the [Releases page](https://github.com/pgokul695/ProtoPost/releases) and\n   download the binary for your OS:\n     - Windows → `ProtoPost-windows.exe`\n     - macOS → `ProtoPost-macos`\n     - Linux → `ProtoPost-linux`\n\n2. Double-click it (or run it from your terminal).\n\n3. First launch only: a short wizard asks for your port (default: 8000) and an\n   optional auth token. Press Enter twice to accept all defaults.\n\n4. Your browser opens to the dashboard automatically.\n\nThat's it. No Python, no pip, no config files.\n\n\u003e **macOS users:** If macOS blocks the file, right-click → Open → Open.\n\u003e This is a one-time Gatekeeper prompt for unsigned binaries.\n\n## Option B — Run from Source (Developers)\n\nRequires Python 3.11+.\n\n```\ngit clone https://github.com/pgokul695/ProtoPost.git\ncd ProtoPost\npip install -r requirements.txt\nuvicorn backend.main:app --reload --port 8000\n```\n\nThen open http://localhost:8000.\n\n---\n\n## What you can do\n\n| Feature | What it means for you |\n|---|---|\n| Sandbox Mode | Emails get captured, never sent. Safe for testing. |\n| Provider Switching | Change from Resend to Gmail in 2 clicks. No code changes. |\n| Automatic Failover | If Resend fails, it tries Gmail automatically. |\n| Load Balancing | Split traffic 70/30 across two providers. |\n| Email Logs | See every email your app sent, with full payload. |\n| Zero App Changes | Your app keeps calling the same endpoint. |\n| Setup Wizards | Guided steps for Gmail and Resend setup — built into the UI. |\n\n---\n\n## How to send an email\n\nPoint your app at `POST http://localhost:8000/api/send`:\n\n```json\n{\n  \"from\": \"you@yourdomain.com\",\n  \"to\": [\"recipient@example.com\"],\n  \"subject\": \"Hello!\",\n  \"body_html\": \"\u003ch1\u003eIt works\u003c/h1\u003e\",\n  \"body_text\": \"It works\"\n}\n```\n\nThat's the only integration step. Your app never needs to know which provider is in use.\n\n---\n\n## Architecture\n\n```\nYour App Code\n     │\n     │  POST /api/send  (JSON payload)\n     ▼\n┌─────────────────────────────┐\n│    ProtoPost Server         │  ← runs at localhost:8000\n│                             │\n│  ┌─────────────────────┐    │\n│  │   config.json       │    │  ← updated live from dashboard\n│  └────────┬────────────┘    │\n│           │                 │\n│  ┌────────▼────────────┐    │\n│  │   Routing Engine    │    │\n│  │                     │    │\n│  │  Sandbox? → Log it  │    │\n│  │  Manual  → Weighted │    │\n│  │  Smart   → Failover │    │\n│  └────────┬────────────┘    │\n│           │                 │\n└───────────┼─────────────────┘\n            │\n    ┌───────┴────────┐\n    │                │\n    ▼                ▼\n  Resend API    Custom SMTP      ... (any configured provider)\n```\n\nThe server reads `config.json` on every request. Change a provider in the dashboard and the next email uses it — no restart needed.\n\n---\n\n## Documentation\n\n| Doc | What's in it |\n|---|---|\n| [Releases page](https://github.com/pgokul695/ProtoPost/releases) | Download the executable for your OS — start here |\n| [docs/HACKATHON_QUICKSTART.md](docs/HACKATHON_QUICKSTART.md) | Get email working in 5 minutes — start here if you're in a hurry |\n| [docs/PROVIDERS.md](docs/PROVIDERS.md) | How to set up Resend, Mailtrap, Gmail, and custom SMTP |\n| [docs/ROUTING.md](docs/ROUTING.md) | Load balancing and failover explained |\n| [docs/API.md](docs/API.md) | Full REST API reference with code examples |\n| [docs/SANDBOX.md](docs/SANDBOX.md) | Sandbox mode — what it does and when to use it |\n| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Exact fixes for the most common errors |\n| [docs/DOCKER.md](docs/DOCKER.md) | Run with Docker — one command, no Python install needed |\n| [docs/HOSTING.md](docs/HOSTING.md) | All cloud hosting options compared (Render, Railway, Fly.io, VPS, and more) |\n| [docs/RENDER.md](docs/RENDER.md) | Step-by-step guide: deploy to Render with persistent storage |\n| [docs/RAILWAY.md](docs/RAILWAY.md) | Step-by-step guide: deploy to Railway with persistent storage |\n| [docs/AUTH.md](docs/AUTH.md) | Authentication — generating tokens, app integration (Python / JS / Node examples) |\n\n---\n\n## Project Structure\n\n```\nprotopost/\n├── backend/\n│   ├── main.py              # FastAPI app + all endpoints\n│   ├── router.py            # Routing logic + load balancing\n│   ├── config_manager.py    # config.json read/write\n│   ├── database.py          # SQLite operations\n│   ├── providers.py         # Email sending implementations\n│   └── models.py            # Pydantic schemas\n├── frontend/\n│   └── dashboard.html       # Complete single-file SPA\n├── docs/                    # This documentation suite\n├── config.json              # Runtime configuration (auto-created)\n├── emails.db                # SQLite database (auto-created)\n└── requirements.txt         # Python dependencies\n```\n\n---\n\n## Creators\n\n| Name | Role | Website | Email |\n|---|---|---|---|\n| Gokul P | Developer | [gokulp.in](https://gokulp.in) | [me@gokulp.in](mailto:me@gokulp.in) |\n| Devika P Sajith | QA | [devikapsajith.netlify.app](https://devikapsajith.netlify.app/) | [devikasajith710@gmail.com](mailto:devikasajith710@gmail.com) |\n\n---\n\n## License\n\nMIT — use it however you want, including at your hackathon.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) if you want to add a provider or fix something.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgokul695%2Fprotopost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgokul695%2Fprotopost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgokul695%2Fprotopost/lists"}