📜 MailMyCertificate

Generate and send professional certificates in minutes — mostly in your browser.

Open-source, privacy-first certificate automation for hackathons, educators, and event organizers.
Upload a template → Add participants (CSV or Google Sheets) → Place fields → Generate PDFs → Download ZIP or send via Gmail.

Live site • Features • Architecture • Getting Started • Deployment • Roadmap

MailMyCertificate is a full certificate workflow: design on a visual canvas, batch-generate PDFs client-side, then optionally send them through your own Gmail account via Google OAuth.

Production: mailmycertificate.tech

Created by Akshat Thakur, a software developer building web applications and tools that solve real problems.

If you like MailMyCertificate, you might also find these useful:

• SafeExam — Online examination platform
• Calcuzy — Productivity and calculation tool
• Priya Sarv Utthan — Platform for a non-profit organization

Connect on GitHub • LinkedIn • Twitter/X

Also: SEO metadata, JSON-LD, sitemap, PWA manifest, service worker (static assets), Vercel Analytics.

┌──────────────────────────────────────────────────────────────────────────┐
│                         Browser (Next.js 16)                              │
│  /tool  → Wizard (Zustand + Dexie IDB) → Web Worker → pdf-lib → ZIP      │
│  /email → Gmail composer → fetch('/api/...', credentials: 'include')       │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │  /api/*  (Vercel Services)
                                ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                    Flask backend (api/index.py)                           │
│  GET  /api/auth/login      → Google OAuth URL                             │
│  GET  /api/auth/callback   → Exchange code, session + CSRF                  │
│  GET  /api/auth/status     → Connected Gmail + csrf_token sync              │
│  POST /api/send-email      → Gmail API send (PDF attachment)                │
│  POST /api/sheets/import   → Google Sheets CSV fetch                        │
└──────────────────────────────────────────────────────────────────────────┘

Vercel routing (vercel.json): Next.js at /, Flask at /api via experimentalServices.

Local dev: next.config.ts rewrites /api/* → http://localhost:8000 when NODE_ENV=development.

MailMyCertificate/
├── api/
│   ├── index.py              # Flask app (OAuth, send-email, sheets)
│   └── site_config.py        # APP_URL, CORS, redirect URI helpers
├── public/
│   ├── logo.png              # Brand asset
│   ├── icon-192.png, icon-512.png, favicon-48.png
│   ├── manifest.json         # PWA
│   └── sw.js                 # Service worker (static cache; skips /api)
├── src/
│   ├── app/                  # Routes (/, /tool, /email, /guide, …)
│   ├── views/                # Page-level views
│   ├── components/           # UI, wizard, email, session, seo, guide
│   ├── core/
│   │   ├── db/schema.ts      # Dexie tables
│   │   ├── session/          # Session manager + recovery
│   │   ├── queue/            # Email queue
│   │   └── worker/           # PDF generation worker
│   ├── services/             # template, csv, email, sheets, zip, pdf
│   ├── store/useAppStore.ts  # Zustand + temporal + persist
│   ├── config/site.ts        # Public URL helpers (frontend)
│   └── lib/                  # metadata, SEO, structured data
├── vercel.json               # Next + Flask services
├── requirements.txt          # Python dependencies
├── next.config.ts
└── .env.example

• Node.js ≥ 18
• Python ≥ 3.10 (for local Gmail API)
• Google Cloud OAuth client (Web) with Gmail API enabled

git clone https://github.com/akshatthakur22/MailMyCertficate.git
cd MailMyCertficate
npm install
pip install -r requirements.txt

Copy .env.example → .env.local and fill in:

NEXT_PUBLIC_APP_URL=http://localhost:3000
APP_URL=http://localhost:3000
FLASK_SECRET_KEY=<random-hex>
GOOGLE_CREDENTIALS_JSON={"web":{...,"redirect_uris":["http://localhost:3000/api/auth/callback"]}}

In Google Cloud Console → OAuth client → add:

• Authorized JavaScript origins: http://localhost:3000
• Authorized redirect URIs: http://localhost:3000/api/auth/callback

For production, also add https://mailmycertificate.tech and
https://mailmycertificate.tech/api/auth/callback.

Terminal A — Flask API (port 8000):

python api/index.py

Terminal B — Next.js:

npm run dev

Open http://localhost:3000. Gmail connect and send only work when both are running.

Alternatively, with the Vercel CLI: vercel dev -L runs frontend + backend together.

1. Import the GitHub repo on Vercel.
2. Set Production environment variables:

3. Ensure vercel.json uses experimentalServices (already in repo).
4. Redeploy after env changes.

Checklist after deploy

• GET /api/auth/login returns JSON with authorization_url (not HTML 500).
• redirect_uri in that URL matches Google Console exactly.
• Connect Gmail on /email, then send a test message.

1. User clicks Connect Gmail → /api/auth/login → Google OAuth.
2. Callback → /api/auth/callback stores tokens in an encrypted Flask session cookie.
3. Frontend syncs CSRF token from redirect URL + /api/auth/status.
4. Each send: POST /api/send-email with credentials: 'include', X-CSRF-Token, and PDF attachment (multipart).

Tokens stay on the server session; certificate bytes are read from IndexedDB and only sent when you hit Send.

• Gmail OAuth + send via Flask on Vercel
• IndexedDB sessions + recovery
• Google Sheets import
• Undo/redo, preview modal, email send UI
• SEO, PWA, settings / legal pages

• Custom font embedding in PDFs (beyond Helvetica)
• Personalized ZIP filenames from CSV columns
• Stronger CSV validation (duplicates, email column hints)
• Dark mode
• Automated tests (unit + E2E)
• Rate-limit UX for large Gmail batches

1. Fork the repo
2. Create a branch (git checkout -b feature/your-feature)
3. Commit and push
4. Open a Pull Request

Issues and PRs are welcome.

MIT License — see LICENSE if present in the repo root.

Built with dedication by Akshat Thakur using:

• pdf-lib · PapaParse · JSZip
• Zustand · Dexie · Next.js · Flask
• Tailwind CSS · TypeScript · React

Thanks to the open-source community for tools that make this possible.

Built with ❤ by Akshat Thakur

If you're looking to fork, customize, or contribute to MailMyCertificate:

• Check out the /for-developers page (coming soon) for architecture deep-dive and customization guide
• Read CONTRIBUTING.md for development workflow, code style, and PR process
• Review GitHub Issues for bugs and feature requests
• Join the discussion on Discussions or email via GitHub profile

Why fork MailMyCertificate?

• You don't need to build certificate generation + Gmail integration from scratch
• The entire workflow is open and transparent — no black box
• Deploy to your own infrastructure (Vercel, self-hosted, Docker)
• Customize fields, styling, or logic to fit your specific workflow