Email - Budgetron

Budgetron uses email for authentication-related notifications including password resets, email verification, account deletion confirmation, and welcome messages.

Email service is optional but required for password reset, email verification, and account deletion features.

Email Configuration

Both environment variables must be set to enable email features:

EMAIL_PROVIDER_API_KEY

string

API key for the email service provider.Example: re_abc123def456... (Resend)Required: Yes (if using email features)

EMAIL_PROVIDER_FROM_EMAIL

string

Email address that emails will be sent from.Example: [email protected], [email protected]Required: Yes (if using email features)Note: Must be a verified domain with your email provider.

Email Provider

Budgetron uses Resend as the default email provider. Resend offers:

Simple API integration
Free tier: 100 emails/day, 3,000/month
Excellent deliverability
Domain verification

Setting Up Resend

Sign up at resend.com
Verify your domain:
- Add DNS records provided by Resend
- Wait for verification (usually instant)
Generate an API key in the dashboard
Set environment variables:

EMAIL_PROVIDER_API_KEY="re_your_api_key_here"
EMAIL_PROVIDER_FROM_EMAIL="[email protected]"

Domain Verification

You must verify your domain with Resend before sending emails. Without verification, emails will fail to send.

Add these DNS records to your domain:

Type	Name	Value
TXT	@	`resend-verification=your-value`
MX	@	`feedback-smtp.resend.com` (priority 10)
TXT	_dmarc	`v=DMARC1; p=none`

Verification usually takes a few minutes but can take up to 48 hours.

Email Templates

Budgetron includes React-based email templates for all notification types:

Available Templates

Welcome Email

Sent when a new user creates an account.Template: src/emails/welcome-email.tsxTrigger: User registration

Email Verification

Sent after sign-up with verification link.Template: src/emails/email-verification-email.tsxTrigger: New account creationExpires: 15 minutes

Password Reset

Sent when user requests password reset.Template: src/emails/reset-password-email.tsxTrigger: Forgot passwordExpires: 15 minutes

Delete Account

Sent when user requests account deletion.Template: src/emails/delete-account-email.tsxTrigger: Delete account requestExpires: 15 minutes

Template Features

Built with React components
Responsive design
Consistent branding
Secure, expiring links
Inline CSS for email client compatibility

Email Workflows

User Registration Flow

User signs up with email and password
Welcome email sent immediately
Email verification sent with 15-minute token
User clicks verification link
Email marked as verified, auto sign-in

Password Reset Flow

User clicks “Forgot password”
Password reset email sent with 15-minute token
User clicks reset link
User enters new password
Password updated, token invalidated

Account Deletion Flow

User requests account deletion
Delete account email sent with 15-minute confirmation token
User clicks confirmation link
Account and all data deleted permanently

Service Implementation

The email service is implemented in src/server/email/service.ts:

async function sendEmail({ to, subject, body }: SendEmailOptions) {
  if (!isEmailServiceEnabled(env)) {
    throw new Error('Email service is not enabled')
  }
  
  const { data, error } = await getProvider().emails.send({
    from: env.EMAIL_PROVIDER_FROM_EMAIL,
    to,
    subject,
    react: body,
  })
  
  if (error) throw new Error(error.message)
  return data
}

Service Detection

The application checks if email is enabled at runtime using isEmailServiceEnabled() defined in src/server/email/utils.ts. Both environment variables must be set for the service to be active.

Provider Abstraction

The provider is abstracted in src/server/email/provider.ts using a singleton pattern. This allows for easy replacement with another email provider by modifying the provider file.

Using Alternative Email Providers

While Resend is the default, you can integrate any email provider by modifying src/server/email/provider.ts.

Supported Alternatives

SendGrid

Popular email API with free tier.Setup:

Install: npm install @sendgrid/mail
Replace Resend in provider.ts
Update environment variables

Docs: sendgrid.com/docs

Mailgun

Powerful email API for developers.Setup:

Install: npm install mailgun.js
Replace Resend in provider.ts
Update environment variables

Docs: documentation.mailgun.com

AWS SES

Scalable email service by Amazon.Setup:

Install: npm install @aws-sdk/client-ses
Replace Resend in provider.ts
Configure AWS credentials

Docs: docs.aws.amazon.com/ses

Postmark

Reliable transactional email.Setup:

Install: npm install postmark
Replace Resend in provider.ts
Update environment variables

Docs: postmarkapp.com/developer

Implementation Steps

Install the provider’s SDK

Update src/server/email/provider.ts:

import { YourEmailProvider } from 'your-provider-sdk'

function getProvider() {
  if (!_provider) {
    _provider = new YourEmailProvider(env.EMAIL_PROVIDER_API_KEY)
  }
  return _provider
}

Update src/server/email/service.ts to match provider’s API
Test all email workflows

Troubleshooting

Emails Not Sending

Service Not Enabled

Error: “Email service is not enabled”Solution: Verify both environment variables are set:

echo $EMAIL_PROVIDER_API_KEY
echo $EMAIL_PROVIDER_FROM_EMAIL

Both must return non-empty values.

Domain Not Verified

Error: “Domain not verified” or “Forbidden”Solutions:

Verify domain in Resend dashboard
Check DNS records are properly configured
Wait up to 48 hours for DNS propagation
Use Resend’s testing domain for development

Invalid API Key

Error: “Invalid API key” or “Unauthorized”Solutions:

Verify EMAIL_PROVIDER_API_KEY is correct
Generate new API key in Resend dashboard
Check for extra spaces or characters

Invalid From Address

Error: “Invalid from address”Solutions:

Ensure EMAIL_PROVIDER_FROM_EMAIL uses verified domain
Format: [email protected] (no spaces)
Must match domain verified in Resend

Rate Limit Exceeded

Error: “Rate limit exceeded” or “Too many requests”Solutions:

Check Resend rate limits (100/day on free tier)
Upgrade to higher tier if needed
Implement rate limiting in application

Testing Email Configuration

Test your email setup:

# Test Resend API
curl -X POST https://api.resend.com/emails \
  -H "Authorization: Bearer $EMAIL_PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "'$EMAIL_PROVIDER_FROM_EMAIL'",
    "to": ["[email protected]"],
    "subject": "Test Email",
    "html": "<p>Test</p>"
  }'

Expected response: JSON with id field.

Emails Going to Spam

Configure SPF, DKIM, and DMARC records to improve email deliverability and prevent spam filtering.

Solutions:

Verify domain with email provider
Add SPF record: v=spf1 include:resend.com ~all
Configure DKIM (automatic with Resend)
Add DMARC policy: v=DMARC1; p=quarantine
Use a dedicated sending domain
Avoid spam trigger words

Development and Testing

Development Workflow

For local development without email setup:

Leave email variables empty
Features requiring email will be disabled
Users can still sign in with email/password
OAuth sign-in works independently

Testing Emails Locally

Resend Test Mode
Mailtrap
Local SMTP Server

Use Resend’s onboarded domain for testing:

EMAIL_PROVIDER_FROM_EMAIL="[email protected]"

Emails will be sent but won’t deliver to recipients.

Run local SMTP server for testing:

# Using MailHog
docker run -p 1025:1025 -p 8025:8025 mailhog/mailhog

View emails at http://localhost:8025

Email Deliverability

Best Practices

Follow these guidelines for optimal email deliverability:

Verify domain - Always verify your sending domain
Use dedicated domain - Don’t send from your main domain
Configure DNS - Set up SPF, DKIM, and DMARC
Warm up domain - Gradually increase sending volume
Monitor bounces - Track and handle bounce rates
Clean subject lines - Avoid spam trigger words
Include unsubscribe - For non-transactional emails

DNS Configuration

Required DNS records for Resend:

# SPF Record
Type: TXT
Name: @
Value: v=spf1 include:resend.com ~all

# DMARC Record
Type: TXT
Name: _dmarc
Value: v=DMARC1; p=quarantine; rua=mailto:[email protected]

# MX Record (for bounce handling)
Type: MX
Name: @
Value: feedback-smtp.resend.com
Priority: 10

Rate Limits and Pricing

Resend Pricing (as of 2024)

Plan	Price	Emails/Month	Features
Free	$0	3,000	100/day, 1 domain
Pro	$20	50,000	Unlimited domains, analytics
Business	$80	200,000	Priority support, SLA

The free tier is sufficient for most small to medium deployments.

Privacy and Compliance

Data Handling

Email content: Sent to Resend via HTTPS
User data: Only email addresses sent to provider
Retention: Resend stores logs for 30 days
GDPR: Resend is GDPR compliant

User Privacy

All email links expire after 15 minutes
Tokens are single-use only
No tracking pixels in emails
Plain text alternative included

Authentication Configuration - Email verification and password reset
Environment Variables - Complete environment reference

Get Started

Core Features

Configuration

Deployment

Development

​Email Configuration

​Email Provider

​Setting Up Resend

​Domain Verification

​Email Templates

​Available Templates

Welcome Email

Email Verification

Password Reset

Delete Account

​Template Features

​Email Workflows

​User Registration Flow

​Password Reset Flow

​Account Deletion Flow

​Service Implementation

​Service Detection

​Provider Abstraction

​Using Alternative Email Providers

​Supported Alternatives

​Implementation Steps

​Troubleshooting

​Emails Not Sending

​Testing Email Configuration

​Emails Going to Spam

​Development and Testing

​Development Workflow

​Testing Emails Locally

​Email Deliverability

​Best Practices

​DNS Configuration

​Rate Limits and Pricing

​Resend Pricing (as of 2024)

​Privacy and Compliance

​Data Handling

​User Privacy

​Related Configuration

Build docs developers (and LLMs) love

Email Configuration

Email Provider

Setting Up Resend

Domain Verification

Email Templates

Available Templates

Template Features

Email Workflows

User Registration Flow

Password Reset Flow

Account Deletion Flow

Service Implementation

Service Detection

Provider Abstraction

Using Alternative Email Providers

Supported Alternatives

Implementation Steps

Troubleshooting

Emails Not Sending

Testing Email Configuration

Emails Going to Spam

Development and Testing

Development Workflow

Testing Emails Locally

Email Deliverability

Best Practices

DNS Configuration

Rate Limits and Pricing

Resend Pricing (as of 2024)

Privacy and Compliance

Data Handling

User Privacy

Related Configuration