CodeCow/stack
1
0
Fork 0
mirror of https://github.com/stack-auth/stack.git synced 2026-06-13 21:01:21 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

init emails docs

Browse Source
This commit is contained in:
Madison 2025-08-12 15:34:22 -05:00
parent 0580a563d8
commit 0fec440e49
7 changed files with 489 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/docs-platform.yml
View File

@ -110,6 +110,9 @@ pages:
- path: concepts/backend-integration.mdx
platforms: ["next", "react", "js", "python"]
- path: concepts/emails.mdx
platforms: ["next", "react", "js"] # No Python (server-side email functionality)
# Components (React-like only)
- path: components/overview.mdx
@ -227,6 +230,9 @@ pages:
- path: sdk/types/user.mdx
platforms: ["next", "react", "js"] # No Python
- path: sdk/types/email.mdx
platforms: ["next", "react", "js"] # No Python
# SDK Hooks (React-like only)
- path: sdk/hooks/use-stack-app.mdx

197
docs/templates/concepts/emails.mdx vendored Normal file
View File

@ -0,0 +1,197 @@
---
title: Email System
description: Send custom emails to your users with Stack Auth's email system.
---
Stack Auth provides an email system that allows you to send custom emails to your users. The system supports both custom HTML emails and template-based emails with theming.
## Overview
The email system provides:
- **Email Sending**: Send custom emails to users via the `sendEmail` method on `StackServerApp`
- **Email Templates**: Use predefined email templates for common authentication flows
- **Email Themes**: Apply consistent styling to your emails
- **Notification Categories**: Allow users to control which emails they receive
## Server-Side Email Sending
### Basic Email Sending
Use the `sendEmail` method on your server app to send emails to users:
```typescript
import { stackServerApp } from './stack';
// Send a custom HTML email
const result = await stackServerApp.sendEmail({
userIds: ['user-id-1', 'user-id-2'],
subject: 'Welcome to our platform!',
html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
});
if (result.status === 'error') {
console.error('Failed to send email:', result.error);
}
```
### Template-Based Emails
Send emails using predefined templates with variables:
```typescript
// Send email using a template
const result = await stackServerApp.sendEmail({
userIds: ['user-id'],
templateId: 'welcome-template',
subject: 'Welcome to our platform!',
variables: {
userName: 'John Doe',
activationUrl: 'https://yourapp.com/activate/token123',
supportEmail: 'support@yourapp.com',
},
});
```
### Email Options
The `sendEmail` method accepts the following options:
```typescript
type SendEmailOptions = {
userIds: string[]; // Array of user IDs to send to
themeId?: string | null | false; // Theme to apply (optional)
subject?: string; // Email subject
notificationCategoryName?: string; // Notification category for user preferences
} & (
| {
html: string; // Custom HTML content
}
| {
templateId: string; // Template ID to use
variables?: Record<string, any>; // Template variables
}
);
```
### Error Handling
The `sendEmail` method returns a `Result` type that can contain specific errors:
```typescript
const result = await stackServerApp.sendEmail({
userIds: ['user-id'],
html: '<p>Hello!</p>',
subject: 'Test Email',
});
if (result.status === 'error') {
switch (result.error.code) {
case 'REQUIRES_CUSTOM_EMAIL_SERVER':
console.error('Please configure a custom email server');
break;
case 'SCHEMA_ERROR':
console.error('Invalid email data provided');
break;
case 'USER_ID_DOES_NOT_EXIST':
console.error('One or more user IDs do not exist');
break;
}
}
```
## Built-in Email Templates
Stack Auth provides several built-in email templates for common authentication flows:
- **Email Verification**: `email_verification` - Sent when users need to verify their email
- **Password Reset**: `password_reset` - Sent when users request password reset
- **Magic Link**: `magic_link` - Sent for passwordless authentication
- **Team Invitation**: `team_invitation` - Sent when users are invited to teams
- **Sign-in Invitation**: `sign_in_invitation` - Sent to invite users to sign up
These templates can be customized through the admin interface or programmatically.
## Email Configuration
### Shared Email Provider (Development)
For development, you can use Stack's shared email provider:
```typescript
// In your project configuration
{
emailConfig: {
type: 'shared', // Uses Stack's shared email service
}
}
```
### Custom Email Server (Production)
For production, configure your own email server:
```typescript
// In your project configuration
{
emailConfig: {
type: 'standard',
host: 'smtp.yourprovider.com',
port: 587,
username: 'your-username',
password: 'your-password',
senderEmail: 'noreply@yourdomain.com',
senderName: 'Your App Name',
}
}
```
## Notification Categories
Control which emails users receive by organizing them into notification categories:
```typescript
await stackServerApp.sendEmail({
userIds: ['user-id'],
html: '<p>New feature available!</p>',
subject: 'Product Updates',
notificationCategoryName: 'product_updates',
});
```
Users can then opt in or out of specific notification categories through their account settings.
## Best Practices
1. **Use Templates**: Leverage built-in templates for consistent branding and easier maintenance
2. **Handle Errors**: Always check the result status and handle potential errors
3. **Respect User Preferences**: Use notification categories to let users control what emails they receive
4. **Server-Side Only**: Always send emails from your server-side code, never from the client
## React Components Integration
The email system 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.
For custom email flows, use the `sendEmail` method from your server-side code:
```typescript
// In your API route or server action
import { stackServerApp } from './stack';
export async function inviteUser(email: string) {
const result = await stackServerApp.sendEmail({
userIds: [userId], // Get user ID first
templateId: 'invitation-template',
subject: 'You\'re invited!',
variables: {
inviteUrl: 'https://yourapp.com/invite/token123',
},
});
return result;
}
```
This email system gives you control over your application's email communications while maintaining the security and reliability of Stack Auth's infrastructure.

1
docs/templates/meta.json vendored
View File

@ -14,6 +14,7 @@
"concepts/api-keys",
"concepts/backend-integration",
"concepts/custom-user-data",
"concepts/emails",
"concepts/oauth",
"concepts/auth-providers",
"concepts/orgs-and-teams",

6
docs/templates/sdk/index.mdx vendored
View File

@ -40,6 +40,12 @@ export const sdkSections = [
{ name: "ServerTeamProfile", href: "types/team-profile#serverteamprofile", icon: "type" },
]
},
{
title: "Email",
items: [
{ name: "SendEmailOptions", href: "types/email#sendemaildoptions", icon: "type" },
]
},
{
title: "Hooks",
items: [

1
docs/templates/sdk/meta.json vendored
View File

@ -14,6 +14,7 @@
"types/team-permission",
"types/team-profile",
"types/contact-channel",
"types/email",
"types/api-key",
"types/project",
"types/connected-account",

72
docs/templates/sdk/objects/stack-app.mdx vendored
View File

@ -525,6 +525,7 @@ exposing [`SECRET_SERVER_KEY`](../../rest-api/overview.mdx) on the client.
// NEXT_LINE_PLATFORM react-like
⤷ useUsers([options]): ServerUser[]; //$stack-link-to:#stackserverappuseusersoptions
createUser([options]): Promise<ServerUser>; //$stack-link-to:#stackserverappcreateuseroptions
sendEmail(options): Promise<Result<void, KnownErrors>>; //$stack-link-to:#stackserverappsendemailoptions
getTeam(id): Promise<ServerTeam | null>; //$stack-link-to:#stackserverappgetteamid
// NEXT_LINE_PLATFORM react-like
@ -799,6 +800,77 @@ const user = await stackServerApp.createUser({
</MethodLayout>
</CollapsibleMethodSection>
<CollapsibleMethodSection method="sendEmail" signature="[options]" appType="StackServerApp" defaultOpen={false}>
<MethodLayout>
<MethodContent>
Send custom emails to users. You can send either custom HTML emails or use predefined templates with variables.
**Parameters:**
- `options` ([SendEmailOptions](../types/email#sendemaildoptions)) - Email configuration and content
**Returns:** `Promise<Result<void, KnownErrors>>`
The method returns a `Result` object that can contain specific error types:
- `RequiresCustomEmailServer` - No custom email server configured
- `SchemaError` - Invalid email data provided
- `UserIdDoesNotExist` - One or more user IDs don't exist
</MethodContent>
<MethodAside>
<AsideSection title="Signature">
```typescript
declare function sendEmail(options: SendEmailOptions): Promise<Result<void, KnownErrors>>;
```
</AsideSection>
<AsideSection title="Examples">
<Tabs defaultValue="html-email">
<TabsList>
<TabsTrigger value="html-email">Send HTML Email</TabsTrigger>
<TabsTrigger value="template-email">Send Template Email</TabsTrigger>
</TabsList>
<TabsContent value="html-email">
```typescript
const result = await stackServerApp.sendEmail({
userIds: ['user-1', 'user-2'],
subject: 'Welcome to our platform!',
html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
});
if (result.status === 'error') {
console.error('Failed to send email:', result.error);
}
```
</TabsContent>
<TabsContent value="template-email">
```typescript
const result = await stackServerApp.sendEmail({
userIds: ['user-1'],
templateId: 'welcome-template',
variables: {
userName: 'John Doe',
activationUrl: 'https://app.com/activate/token123',
},
});
if (result.status === 'error') {
console.error('Failed to send email:', result.error);
}
```
</TabsContent>
</Tabs>
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleMethodSection>
## Team Management
<CollapsibleMethodSection method="getTeam" signature="[id]" appType="StackServerApp" defaultOpen={false}>

206
docs/templates/sdk/types/email.mdx vendored Normal file
View File

@ -0,0 +1,206 @@
---
title: Email
full: true
---
This is a detailed reference for email-related types in Stack Auth. If you're looking for a more high-level overview, please refer to our [guide on the email system](../../concepts/emails.mdx).
On this page:
- [SendEmailOptions](#sendemaildoptions)
---
# `SendEmailOptions`
Options for sending emails via the `sendEmail` method on `StackServerApp`.
### Table of Contents
<ClickableTableOfContents code={`type SendEmailOptions = {
userIds: string[]; //$stack-link-to:#sendemaildoptionsuserids
themeId?: string | null | false; //$stack-link-to:#sendemaildoptionsthemeid
subject?: string; //$stack-link-to:#sendemaildoptionssubject
notificationCategoryName?: string; //$stack-link-to:#sendemaildoptionsnotificationcategoryname
} & (
| {
html: string; //$stack-link-to:#sendemaildoptionshtml
}
| {
templateId: string; //$stack-link-to:#sendemaildoptionstemplateid
variables?: Record<string, any>; //$stack-link-to:#sendemaildoptionsvariables
}
);`} />
<CollapsibleTypesSection type="sendEmailOptions" property="userIds" defaultOpen={false}>
<MethodLayout>
<MethodContent>
An array of user IDs that will receive the email. All users must exist in your Stack Auth project.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
userIds: string[]
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
userIds: ['user-1', 'user-2', 'user-3'],
// ... other options
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>
<CollapsibleTypesSection type="sendEmailOptions" property="themeId" defaultOpen={false}>
<MethodLayout>
<MethodContent>
Optional theme ID to apply to the email. Use `null` for no theme, `false` to use the default theme, or a string ID for a specific theme.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
themeId?: string | null | false
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
themeId: 'corporate-theme-id',
// or
themeId: null, // no theme
// or
themeId: false, // default theme
// ... other options
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>
<CollapsibleTypesSection type="sendEmailOptions" property="subject" defaultOpen={false}>
<MethodLayout>
<MethodContent>
Optional email subject line. If using a template, this overrides the template's default subject.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
subject?: string
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
subject: 'Welcome to our platform!',
// ... other options
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>
<CollapsibleTypesSection type="sendEmailOptions" property="notificationCategoryName" defaultOpen={false}>
<MethodLayout>
<MethodContent>
Optional notification category name for user preferences. Users can opt in or out of specific categories through their account settings.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
notificationCategoryName?: string
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
notificationCategoryName: 'product_updates',
// ... other options
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>
<CollapsibleTypesSection type="sendEmailOptions" property="html" defaultOpen={false}>
<MethodLayout>
<MethodContent>
Custom HTML content for the email. Use this option when you want to send a custom HTML email instead of using a template.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
html: string
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
userIds: ['user-1'],
html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
subject: 'Welcome to our platform'
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>
<CollapsibleTypesSection type="sendEmailOptions" property="templateId" defaultOpen={false}>
<MethodLayout>
<MethodContent>
ID of the email template to use. Use this option when you want to send a template-based email with variables.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
templateId: string
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
userIds: ['user-1'],
templateId: 'welcome-template',
variables: {
userName: 'John Doe',
activationUrl: 'https://app.com/activate/token123'
}
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>
<CollapsibleTypesSection type="sendEmailOptions" property="variables" defaultOpen={false}>
<MethodLayout>
<MethodContent>
Optional variables to substitute in the template. Only used when `templateId` is provided.
</MethodContent>
<MethodAside>
<AsideSection title="Type">
```typescript
variables?: Record<string, any>
```
</AsideSection>
<AsideSection title="Example">
```typescript
{
templateId: 'welcome-template',
variables: {
userName: 'John Doe',
activationUrl: 'https://app.com/activate/token123',
supportEmail: 'support@yourapp.com'
}
}
```
</AsideSection>
</MethodAside>
</MethodLayout>
</CollapsibleTypesSection>