|
| 1 | +--- |
| 2 | +title: Emails |
| 3 | +description: Send custom emails to your users with Stack Auth's email system. |
| 4 | +--- |
| 5 | + |
| 6 | +Stack Auth provides emails that allows you to send custom emails to your users. The system supports both custom HTML emails and template-based emails with theming. |
| 7 | + |
| 8 | +## Email Types: |
| 9 | +There are two types of emails that you can send to your users: |
| 10 | +- **Transactional Emails**: Transactional emails are those required for your user to use your application. These emails cannot be opted out of. |
| 11 | +- **Marketing Emails**: Marketing emails always contain an unsubscribe link and may be more general marketing material related to your application/company. |
| 12 | + |
| 13 | +<Info> |
| 14 | +Never send marketing emails as transactional emails, as this can quickly lead to your domain being blacklisted by email spam filters. |
| 15 | +</Info> |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +## Overview |
| 20 | + |
| 21 | +The email system provides: |
| 22 | + |
| 23 | +- **Email Sending**: Send custom emails to users via the `sendEmail` method on `StackServerApp` |
| 24 | +- **Email Templates**: Use predefined email templates for common authentication flows |
| 25 | +- **Email Themes**: Apply consistent styling to your emails |
| 26 | +- **Notification Categories**: Allow users to control which emails they receive |
| 27 | + |
| 28 | +## Server-Side Email Sending |
| 29 | + |
| 30 | +### Basic Email Sending |
| 31 | + |
| 32 | +Use the `sendEmail` method on your server app to send emails to users: |
| 33 | + |
| 34 | +```typescript |
| 35 | +import { stackServerApp } from './stack'; |
| 36 | + |
| 37 | +// Send a custom HTML email |
| 38 | +const result = await stackServerApp.sendEmail({ |
| 39 | + userIds: ['user-id-1', 'user-id-2'], |
| 40 | + subject: 'Welcome to our platform!', |
| 41 | + html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>', |
| 42 | +}); |
| 43 | + |
| 44 | +if (result.status === 'error') { |
| 45 | + console.error('Failed to send email:', result.error); |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +### Template-Based Emails |
| 50 | + |
| 51 | +Send emails using predefined templates with variables: |
| 52 | + |
| 53 | +```typescript |
| 54 | +// Send email using a template |
| 55 | +const result = await stackServerApp.sendEmail({ |
| 56 | + userIds: ['user-id'], |
| 57 | + templateId: 'welcome-template', |
| 58 | + subject: 'Welcome to our platform!', |
| 59 | + variables: { |
| 60 | + userName: 'John Doe', |
| 61 | + activationUrl: 'https://yourapp.com/activate/token123', |
| 62 | + supportEmail: 'support@yourapp.com', |
| 63 | + }, |
| 64 | +}); |
| 65 | +``` |
| 66 | + |
| 67 | +### Email Options |
| 68 | + |
| 69 | +The `sendEmail` method accepts the following options: |
| 70 | + |
| 71 | +```typescript |
| 72 | +type SendEmailOptions = { |
| 73 | + userIds: string[]; // Array of user IDs to send to |
| 74 | + themeId?: string | null | false; // Theme to apply (optional) |
| 75 | + subject?: string; // Email subject |
| 76 | + notificationCategoryName?: string; // Notification category for user preferences |
| 77 | + html?: string; // Custom HTML content |
| 78 | + templateId?: string; // Template ID to use |
| 79 | + variables?: Record<string, any>; // Template variables |
| 80 | +}; |
| 81 | +``` |
| 82 | + |
| 83 | +### Error Handling |
| 84 | + |
| 85 | +The `sendEmail` method returns a `Result` type that can contain specific errors: |
| 86 | + |
| 87 | +```typescript |
| 88 | +const result = await stackServerApp.sendEmail({ |
| 89 | + userIds: ['user-id'], |
| 90 | + html: '<p>Hello!</p>', |
| 91 | + subject: 'Test Email', |
| 92 | +}); |
| 93 | + |
| 94 | +if (result.status === 'error') { |
| 95 | + switch (result.error.code) { |
| 96 | + case 'REQUIRES_CUSTOM_EMAIL_SERVER': |
| 97 | + console.error('Please configure a custom email server'); |
| 98 | + break; |
| 99 | + case 'SCHEMA_ERROR': |
| 100 | + console.error('Invalid email data provided'); |
| 101 | + break; |
| 102 | + case 'USER_ID_DOES_NOT_EXIST': |
| 103 | + console.error('One or more user IDs do not exist'); |
| 104 | + break; |
| 105 | + } |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | + |
| 110 | + |
| 111 | +## Built-in Email Templates |
| 112 | + |
| 113 | +Stack Auth provides several built-in email templates for common authentication flows: |
| 114 | + |
| 115 | +- **Email Verification**: `email_verification` - Sent when users need to verify their email |
| 116 | +- **Password Reset**: `password_reset` - Sent when users request password reset |
| 117 | +- **Magic Link**: `magic_link` - Sent for passwordless authentication |
| 118 | +- **Team Invitation**: `team_invitation` - Sent when users are invited to teams |
| 119 | +- **Sign-in Invitation**: `sign_in_invitation` - Sent to invite users to sign up |
| 120 | + |
| 121 | +These templates can be customized through the admin interface or programmatically. |
| 122 | + |
| 123 | +## Email Configuration |
| 124 | + |
| 125 | +Email configuration is managed through the Stack Auth dashboard or admin API, not directly in your application code. You have two options: |
| 126 | + |
| 127 | +### Shared Email Provider (Development) |
| 128 | + |
| 129 | +For development and testing, you can use Stack's shared email provider. This sends emails from `noreply@stackframe.co` and is configured through your project settings in the Stack Auth dashboard. |
| 130 | + |
| 131 | +- Go to your project's Email settings in the dashboard |
| 132 | +- Select "Shared" as your email server type |
| 133 | +- No additional configuration required |
| 134 | + |
| 135 | +### Custom Email Server (Production) |
| 136 | + |
| 137 | +For production, configure your own SMTP server through the dashboard: |
| 138 | + |
| 139 | +- Go to your project's Email settings in the dashboard |
| 140 | +- Select "Custom SMTP server" as your email server type |
| 141 | +- Configure the following settings: |
| 142 | + - **Host**: Your SMTP server hostname (e.g., `smtp.yourprovider.com`) |
| 143 | + - **Port**: SMTP port (typically 587 for TLS or 465 for SSL) |
| 144 | + - **Username**: Your SMTP username |
| 145 | + - **Password**: Your SMTP password |
| 146 | + - **Sender Email**: The email address emails will be sent from |
| 147 | + - **Sender Name**: The display name for your emails |
| 148 | + |
| 149 | +The dashboard will automatically test your configuration when you save it. |
| 150 | + |
| 151 | +## Notification Categories |
| 152 | + |
| 153 | +Control which emails users receive by organizing them into notification categories: |
| 154 | + |
| 155 | +```typescript |
| 156 | +await stackServerApp.sendEmail({ |
| 157 | + userIds: ['user-id'], |
| 158 | + html: '<p>New feature available!</p>', |
| 159 | + subject: 'Product Updates', |
| 160 | + notificationCategoryName: 'product_updates', |
| 161 | +}); |
| 162 | +``` |
| 163 | + |
| 164 | +Users can then opt in or out of specific notification categories through their account settings. |
| 165 | + |
| 166 | +## Best Practices |
| 167 | + |
| 168 | +1. **Use Templates**: Leverage built-in templates for consistent branding and easier maintenance |
| 169 | +2. **Handle Errors**: Always check the result status and handle potential errors |
| 170 | +3. **Respect User Preferences**: Use notification categories to let users control what emails they receive |
| 171 | +4. **Server-Side Only**: Always send emails from your server-side code, never from the client |
| 172 | + |
| 173 | +## React Components Integration |
| 174 | + |
| 175 | +Emails integrates seamlessly with Stack Auth's React components. Email verification, password reset, and other authentication emails are automatically sent when users interact with the provided components. |
| 176 | + |
| 177 | +For custom email flows, use the `sendEmail` method from your server-side code: |
| 178 | + |
| 179 | +```typescript |
| 180 | +// In your API route or server action |
| 181 | +import { stackServerApp } from '@stackframe/stack'; |
| 182 | + |
| 183 | +export async function inviteUser(email: string) { |
| 184 | + const result = await stackServerApp.sendEmail({ |
| 185 | + userIds: [userId], // Get user ID first |
| 186 | + templateId: 'invitation-template', |
| 187 | + subject: 'You\'re invited!', |
| 188 | + variables: { |
| 189 | + inviteUrl: 'https://yourapp.com/invite/token123', |
| 190 | + }, |
| 191 | + }); |
| 192 | + |
| 193 | + return result; |
| 194 | +} |
| 195 | +``` |
| 196 | + |
| 197 | +This email system gives you control over your application's email communications while maintaining the security and reliability of Stack Auth's infrastructure. |
0 commit comments