Email System

goilerplate comes with a complete email system powered by Resend, providing email verification, password reset, and newsletter functionality out of the box.

Requirements

Resend Account (Required)

goilerplate requires a Resend account for email functionality. Resend offers a generous free tier:

• 3,000 emails per month
• 100 daily sends
• Unlimited audience contacts

Sign up at resend.com to get your API key.

Configuration

Add these environment variables to your .env file:

# Email Service (REQUIRED for production)
[email protected]
RESEND_API_KEY=re_xxxxxxxxxxxxx

# Optional: For newsletter subscriptions
RESEND_AUDIENCE_ID=aud_xxxxxxxxxxxxx

Features

Email Verification

All new users must verify their email address before accessing the application:

1. User registers → Email with verification link sent
2. User clicks verification link → Account activated
3. Automatic login after successful verification
4. Configurable expiry (default: 24 hours)

Password Reset

Security-focused password reset flow:

1. User requests reset → Email with magic link sent
2. User clicks link → Password removed & automatically logged in
3. User redirected to Settings with “Password Removed” notification
4. User can set new password in Settings
5. Configurable expiry (default: 15 minutes)

This approach prevents token replay attacks and ensures the user has full control over their new password.

Newsletter Signup

Optional newsletter functionality:

1. Email collected via footer form
2. Subscribers added to Resend Audience
3. Managed through Resend dashboard
4. Automatic unsubscribe handling

To disable the newsletter, simply comment out @FooterNewsletter() in internal/ui/blocks/footer.templ.

Development Mode

In development mode (APP_ENV=development), emails are logged to the console instead of being sent:

[EMAIL] Verification
  To: [email protected]
  Subject: Verify your email for Acme
  URL: http://localhost:8090/verify/abc123...

This allows you to develop without a Resend API key.

Production Setup

1. Get Your Resend API Key

1. Sign up at resend.com
2. Navigate to API Keys
3. Create a new API key
4. Add to your .env file

2. Configure Your Domain

1. Add your domain in Resend dashboard
2. Configure DNS records as instructed
3. Update EMAIL_FROM to use your domain

3. Create an Audience (Optional)

For newsletter functionality:

1. Create an Audience in Resend
2. Copy the Audience ID
3. Add to RESEND_AUDIENCE_ID

Customization

Email Templates

Edit email templates in internal/service/email_templates.go:

• verificationEmailTemplate() - Verification email content
• passwordResetEmailTemplate() - Password reset email content
• welcomeEmailTemplate() - Welcome email content

Email Pages

Customize email-related pages in internal/ui/pages/:

• verify_email_sent.templ - Check your email page
• verify_email.templ - Verification success/error
• forgot_password.templ - Request password reset
• reset_password.templ - New password form

Security

The email system includes these security features:

• Secure tokens: 32-byte random tokens using crypto/rand
• Configurable token expiry: Customize expiry times via environment variables (defaults: 24h for email verification, 15m for password reset, 24h for email change)
• One-time use: Tokens are marked as used after first use
• Email enumeration protection: Same response for existing/non-existing emails
• Password requirements: Minimum 12 characters enforced

Token expiry can be customized via environment variables. See Authentication → Customization for details.

Troubleshooting

• Emails not sending: Verify RESEND_API_KEY is set correctly and APP_ENV is set to production. Check Resend dashboard for API errors.
• Emails going to spam: Configure domain authentication (SPF, DKIM, DMARC) in Resend dashboard.
• Newsletter not working: Ensure RESEND_AUDIENCE_ID is configured correctly.