status.health logo status.health logo status.health

Newsletter System Setup Guide

Newsletter System Setup Guide

Overview

This guide will help you set up the private newsletter system for the status.health blog using GitHub private repository + encryption + SendGrid + Vercel.

Prerequisites

  1. GitHub account with ability to create private repositories
  2. SendGrid account (free tier is fine for starting)
  3. Vercel account (free tier works)
  4. Access to status.health blog repository

Step 1: Create Private GitHub Repository

  1. Go to GitHub and create a new private repository named newsletter-subscribers
  2. Initialize it with a README
  3. This will store encrypted subscriber emails

Step 2: Set Up SendGrid

  1. Sign up for SendGrid
  2. Create an API key:
    • Go to Settings → API Keys
    • Click “Create API Key”
    • Name it “status.health blog newsletter”
    • Give it “Full Access” permissions
    • Copy the API key (you’ll only see it once!)
  3. Set up sender authentication:
    • Go to Settings → Sender Authentication
    • Add domain: status.health
    • Follow DNS verification steps

Step 3: Generate Encryption Key

Run this command to generate a secure encryption key:

openssl rand -base64 32

Save this key securely - you’ll need it for the environment variables.

Step 4: Set Up GitHub Secrets

In your blog repository, go to Settings → Secrets and variables → Actions, and add:

Step 5: Deploy to Vercel

  1. Install Vercel CLI: 
    npm i -g vercel
  2. In the blog directory, run: 
    vercel

  3. Follow the prompts to link to your Vercel account

  4. Set environment variables in Vercel: 
    vercel env add GITHUB_TOKEN
vercel env add SENDGRID_API_KEY
vercel env add ENCRYPTION_KEY
vercel env add PRIVATE_REPO_NAME

Step 6: Configure DNS (if using custom domain)

In Vercel dashboard:

  1. Go to your project settings
  2. Add domain: blog.status.health
  3. Follow DNS configuration instructions

Step 7: Test the System

  1. Test subscription:
    • Go to your blog
    • Enter an email in the newsletter form
    • Check for:
      • Welcome email received
      • Email encrypted in private repo
      • Success animation on frontend
  2. Test unsubscribe:
    • Click unsubscribe link in welcome email
    • Verify subscriber marked as unsubscribed
  3. Test new post notification:
    • Create a test post in _posts/
    • Push to main branch
    • Check GitHub Actions log
    • Verify notification emails sent

Monitoring & Maintenance

Check subscriber count:

// Quick script to check subscribers
const { Octokit } = require('@octokit/rest');
const octokit = new Octokit({ auth: 'YOUR_GITHUB_TOKEN' });

async function getSubscriberCount() {
  const { data } = await octokit.repos.getContent({
    owner: 'statusdothealth',
    repo: 'newsletter-subscribers',
    path: 'subscribers.json'
  });
  
  const content = Buffer.from(data.content, 'base64').toString();
  const subscribers = JSON.parse(content);
  const active = Object.values(subscribers).filter(s => s.status === 'active').length;
  
  console.log(`Active subscribers: ${active}`);
}

SendGrid Dashboard:

Privacy Compliance:

Troubleshooting

Emails not sending:

  1. Check SendGrid API key is valid
  2. Verify sender authentication
  3. Check GitHub Action logs
  4. Ensure environment variables are set

Subscription not working:

  1. Check browser console for errors
  2. Verify Vercel deployment is live
  3. Check API endpoint logs in Vercel
  4. Ensure CORS headers are correct
  1. Verify encryption key matches
  2. Check token generation logic
  3. Ensure subscriber ID exists

Security Best Practices

  1. Rotate encryption key every 6 months
  2. Audit access to private repo regularly
  3. Monitor for suspicious subscription patterns
  4. Keep dependencies updated
  5. Review logs for unauthorized access attempts

Support

For issues or questions: