Email Troubleshooting Guide

Generated: 2025-07-25 08:30 UTC
Status: Complete
Verified:

Overview

This guide documents the troubleshooting process for Gmail API email delivery issues in the Convert to Markdown service.

Issue Description

• Problem: Welcome emails with API keys are not being delivered to users
• Symptom: Emails appear to bounce back to the sender's Gmail account
• Environment: Google Cloud Functions (production)

Root Cause Analysis

1. Local Testing Results

Testing the email functionality locally shows successful delivery:

node test-email.js
# Result: Email sent successfully with Message ID: 19840aabf8d1fdc8

This confirms:

• Gmail API is configured correctly
• Service account credentials are valid
• Domain-wide delegation is working
• Email sending code is functional

2. Production Environment Issue

The issue appears to be specific to the production environment on Google Cloud Functions.

Production Configuration Requirements

1. Service Account Key Management

The email system expects the Gmail service account key in one of three ways:

1. Local Development: File path via GMAIL_SERVICE_ACCOUNT_KEY environment variable
2. Environment Variable: Base64-encoded JSON via GMAIL_SERVICE_ACCOUNT_KEY_JSON
3. Google Secret Manager: Automatic retrieval using default credentials

2. Current Production Setup

The deployment uses .env.prod for environment variables, but the Gmail service account key is NOT included there for security reasons.

Solution: Configure Gmail Service Account in Production

Option 1: Use Google Secret Manager (Recommended)

1. Create the secret in Google Cloud:

# Convert the service account key to base64
base64 -i deploy-gcp/keys/gmail-service-account.json | tr -d '\n' > gmail-key-base64.txt

# Create the secret
gcloud secrets create gmail-service-account-key \
  --data-file=gmail-key-base64.txt \
  --project=convert-to-markdown-us-east4 \
  --replication-policy=automatic

# Clean up
rm gmail-key-base64.txt

2. Grant access to the Cloud Function service account:

# Get the service account email
SERVICE_ACCOUNT=$(gcloud functions describe convert-api --region=us-east4 --format="value(serviceConfig.serviceAccountEmail)")

# Grant access to the secret
gcloud secrets add-iam-policy-binding gmail-service-account-key \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor" \
  --project=convert-to-markdown-us-east4

Option 2: Use Environment Variable

Add to .env.prod:

# Convert to base64
GMAIL_SERVICE_ACCOUNT_KEY_JSON=$(base64 -i deploy-gcp/keys/gmail-service-account.json | tr -d '\n')

Then redeploy the function.

Verification Steps

1. Check Cloud Function logs:

gcloud functions logs read convert-api --region=us-east4 --limit=50 | grep -i "email"

2. Test the signup endpoint:

curl -X POST https://convert-to-markdown.knowcode.tech/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

3. Monitor logs during signup:

gcloud functions logs read convert-api --region=us-east4 --limit=20 --format=json | jq '.textPayload' | grep -i "email"

Enhanced Logging

The email system now includes detailed logging:

• [EMAIL] Getting service account key... - Shows key retrieval process
• [EMAIL] Environment: - Shows if running in production
• [EMAIL] Has GMAIL_SERVICE_ACCOUNT_KEY: - Shows if file path is set
• [EMAIL] Has GMAIL_SERVICE_ACCOUNT_KEY_JSON: - Shows if base64 key is set
• [EMAIL] Attempting to send welcome email to: - Shows email send attempts
• [EMAIL] Successfully sent welcome email to - Confirms successful delivery
• [EMAIL] Failed to send welcome email to - Shows error details

Common Issues and Solutions

1. "Could not load the default credentials"

Cause: Service account key not available in production
Solution: Implement one of the configuration options above

2. "Permission denied (403)"

Cause: Domain-wide delegation not configured properly
Solution: Verify OAuth scopes and client ID in Google Workspace admin

3. Emails bounce back

Cause: Usually indicates authentication or permission issues
Solution: Check service account configuration and Gmail API setup

Next Steps

1. Implement Google Secret Manager solution (recommended)
2. Redeploy the Cloud Function
3. Test email delivery in production
4. Monitor logs for successful delivery

Security Notes

• Never commit service account keys to version control
• Use Secret Manager for production environments
• Rotate service account keys periodically
• Monitor usage for suspicious activity