Last updated: Jul 25, 2025, 10:08 AM UTC

Email System Complete Specifications and Architecture

Generated: 2025-01-25 17:30 UTC
Status: Complete
Verified:

Executive Summary

The Convert to Markdown email system uses Gmail API with Google Workspace domain-wide delegation to send transactional emails. The system is designed for secure API key delivery, user notifications, and future marketing communications. It supports both development and production environments with automatic failover to Google Secret Manager for credential management.

Current Implementation Status

Implemented Features

  1. Gmail API integration with domain-wide delegation
  2. Service account authentication with JWT
  3. Multi-environment credential management (local files, env vars, Secret Manager)
  4. HTML and plain text email templates
  5. Welcome emails for free and pro tiers
  6. API key secure delivery

Missing Features

  1. Email delivery tracking and analytics
  2. Bounce handling and retry logic
  3. Unsubscribe mechanism
  4. Email template management system
  5. Bulk email capabilities
  6. Email logging and monitoring

System Architecture

graph TB subgraph "Email System Architecture" A[Subscription Service] --> B[Email Service] B --> C{Environment} C -->|Development| D[Local Service Account File] C -->|Staging| E[Environment Variable] C -->|Production| F[Google Secret Manager] D --> G[Gmail API Client] E --> G F --> G G --> H[Google Workspace] H --> I[Domain-wide Delegation] I --> J[Send as lindsay@knowcode.tech] J --> K[User Inbox] end subgraph "Email Types" L[Welcome Email Free Tier] M[Welcome Email Pro Tier] N[API Key Delivery] O[Future: Usage Alerts] P[Future: Payment Receipts] end

Technical Specifications

1. Authentication Configuration

Service Account Setup

  • Service Account: gmail-sender@convert-to-markdown-us-east4.iam.gserviceaccount.com
  • Client ID: 116940581280353324169
  • Delegation Scope: https://www.googleapis.com/auth/gmail.send
  • Impersonation Email: lindsay@knowcode.tech

Credential Management Hierarchy

  1. Local Development: GMAIL_SERVICE_ACCOUNT_KEY env var pointing to JSON file
  2. Staging/CI: GMAIL_SERVICE_ACCOUNT_KEY_JSON env var with base64 encoded key
  3. Production: Google Secret Manager with key gmail-service-account-key

2. Email Service Implementation

Core Functions

// Main email sending function
async function sendEmail({ to, subject, text, html })

// Specialized email functions
async function sendWelcomeEmailFree(email, apiKey)
async function sendWelcomeEmailPro(email, apiKey)

Email Format

  • MIME Type: multipart/alternative
  • Encoding: UTF-8 for both text and HTML
  • From Header: Convert To Markdown <lindsay@knowcode.tech>
  • Reply-To: Same as From (future: support@convert-to-markdown.knowcode.tech)

3. Email Templates

Welcome Email - Free Tier

  • Subject: "Welcome to Convert To Markdown - Your API Key Inside! "
  • Key Elements:
    • API key display with security warning
    • Plan features (50 conversions, 5MB limit)
    • Quick start curl example
    • Upgrade CTA to Pro tier
    • Support contact information

Welcome Email - Pro Tier

  • Subject: "Welcome to Convert To Markdown Pro! "
  • Key Elements:
    • API key display with security warning
    • Pro benefits (10,000 conversions, 50MB limit)
    • Usage API and documentation links
    • Stripe customer portal link
    • Priority support information

4. Security Considerations

API Key Handling

  • Keys displayed once in email only
  • No storage of unhashed keys
  • Clear security warnings about key management
  • SHA-256 hashing for database storage

Email Security

  • TLS encryption via Gmail
  • Domain authentication (SPF, DKIM via Google)
  • No sensitive data beyond API keys
  • Rate limiting to prevent abuse

5. Error Handling

Current Implementation

if (error.code === 403) {
  // Domain-wide delegation not configured
  console.error('Permission denied. Check domain-wide delegation setup.');
  console.error('Client ID should be: 116940581280353324169');
}

Missing Error Scenarios

  • Network timeouts
  • Invalid email addresses
  • Gmail API quota exceeded
  • Service account key rotation
  • Secret Manager access failures

Future Enhancements

1. Email Types to Add

Usage Alert Emails

  • Threshold notifications (80%, 90%, 100% usage)
  • Monthly usage summary
  • Conversion failure notifications

Payment Emails

  • Subscription confirmation
  • Payment receipts
  • Failed payment notifications
  • Subscription cancellation confirmation

Marketing Emails

  • Feature announcements
  • Tips and best practices
  • Case studies and success stories

2. Infrastructure Improvements

Email Delivery Service

  • Add SendGrid or AWS SES as backup
  • Implement delivery tracking
  • Bounce and complaint handling
  • Email analytics system

Template Management

  • Database-stored templates
  • A/B testing capabilities
  • Personalization engine
  • Multi-language support

Monitoring and Logging

  • Email send success/failure metrics
  • Delivery rate tracking
  • Open and click tracking (with consent)
  • Detailed logging for debugging

3. Compliance Features

GDPR/Privacy

  • Unsubscribe links in all emails
  • Email preference center
  • Data retention policies
  • Consent management

Anti-Spam

  • List hygiene procedures
  • Bounce handling
  • Complaint feedback loops
  • Sending reputation monitoring

Implementation Roadmap

Phase 1: Current State

  • Basic transactional email sending
  • Welcome emails with API keys
  • Gmail API integration

Phase 2: Reliability (Q1 2025)

  • Add retry logic with exponential backoff
  • Implement email logging
  • Set up monitoring alerts
  • Add backup email service

Phase 3: Analytics (Q2 2025)

  • Delivery tracking
  • Basic analytics dashboard
  • A/B testing for templates
  • Performance metrics

Phase 4: Advanced Features (Q3 2025)

  • Email preference center
  • Advanced personalization
  • Automated campaigns
  • Multi-channel notifications (SMS, push)

Configuration Requirements

Environment Variables

# Required
GMAIL_SENDER_EMAIL=lindsay@knowcode.tech
GCP_PROJECT_ID=convert-to-markdown-us-east4

# Development only
GMAIL_SERVICE_ACCOUNT_KEY=/path/to/service-account.json

# Staging/CI only
GMAIL_SERVICE_ACCOUNT_KEY_JSON=base64_encoded_json

# Future
SENDGRID_API_KEY=your_sendgrid_key
EMAIL_TRACKING_ENABLED=true
EMAIL_RETRY_ATTEMPTS=3

Google Workspace Setup

  1. Enable Gmail API in GCP Console
  2. Create service account with domain-wide delegation
  3. Add delegation in Google Workspace Admin:
    • Client ID: 116940581280353324169
    • Scope: https://www.googleapis.com/auth/gmail.send
  4. Configure SPF and DKIM for domain

Monitoring and Metrics

Key Metrics to Track

  • Delivery Rate: Emails successfully delivered / total sent
  • Bounce Rate: Hard and soft bounces
  • Open Rate: For marketing emails only
  • API Key Activation: Keys used within 24 hours
  • Support Tickets: Email-related issues

Alerting Thresholds

  • Delivery rate < 95%
  • Bounce rate > 5%
  • Failed sends > 10 in 5 minutes
  • Gmail API quota > 80%

Security Best Practices

  1. Credential Rotation

    • Rotate service account keys quarterly
    • Update Secret Manager versions
    • Test in staging before production

  2. Access Control

    • Limit service account permissions
    • Use separate accounts for dev/prod
    • Audit access logs regularly

  3. Data Protection

    • No PII in email logs
    • Encrypt email content at rest
    • Implement data retention policies

Troubleshooting Guide

Common Issues

  1. 403 Permission Denied

    • Check domain-wide delegation setup
    • Verify Client ID matches
    • Ensure scope is correct

  2. Service Account Not Found

    • Check file path or environment variable
    • Verify Secret Manager permissions
    • Ensure service account exists

  3. Email Not Delivered

    • Check spam folders
    • Verify email address validity
    • Review Gmail API quotas

Conclusion

The email system provides a solid foundation for transactional emails with room for growth into a full-featured communication platform. Priority should be given to implementing retry logic, monitoring, and a backup email service to ensure reliable API key delivery for paying customers.