diff --git a/docs/content/docs/(guides)/apps/emails.mdx b/docs/content/docs/(guides)/apps/emails.mdx index 8a94e6559..9ae09b38e 100644 --- a/docs/content/docs/(guides)/apps/emails.mdx +++ b/docs/content/docs/(guides)/apps/emails.mdx @@ -2,6 +2,7 @@ title: Emails description: Send custom emails to your users with Stack Auth's email system. icon: Mail +lastModified: "2026-03-11" --- 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. @@ -65,6 +66,24 @@ const result = await stackServerApp.sendEmail({ }); ``` +### Scheduling Emails + +Schedule emails for future delivery with the `scheduledAtMillis` option: + +```typescript +// Schedule an email to be sent in 1 hour +const oneHourFromNow = Date.now() + 60 * 60 * 1000; + +const result = await stackServerApp.sendEmail({ + userIds: ['user-id'], + subject: 'Reminder: Your trial ends soon', + html: '

Your trial period ends tomorrow. Upgrade now to keep access.

', + scheduledAtMillis: oneHourFromNow, +}); +``` + +If `scheduledAtMillis` is not provided, the email is sent immediately. + ### Email Options The `sendEmail` method accepts the following options: @@ -78,6 +97,7 @@ type SendEmailOptions = { html?: string; // Custom HTML content templateId?: string; // Template ID to use variables?: Record; // Template variables + scheduledAtMillis?: number; // When to send (timestamp in milliseconds) }; ``` @@ -125,7 +145,7 @@ These templates can be customized through the admin interface or programmaticall ## Email Configuration -Email configuration is managed through the Stack Auth dashboard or admin API, not directly in your application code. You have two options: +Email configuration is managed through the Stack Auth dashboard or admin API, not directly in your application code. You have three options: ### Shared Email Provider (Development) @@ -135,9 +155,27 @@ For development and testing, you can use Stack's shared email provider. This sen - Select "Shared" as your email server type - No additional configuration required +### Managed by Stack Auth (Production) + +Stack Auth can automatically manage your email domain and DNS configuration, letting you send emails from your own domain without manually configuring SMTP. + +**Setup:** + +1. Go to your project's Email settings in the dashboard and click "Managed Setup" +2. Enter your subdomain (e.g., `mail.yourdomain.com`) and sender local part (e.g., `noreply`) +3. Stack Auth will display nameserver records — add these NS records at your DNS provider for the subdomain +4. Wait for DNS propagation (status will change from "pending_verification" to "verified") +5. Click "Use This Domain" to activate + +Your emails will be sent from `{sender}@{subdomain}` (e.g., `noreply@mail.yourdomain.com`). + + +DNS propagation can take anywhere from a few minutes to 48 hours depending on your DNS provider. + + ### Custom Email Server (Production) -For production, configure your own SMTP server through the dashboard: +If you prefer to use your own SMTP server, configure it through the dashboard: - Go to your project's Email settings in the dashboard - Select "Custom SMTP server" as your email server type