Skip to main content

​
Overview

Stack Auth provides customizable email templates for authentication flows. You can modify the subject lines and content to match your brand.

​
Available Email Types

Stack Auth sends emails for the following events:
  • email_verification - Email address verification
  • password_reset - Password reset requests
  • magic_link - Passwordless authentication links
  • team_invitation - Team membership invitations
  • sign_in_invitation - Sign-in invitations for new users
  • payment_receipt - Payment confirmation receipts
  • payment_failed - Failed payment notifications

​
Email Template Structure

Each email template consists of: 
{
  type: 'email_verification' | 'password_reset' | ...,
  subject: string,
  content: any,  // Rich content structure
  is_default: boolean
}

​
Customizing Email Templates

You can customize email templates through the Admin API:

​
Create or Update Template

import { StackServerApp } from '@stackframe/stack';

const stackApp = new StackServerApp({
  tokenStore: 'nextjs-cookie',
});

// Update email template
await stackApp.updateEmailTemplate('email_verification', {
  subject: 'Verify your email - MyApp',
  content: {
    // Custom content structure
  },
});

​
Reset to Default Template

// Delete custom template to revert to default
await stackApp.deleteEmailTemplate('email_verification');

​
Email Configuration

For development, Stack Auth uses Inbucket as a local email testing server. Configure email settings via environment variables: 
# Email service configuration
STACK_EMAIL_FROM=[email protected]
STACK_EMAIL_PROVIDER=smtp

# SMTP settings
STACK_SMTP_HOST=smtp.sendgrid.net
STACK_SMTP_PORT=587
STACK_SMTP_USER=apikey
STACK_SMTP_PASSWORD=your_sendgrid_api_key

​
Email Testing

During development, emails are captured by Inbucket: 
# Start email emulator
pnpm restart-deps

# View emails at:
http://localhost:8125

​
Template Variables

Email templates support dynamic variables:
  • {{verificationLink}} - Email verification URL
  • {{resetLink}} - Password reset URL
  • {{magicLink}} - Magic link URL
  • {{inviteLink}} - Team invitation URL
  • {{userName}} - User’s display name
  • {{teamName}} - Team name (for invitations)
  • {{amount}} - Payment amount (for receipts)

​
Email Delivery Status

Track email delivery through the backend: 
// Check email queue status
const emailStatus = await prisma.emailQueue.findMany({
  where: { projectUserId: userId },
  orderBy: { createdAt: 'desc' },
});

​
Email Normalization

Stack Auth normalizes email addresses:
  • Converts to lowercase
  • Trims whitespace
  • Handles Gmail-style aliases (+ addressing)
This prevents duplicate accounts with similar email addresses.

​
Best Practices

  • Test emails thoroughly before deploying to production
  • Keep subjects clear and concise (under 50 characters)
  • Include your brand name in the subject line
  • Ensure links are accessible for at least 24 hours
  • Monitor delivery rates and failed email notifications
  • Comply with email regulations (CAN-SPAM, GDPR)

​
Troubleshooting

​
Emails Not Sending

  1. Verify SMTP credentials are correct
  2. Check that your SMTP provider allows sending from your domain
  3. Review email queue for errors: pnpm db:seed then check dashboard
  4. Ensure recipient email addresses are valid

​
Emails Going to Spam

  1. Configure SPF, DKIM, and DMARC records for your domain
  2. Use a reputable email service provider (SendGrid, Postmark, etc.)
  3. Avoid spam trigger words in subject lines
  4. Include an unsubscribe link (for marketing emails)

Build docs developers (and LLMs) love

Get started for freeTalk to us