> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugged.in/llms.txt
> Use this file to discover all available pages before exploring further.
# Email Testing Guide
> Test email functionality using Mailtrap and other services
# Email Testing
This guide explains how to test email functionality in Plugged.in using [Mailtrap](https://mailtrap.io) for development and staging environments.
## Quick Setup with Mailtrap
Sign up for a free account at [Mailtrap.io](https://mailtrap.io)
Navigate to **Inboxes** → Select inbox → **SMTP Settings** → Choose **Nodemailer**
```env theme={null}
EMAIL_SERVER_HOST=sandbox.smtp.mailtrap.io
EMAIL_SERVER_PORT=2525
EMAIL_SERVER_USER=your-mailtrap-username
EMAIL_SERVER_PASSWORD=your-mailtrap-password
EMAIL_FROM=noreply@plugged.in
EMAIL_FROM_NAME=Plugged.in
```
```bash theme={null}
curl -X POST http://localhost:12005/api/auth/test-email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-admin-secret' \
-d '{"email": "test@example.com"}'
```
## Email Templates
Plugged.in includes responsive HTML email templates for various notifications:
Sent when users register to verify their email address
Sent when users request a password reset
Activity alerts and system notifications
Onboarding email for new users
## Development Setup
### 1. Install Dependencies
Ensure email dependencies are installed:
```bash theme={null}
pnpm install nodemailer @types/nodemailer
```
### 2. Configure Mailtrap
1. Log into [Mailtrap Dashboard](https://mailtrap.io)
2. Navigate to **Inboxes**
3. Click on your inbox
4. Copy SMTP credentials
5. Select **Nodemailer** integration
```bash theme={null}
# Get API token from Mailtrap settings
curl -X GET "https://mailtrap.io/api/v1/inboxes" \
-H "Api-Token: your-api-token"
```
### 3. Environment Configuration
Create or update `.env.local`:
```env theme={null}
# Mailtrap Settings
EMAIL_SERVER_HOST=sandbox.smtp.mailtrap.io
EMAIL_SERVER_PORT=2525
EMAIL_SERVER_USER=your-username
EMAIL_SERVER_PASSWORD=your-password
# Email Configuration
EMAIL_FROM=noreply@plugged.in
EMAIL_FROM_NAME=Plugged.in
ENABLE_EMAIL_VERIFICATION=true
# Admin Secret for Testing
ADMIN_SECRET=your-secret-key
```
### 4. Test Email Functionality
#### Using Application Forms
* **Password Reset**: Visit `/forgot-password`
* **User Registration**: Visit `/register`
* **Email Verification**: Complete registration flow
#### Using Test Endpoint
```bash theme={null}
# Test email delivery
curl -X POST http://localhost:12005/api/auth/test-email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-admin-secret' \
-d '{
"email": "test@example.com",
"subject": "Test Email",
"template": "verification"
}'
```
## Email Template Customization
### Template Structure
All email templates follow this structure:
```html theme={null}
```
### Customizing Templates
Edit email templates in `lib/email.ts`:
```typescript theme={null}
// lib/email.ts
export const emailTemplates = {
verification: (token: string) => ({
subject: 'Verify your email',
html: generateTemplate({
title: 'Email Verification',
content: `Click below to verify your email`,
buttonText: 'Verify Email',
buttonUrl: `${process.env.NEXTAUTH_URL}/verify?token=${token}`
})
}),
passwordReset: (token: string) => ({
subject: 'Reset your password',
html: generateTemplate({
title: 'Password Reset',
content: `Click below to reset your password`,
buttonText: 'Reset Password',
buttonUrl: `${process.env.NEXTAUTH_URL}/reset-password?token=${token}`
})
})
};
```
### Logo Customization
Logos are embedded as base64 to ensure display even when images are blocked.
Replace the logo:
```typescript theme={null}
// Convert logo to base64
const logoBase64 = fs.readFileSync('logo.png').toString('base64');
// Update in lib/email.ts
const DEFAULT_LOGO_BASE64 = `data:image/png;base64,${logoBase64}`;
```
**Logo Guidelines:**
* Maximum size: 30KB (to avoid email size issues)
* Recommended dimensions: 200x50px
* Format: PNG with transparency or JPEG
* Optimize before converting to base64
## Testing Strategies
### Unit Testing
```typescript theme={null}
// tests/email.test.ts
import { sendEmail } from '@/lib/email';
import { vi, describe, it, expect } from 'vitest';
describe('Email Service', () => {
it('should send verification email', async () => {
const mockTransport = {
sendMail: vi.fn().mockResolvedValue({ messageId: '123' })
};
const result = await sendEmail({
to: 'test@example.com',
subject: 'Test',
html: 'Test
'
});
expect(mockTransport.sendMail).toHaveBeenCalled();
expect(result.messageId).toBe('123');
});
});
```
### Integration Testing
```typescript theme={null}
// tests/email.integration.test.ts
describe('Email Integration', () => {
it('should deliver to Mailtrap', async () => {
const response = await fetch('/api/auth/test-email', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.ADMIN_SECRET}`
},
body: JSON.stringify({
email: 'integration@test.com'
})
});
expect(response.status).toBe(200);
// Verify in Mailtrap API
const mailtrapMessages = await checkMailtrap();
expect(mailtrapMessages).toContainEmail('integration@test.com');
});
});
```
## Production Email Services
### Supported Providers
```env theme={null}
EMAIL_SERVER_HOST=smtp.sendgrid.net
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER=apikey
EMAIL_SERVER_PASSWORD=your-sendgrid-api-key
```
```env theme={null}
EMAIL_SERVER_HOST=email-smtp.us-east-1.amazonaws.com
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER=your-smtp-username
EMAIL_SERVER_PASSWORD=your-smtp-password
```
```env theme={null}
EMAIL_SERVER_HOST=smtp.mailgun.org
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER=postmaster@your-domain.mailgun.org
EMAIL_SERVER_PASSWORD=your-mailgun-password
```
```env theme={null}
EMAIL_SERVER_HOST=smtp.gmail.com
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER=your-email@gmail.com
EMAIL_SERVER_PASSWORD=your-app-password
```
### Production Checklist
* [ ] Replace Mailtrap with production email service
* [ ] Configure SPF, DKIM, and DMARC records
* [ ] Set up email bounce handling
* [ ] Implement rate limiting for email sending
* [ ] Add email analytics tracking
* [ ] Configure unsubscribe links
* [ ] Test email deliverability
* [ ] Monitor email reputation
* [ ] Remove or secure test endpoints
* [ ] Update logo to production version
## Email Debugging
### Common Issues
**Solutions:**
* Verify Mailtrap credentials in `.env`
* Check console for error messages
* Ensure `EMAIL_SERVER_PORT` is 2525 (not 25 or 587)
* Test connection with telnet: `telnet sandbox.smtp.mailtrap.io 2525`
**Solutions:**
* Check firewall settings
* Verify network allows outbound SMTP
* Try alternative ports (2525, 587, 465)
* Use secure connection: `EMAIL_SERVER_SECURE=true`
**Solutions:**
* Regenerate Mailtrap credentials
* Ensure no extra spaces in credentials
* Check for special characters that need escaping
* Verify account is active and not suspended
**Solutions:**
* Use base64 embedded images
* Keep image size under 30KB
* Test in multiple email clients
* Provide alt text for accessibility
### Debug Mode
Enable detailed logging:
```typescript theme={null}
// lib/email.ts
import { createTransport } from 'nodemailer';
const transporter = createTransport({
host: process.env.EMAIL_SERVER_HOST,
port: Number(process.env.EMAIL_SERVER_PORT),
auth: {
user: process.env.EMAIL_SERVER_USER,
pass: process.env.EMAIL_SERVER_PASSWORD,
},
debug: true, // Enable debug output
logger: true // Log to console
});
```
### Testing Tools
Safe email testing sandbox
[mailtrap.io](https://mailtrap.io)
Spam score analysis
[mail-tester.com](https://www.mail-tester.com)
Email client preview testing
[litmus.com](https://litmus.com)
Comprehensive email testing
[emailonacid.com](https://www.emailonacid.com)
## API Reference
### Test Email Endpoint
```typescript theme={null}
POST /api/auth/test-email
Authorization: Bearer {admin-secret}
{
"email": "recipient@example.com",
"subject": "Custom Subject",
"template": "verification" | "passwordReset" | "notification"
}
Response:
{
"success": true,
"messageId": "abc123",
"preview": "https://mailtrap.io/inboxes/123/messages/456"
}
```
### Email Service Methods
```typescript theme={null}
// Send email
await sendEmail({
to: string | string[],
subject: string,
html: string,
text?: string,
attachments?: Array<{
filename: string,
content: Buffer
}>
});
// Send templated email
await sendTemplatedEmail({
to: string,
template: 'verification' | 'passwordReset',
data: {
token: string,
userName?: string,
expiresIn?: string
}
});
```
## Support
For email testing assistance:
* **Documentation**: [docs.plugged.in](https://docs.plugged.in)
* **Mailtrap Support**: [help.mailtrap.io](https://help.mailtrap.io)
* **GitHub Issues**: [Report issues](https://github.com/VeriTeknik/pluggedin-app/issues)
