Configuration

The starter kit uses Resend for sending emails. Resend is a modern email API designed for developers, offering excellent deliverability and a simple integration.

Setup

1. Create a Resend Account

1. Go to Resend and create an account
2. Navigate to the API Keys section in your dashboard
3. Click Create API Key
4. Give it a name (e.g., "Production" or "Development")
5. Copy the API key (starts with re_)

2. Configure Environment Variables

Add the following environment variables to your .env file:

RESEND_API_KEY=re_...
EMAIL_FROM=noreply@yourdomain.com

3. Domain Setup

To send emails from your own domain:

1. Go to Domains in your Resend dashboard

2. Click Add Domain

3. Enter your domain (e.g., yourdomain.com)

4. Add the required DNS records to verify your domain:

   • SPF Record - Authorizes Resend to send emails
   • DKIM Record - Signs emails for authentication
   • DMARC Record (optional) - Email authentication policy

5. Wait for domain verification (usually a few minutes)

6. Update EMAIL_FROM to use your verified domain:

EMAIL_FROM=noreply@yourdomain.com

Email Functions

The email functions in lib/email automatically use your environment variables.

Basic Usage

import { sendEmail } from '@/lib/email';

await sendEmail({
  recipient: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our platform!</h1>',
  text: 'Welcome to our platform!'
});

Using Pre-built Templates

The email module exports functions for all pre-built templates:

import { sendVerifyEmailAddressEmail } from '@/lib/email';

await sendVerifyEmailAddressEmail({
  recipient: user.email,
  name: user.name,
  verificationLink: `${getBaseUrl()}/verify-email?token=${token}`
});

Retry Logic

The email service includes automatic retry logic with exponential backoff:

• Max Attempts: 3 total attempts (the initial attempt and up to 2 retries)
• Base Delay: 1 second
• Max Delay: 10 seconds
• Exponential Backoff: Delay doubles with each retry

Permanent errors (invalid email, auth failure) are not retried.

Error Handling

The email functions handle errors gracefully:

import { sendEmail } from '@/lib/email';

try {
  await sendEmail({
    recipient: 'user@example.com',
    subject: 'Test',
    html: '<p>Test</p>',
    text: 'Test'
  });
} catch (error) {
  // Error is logged automatically
  // Permanent errors are not retried
  // Transient errors are retried automatically
}

Production Configuration

For production deployments:

1. Use a verified domain - Always use your own domain, not Resend's default
2. Set up SPF/DKIM - Ensure DNS records are properly configured
3. Monitor deliverability - Check Resend dashboard for bounce rates
4. Set up webhooks (optional) - Track email events (delivered, bounced, etc.)

Environment Variables in Production

Add your environment variables in your hosting platform:

• Vercel: Project Settings → Environment Variables
• Railway: Variables tab
• Other platforms: Follow their environment variable documentation

Testing

Test templates and delivery separately. A correct preview does not prove that Resend can authenticate your sender or deliver a message.

Preview templates locally

Run npm run email:dev, then open http://localhost:3001. This renders the components in lib/email/templates/ with their PreviewProps without sending email or calling Resend. See React Email Preview.

Verify provider delivery

1. Set RESEND_API_KEY to a development API key.
2. Set EMAIL_FROM to an address on a verified domain. For an initial Resend test, onboarding@resend.dev can only send to the email address associated with your Resend account.
3. Start the application and trigger a real product flow such as email verification, password reset or an organization invitation.
4. Confirm the request succeeds, the message appears in the Resend dashboard and the recipient receives it.
5. Open the generated link and confirm that it uses the correct application URL for the environment you are testing.

Before production

• Use separate Resend API keys for development and production.
• Verify the production sending domain and set EMAIL_FROM to that domain.
• Add both email variables to the production deployment environment.
• Exercise verification, password reset and invitation delivery after deploy.
• Review failed requests, bounces and provider limits in the Resend dashboard.

Best Practices

1. Always use your own domain - Better deliverability and branding
2. Set up DNS records correctly - SPF, DKIM and DMARC
3. Monitor bounce rates - Remove invalid email addresses
4. Use templates - Consistent branding and easier maintenance
5. Handle errors gracefully - Log errors and notify admins
6. Test before production - Preview templates, then exercise real product flows against the deployed environment