Skip to content

EMAIL_NOTIFICATIONS_SETUP.md

Latest commit

 

History

History
212 lines (156 loc) · 7.04 KB

EMAIL_NOTIFICATIONS_SETUP.md

File metadata and controls

212 lines (156 loc) · 7.04 KB

Email Notifications Setup Guide

This guide explains how to set up email notifications for new config submissions using Proton Mail.

Overview

When a new config submission is created (GitHub issue with config-submission label), an automated email will be sent to notify the admin.

Features:

  • ✉️ HTML and plain text email formats
  • 🎨 Beautiful branded email template
  • ⚡ Instant notifications (triggered immediately)
  • 🔒 Secure SMTP via Proton Mail
  • 📊 Direct links to GitHub issue and admin dashboard

Prerequisites

  1. Proton Mail Account - You mentioned you have a paid Proton email
  2. Proton Mail Bridge or App Password - Required for SMTP access
  3. GitHub Repository Admin Access - To add secrets

Step 1: Get Proton Mail SMTP Credentials

Option A: Proton Mail Bridge (Recommended for Paid Accounts)

  1. Download and install Proton Mail Bridge
  2. Log in with your Proton account
  3. Bridge will provide you with:
    • SMTP server: 127.0.0.1 (local) or use smtp.protonmail.ch for cloud
    • Port: 587 (STARTTLS) or 465 (SSL)
    • Username: Your Proton email address
    • Password: Generated by Bridge (NOT your account password)

Option B: App-Specific Password (Alternative)

Proton Mail doesn't support traditional app passwords like Gmail. You need to use Bridge or configure SMTP directly.

SMTP Settings for Proton Mail:

  • Host: smtp.protonmail.ch
  • Port: 587 (STARTTLS) or 465 (SSL)
  • Encryption: TLS/STARTTLS
  • Username: Your full Proton email (e.g., admin@proton.me)
  • Password: Your Proton account password OR Bridge-generated password

⚠️ Security Note: Using your main account password is less secure. Proton Mail Bridge is strongly recommended.

Step 2: Add Secrets to GitHub Repository

  1. Go to your GitHub repository: https://github.com/yusufkaraaslan/skillseekersweb
  2. Navigate to Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Add the following secrets:
Secret Name Value Example
NOTIFICATION_EMAIL_HOST SMTP server address smtp.protonmail.ch
NOTIFICATION_EMAIL_PORT SMTP port 587
NOTIFICATION_EMAIL_USER Your Proton email notifications@proton.me
NOTIFICATION_EMAIL_PASSWORD Proton password or Bridge password your-secure-password
NOTIFICATION_EMAIL_TO Admin email to receive notifications youremail@proton.me

Example:

NOTIFICATION_EMAIL_HOST = smtp.protonmail.ch
NOTIFICATION_EMAIL_PORT = 587
NOTIFICATION_EMAIL_USER = skillseekers-bot@proton.me
NOTIFICATION_EMAIL_PASSWORD = ********** (from Bridge or account)
NOTIFICATION_EMAIL_TO = yusuf@proton.me

Step 3: Activate the Email Notification Workflow

The workflow template is already created but disabled (.yml.template extension).

To activate:

# Rename the template file to activate it
mv .github/workflows/email-notification-template.yml.template \
   .github/workflows/config-submission-email-notification.yml

# Commit and push
git add .github/workflows/config-submission-email-notification.yml
git commit -m "feat: Enable email notifications for config submissions"
git push origin master

Step 4: Test the Email Notification

  1. Create a test GitHub issue with the config-submission label
  2. The workflow should trigger automatically
  3. Check your email (defined in NOTIFICATION_EMAIL_TO)
  4. You should receive a formatted email with submission details

What the email includes:

  • Issue number and title
  • Author username
  • Submission timestamp
  • Direct link to GitHub issue
  • Direct link to admin dashboard
  • SLA reminder (48-hour review)

Email Template Preview

The email will look like this:

┌─────────────────────────────────────────┐
│   🔔 New Config Submission              │
│   Skill Seekers Admin Notification      │
└─────────────────────────────────────────┘

A new config submission has been received:

#123 Add React Documentation Config

👤 Author: @johndoe
📅 Submitted: 2026-01-17T12:00:00Z
⏱️ SLA: Review within 48 hours

[View GitHub Issue →] [Open Admin Dashboard →]

Next Steps:
1. Review the config in the GitHub issue
2. Verify all fields are correct
3. Approve ✅ or Reject ❌ via the admin dashboard

Troubleshooting

Email not received

Check:

  1. ✅ All GitHub secrets are correctly set
  2. ✅ Workflow file is renamed from .yml.template to .yml
  3. ✅ Issue has the config-submission label
  4. ✅ Check GitHub Actions tab for workflow run status
  5. ✅ Check spam folder

Authentication failed

Solution:

  • If using Proton Mail Bridge, make sure it's running
  • Verify SMTP credentials are correct
  • Try using port 465 with SSL instead of 587 with STARTTLS
  • Ensure password is from Bridge, not your account password

Workflow not triggering

Solution:

  • Check .github/workflows/ directory for the .yml file (not .yml.template)
  • Verify the workflow file is committed and pushed to master branch
  • Check GitHub Actions → Workflows to see if it's listed

SMTP connection timeout

Solution:

  • Verify NOTIFICATION_EMAIL_HOST is correct (smtp.protonmail.ch)
  • Check NOTIFICATION_EMAIL_PORT (use 587 for STARTTLS or 465 for SSL)
  • Ensure your network/firewall allows outbound SMTP connections

Security Best Practices

✅ DO:

  • Use Proton Mail Bridge for secure SMTP access
  • Store credentials in GitHub Secrets (never commit to code)
  • Use a dedicated email for notifications (e.g., skillseekers-bot@proton.me)
  • Enable 2FA on your Proton account
  • Regularly rotate passwords

❌ DON'T:

  • Hardcode email credentials in workflow files
  • Use your personal email password
  • Share GitHub secrets publicly
  • Commit .env files with credentials

Monitoring

View workflow runs:

  1. Go to GitHub repository
  2. Click Actions tab
  3. Click Email Notification for Config Submissions workflow
  4. See run history and logs

Disable notifications temporarily:

# Rename to disable
mv .github/workflows/config-submission-email-notification.yml \
   .github/workflows/config-submission-email-notification.yml.disabled

Alternative Notification Methods

If Proton Mail SMTP doesn't work, consider:

  1. Discord Webhook - Instant notifications to Discord channel (free, easy setup)
  2. Slack Webhook - Notifications to Slack workspace
  3. GitHub Mobile App - Native GitHub notifications (no setup required)
  4. SendGrid API - Dedicated email API service (free tier: 100 emails/day)

Support

If you encounter issues:

Last Updated: 2026-01-17 Status: ⏳ Template created, waiting for Proton email credentials to activate