135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
# 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](https://myaccount.google.com/)
|
|
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](https://myaccount.google.com/)
|
|
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:
|
|
|
|
```env
|
|
# 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:
|
|
```bash
|
|
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.
|