www_ourworld_new/docs/gmail-setup-guide.md

Gmail Contact Form Setup Guide

This guide will help you configure your contact form to send emails to your company Gmail inbox.

Prerequisites

• A Gmail account for your company
• Access to Google Account settings
• Basic understanding of environment variables

Step 1: Enable 2-Factor Authentication

1. Go to Google Account Settings
2. Navigate to Security → 2-Step Verification
3. Follow the prompts to enable 2FA if not already enabled
4. Note: App passwords require 2FA to be enabled

Step 2: Generate Gmail App Password

1. Go to Google Account Settings
2. Navigate to Security → 2-Step Verification → App passwords
3. Select Mail as the app and Other as the device
4. Enter "OurWorld Contact Form" as the device name
5. Click Generate
6. Important: Copy the 16-character app password immediately (you won't see it again)

Step 3: Configure Environment Variables

1. Open the .env.local file in your project root
2. Replace the placeholder values with your actual credentials:

# Your Gmail address (the one that will send emails)
GMAIL_USER=your-company-email@gmail.com

# The 16-character app password you generated (no spaces)
GMAIL_APP_PASSWORD=abcdabcdabcdabcd

# Email address where contact form submissions will be sent
COMPANY_EMAIL=info@ourworld.tf

Step 4: Security Considerations

Environment Variables

• Never commit .env.local to version control
• The .env.local file is already in .gitignore
• Use different environment variables for production deployment

Production Deployment

For production (Vercel, Netlify, etc.), add these environment variables in your hosting platform's dashboard:

• GMAIL_USER
• GMAIL_APP_PASSWORD
• COMPANY_EMAIL

Step 5: Testing the Setup

1. Start your development server:

   npm run dev
   

2. Navigate to /contact page

3. Fill out and submit the contact form

4. Check your Gmail inbox for the contact form submission

Troubleshooting

Common Issues

"Authentication failed" error:

• Verify 2FA is enabled on your Google account
• Double-check the app password (no spaces, 16 characters)
• Ensure you're using the app password, not your regular Gmail password

"Invalid credentials" error:

• Verify the GMAIL_USER email address is correct
• Check that the app password is correctly copied

Emails not being received:

• Check your spam/junk folder
• Verify the COMPANY_EMAIL address is correct
• Test with a different recipient email

"Module not found" error:

• Ensure nodemailer is installed: npm install nodemailer @types/nodemailer

Email Format

The contact form sends emails with:

• Subject: "New Contact Form Submission from [First Name] [Last Name]"
• From: Your Gmail address (GMAIL_USER)
• To: Company email address (COMPANY_EMAIL)
• Content: Formatted HTML and plain text versions

Security Best Practices

1. Use App Passwords: Never use your main Gmail password
2. Limit Access: Only share credentials with necessary team members
3. Regular Rotation: Consider rotating app passwords periodically
4. Monitor Usage: Check Gmail's security activity regularly
5. Environment Separation: Use different credentials for development/production

Alternative Solutions

If you prefer not to use Gmail directly, consider these alternatives:

1. EmailJS: Client-side email service
2. Formspree: Form handling service
3. SendGrid: Professional email API
4. Mailgun: Email delivery service
5. Resend: Modern email API

Support

If you encounter issues:

1. Check the browser console for error messages
2. Review the server logs for API errors
3. Verify all environment variables are set correctly
4. Test with a simple email first

File Structure

project/
├── .env.local                 # Environment variables (not in git)
├── src/app/api/contact/       # API route for form submission
├── src/components/ContactHero.tsx  # Contact form component
└── docs/gmail-setup-guide.md # This guide

---

Important: Keep your app password secure and never share it publicly. If compromised, revoke it immediately in your Google Account settings and generate a new one.