Email Workflows

The boilerplate includes comprehensive email workflows that automatically handle user communications across authentication, billing, team management, and security scenarios.
Perfect for: Automated user journeys, transactional communications, and professional email sequences that enhance user experience.

Workflow Categories

The system handles four main categories of email workflows:
Automatic workflows triggered by Better Auth:
  • Account registration and verification
  • Password reset process
  • Magic link authentication
  • Two-factor authentication
  • Email address changes
  • Account security alerts

Authentication Workflows

Password Reset Flow

1

User Request

  1. User clicks "Forgot Password"
  2. Enters email address
  3. Submits reset request
2

Better Auth Processing

// From src/lib/better-auth/auth.ts
sendResetPassword: async ({ user, url }) => {
  await createTypedNotificationService({
    userId: user.id,
    type: NotificationTypeConst.reset_password,
    metadata: { url },
  })
}
3

Email Delivery

  • Template: reset-password-email.tsx
  • Type: Critical (always sent)
  • Content: Secure reset link with expiration
  • Languages: User's preferred language
4

User Action

  1. User receives email
  2. Clicks reset link
  3. Sets new password
  4. Gets confirmation notification

Email Verification Flow

1

Registration Trigger

  • New user registration
  • Email change request
  • Manual verification request
2

Automatic Processing

// From src/lib/better-auth/auth.ts
sendVerificationEmail: async ({ user, url }) => {
  await createTypedNotificationService({
    userId: user.id,
    type: NotificationTypeConst.email_verification,
    metadata: { url },
  })
}
3

Email Details

  • Template: verification-email.tsx
  • Expiration: 1 hour
  • Auto-login: After verification
  • Resend: Available if needed

Magic Link Flow

1

Passwordless Request

  1. User enters email for magic link
  2. System generates secure link
  3. Better Auth triggers notification
2

Email Generation

  • Template: magic-link-email.tsx
  • Security: Single-use link
  • Expiration: Time-limited
  • Fallback: Option to use password instead
3

Authentication

  1. User clicks magic link
  2. Automatic sign-in
  3. Redirect to dashboard

Subscription Workflows

New Subscription Flow

1

Stripe Webhook

  1. User completes payment in Stripe
  2. Stripe sends webhook to application
  3. System processes subscription data
2

Email Trigger

// From src/services/email-service.ts
export const sendSubscriptionCompletedEmailService = async (
  subscription: Subscription
) => {
  // Process subscription details
  const planName = subscription.plan || plan?.planName || 'Plan inconnu'
  const price = getFormattedPriceFromSubscription(stripeSubscription)

  // Send comprehensive subscription email
}
3

Email Content

  • Template: subscription-completed-email.tsx
  • Details: Plan name, price, billing cycle
  • Features: Plan limits and seat count
  • Next steps: Account setup guidance

Subscription Update Flow

1

Plan Change

  • User upgrades/downgrades plan
  • Billing cycle changes
  • Seat count modifications
2

Automatic Notification

// From src/services/email-service.ts
export const sendSubscriptionUpdatedEmailService = async (
  subscription: Subscription
) => {
  // Calculate changes and send update email
}
3

Update Details

  • Template: subscription-updated-email.tsx
  • Changes: What changed in the subscription
  • Billing: New pricing and billing date
  • Features: Updated plan limits

Subscription Cancellation Flow

1

Cancellation Event

  • User cancels subscription
  • System processes cancellation
  • Stripe confirms cancellation
2

Email Confirmation

  • Template: subscription-canceled-email.tsx
  • Details: Cancellation date and reason
  • Access: Remaining access period
  • Reactivation: How to reactivate if desired

Organization Workflows

Team Invitation Flow

1

Invitation Creation

  1. Admin invites new team member
  2. System creates invitation record
  3. Invitation email is triggered
2

Email Process

// From src/services/email-service.ts
export const sendOrganizationInvitation = async ({
  email,
  invitedByUsername,
  invitedByEmail,
  teamName,
  inviteLink,
}: SendOrganizationInvitationParams) => {
  // Send invitation with team context
}
3

Invitation Email

  • Template: invitation-organization-link-email.tsx
  • Context: Who invited them and to which organization
  • Action: Secure invitation link
  • Expiration: Time-limited invitation
4

Dual Notification

  • Invitee: Receives invitation email
  • Inviter: Gets confirmation that invitation was sent
  • Organization: Team activity log updated

Security Workflows

Security Alert Flow

1

Security Event

  • Suspicious login detected
  • Password change from new device
  • Multiple failed login attempts
  • Account access from new location
2

Alert Generation

// Security alerts are critical notifications
await createTypedNotificationService({
  userId: user.id,
  type: NotificationTypeConst.security_alert,
  title: 'Suspicious login detected',
  message: 'We detected a login from a new device',
  metadata: {
    ipAddress: '192.168.1.1',
    location: 'Paris, France'
  }
})
3

Immediate Email

  • Priority: Critical (bypasses user preferences)
  • Template: notification-email.tsx with warning styling
  • Action: Security recommendations
  • Response: How to secure account

Email Type Classification

The system automatically handles email priority based on content type:

Critical Emails (Always Sent)

// From src/services/notification-service.ts
const criticalTypes: NotificationType[] = [
  'reset_password',
  'email_verification',
  'change_email_verification',
  'magic_link',
  'otp_code',
  'security_alert',
  'password_changed',
  'organization_invitation',
  'subscription_created',
  'subscription_updated',
  'subscription_canceled',
  'subscription_deleted',
]
These emails are sent regardless of user notification preferences.

Standard Emails (Respect User Preferences)

  • Generic notifications
  • Feature updates
  • Marketing communications
  • Non-critical system updates
These emails respect the user's notification channel settings.

Error Handling and Reliability

Graceful Degradation

// From src/services/notification-service.ts
try {
  // Email sending logic...
} catch (emailError) {
  // Don't fail notification creation if email fails
  console.error("Erreur lors de l'envoi de l'email de notification:", emailError)
}

Reliability Features

  • Notification Creation: Always succeeds even if email fails
  • Error Logging: Comprehensive error tracking
  • Retry Logic: Built into Resend service
  • Monitoring: Dashboard visibility into email delivery

Multi-Language Support

All workflows automatically adapt to user language preferences: 
// From src/services/email-service.ts
const t = await getTranslations({
  locale: userLanguage,
  namespace: 'email.user.notification',
})
Supported languages: French, English, Spanish
Complete email automation! Your application handles all user communication workflows automatically with professional templates and reliable delivery.
    Email Workflows | ShipSaaS Documentation | ShipSaaS - Launch your SaaS with AI in days