init emails docs (#848)

Updates existing docs to include emails endpoints, and adds new docs for emails in general docs, as well as SDK docs.  ---- > [!IMPORTANT] > Introduces server-side email sending API and updates documentation to include comprehensive guides and SDK references for email functionality. > > - **Behavior**: > - Introduces `sendEmail` API in `route.tsx` for sending emails with HTML or templates. > - Handles errors like missing user IDs and schema errors. > - **Documentation**: > - Adds `concepts/emails.mdx` detailing email types, sending methods, and configuration. > - Updates `docs-platform.yml` and `meta.json` to include email documentation. > - Adds `sdk/types/email.mdx` for `SendEmailOptions` type reference. > - **UI/Style**: > - Adds badge style for `sendEmailOptions` in `method-layout.tsx`. > > <sup>This description was created by </sup>[<img alt="Ellipsis" src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup> for 2edeb57734. You can [customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this summary. It will automatically update as commits are pushed.</sup> ----   ## Summary by CodeRabbit * **New Features** * Introduced server-side email sending API with templates, theming, variables, and notification categories. * **Documentation** * Added comprehensive Emails concept guide and SDK references (sendEmail, SendEmailOptions). * Extended SDK index and platform navigation to include Email docs for Next/React/JS. * Added an “Emails” functional tag to API docs and route metadata. * **Style** * Added a distinct badge style for SendEmailOptions in the docs UI.  --------- Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
2026-06-04 21:04:37 +08:00 · 2025-08-21 12:05:48 -05:00 · 2025-08-21 12:05:48 -05:00 · 4b06bca59e
commit 4b06bca59e
parent f43a2e1a1e
10 changed files with 491 additions and 3 deletions
--- a/apps/backend/src/app/api/latest/emails/send-email/route.tsx
+++ b/apps/backend/src/app/api/latest/emails/send-email/route.tsx
@ -3,12 +3,11 @@ import { getEmailConfig, sendEmail } from "@/lib/emails";
 import { getNotificationCategoryByName, hasNotificationEnabled } from "@/lib/notification-categories";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { KnownErrors } from "@stackframe/stack-shared";
 import { adaptSchema, serverOrHigherAuthTypeSchema, templateThemeIdSchema, yupArray, yupMixed, yupNumber, yupObject, yupRecord, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
-import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
-import { throwErr } from "@stackframe/stack-shared/dist/utils/errors";
+import { StatusError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
 import { unsubscribeLinkVerificationCodeHandler } from "../unsubscribe-link/verification-handler";
-import { KnownErrors } from "@stackframe/stack-shared";

 type UserResult = {
  user_id: string,
@ -19,6 +18,7 @@ export const POST = createSmartRouteHandler({
  metadata: {
    summary: "Send email",
    description: "Send an email to a list of users. The content field should contain either {html, subject, notification_category_name} for HTML emails or {template_id, variables} for template-based emails.",
+    tags: ["Emails"],
  },
  request: yupObject({
    auth: yupObject({
--- a/docs/docs-platform.yml
+++ b/docs/docs-platform.yml
@ -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
--- a/docs/scripts/generate-functional-api-docs.mjs
+++ b/docs/scripts/generate-functional-api-docs.mjs
@ -13,6 +13,7 @@ const FUNCTIONAL_TAGS = [
  'API Keys', 
  'CLI Authentication',
  'Contact Channels',
+  'Emails',
  'Oauth', // Note: OpenAPI uses "Oauth" not "OAuth"
  'OTP',
  'Password',
--- a/docs/src/components/ui/method-layout.tsx
+++ b/docs/src/components/ui/method-layout.tsx
@ -376,6 +376,9 @@ export function CollapsibleTypesSection({
        case 'project': {
          return 'bg-lime-50 dark:bg-lime-950/50 text-lime-700 dark:text-lime-300';
        }
+        case 'sendemailoptions': {
+          return 'bg-rose-50 dark:bg-rose-950/50 text-rose-700 dark:text-rose-300';
+        }
        default: {
          return 'bg-gray-50 dark:bg-gray-950/50 text-gray-700 dark:text-gray-300';
        }
--- a/docs/templates/concepts/emails.mdx
+++ b/docs/templates/concepts/emails.mdx
@ -0,0 +1,197 @@
+---
+title: Emails
+description: Send custom emails to your users with Stack Auth's email system.
+---
+
+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.
+
+## Email Types:
+There are two types of emails that you can send to your users:
+- **Transactional Emails**: Transactional emails are those required for your user to use your application. These emails cannot be opted out of.
+- **Marketing Emails**: Marketing emails always contain an unsubscribe link and may be more general marketing material related to your application/company.
+
+<Info>
+Never send marketing emails as transactional emails, as this can quickly lead to your domain being blacklisted by email spam filters.
+</Info>
+
+
+
+## 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
+
+Email configuration is managed through the Stack Auth dashboard or admin API, not directly in your application code. You have two options:
+
+### Shared Email Provider (Development)
+
+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.
+
+- Go to your project's Email settings in the dashboard
+- Select "Shared" as your email server type
+- No additional configuration required
+
+### Custom Email Server (Production)
+
+For production, configure your own SMTP server through the dashboard:
+
+- Go to your project's Email settings in the dashboard  
+- Select "Custom SMTP server" as your email server type
+- Configure the following settings:
+  - **Host**: Your SMTP server hostname (e.g., `smtp.yourprovider.com`)
+  - **Port**: SMTP port (typically 587 for TLS or 465 for SSL)
+  - **Username**: Your SMTP username
+  - **Password**: Your SMTP password
+  - **Sender Email**: The email address emails will be sent from
+  - **Sender Name**: The display name for your emails
+
+The dashboard will automatically test your configuration when you save it.
+
+## 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
+
+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.
+
+For custom email flows, use the `sendEmail` method from your server-side code:
+
+```typescript
+// In your API route or server action
+import { stackServerApp } from '@stackframe/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.
--- a/docs/templates/meta.json
+++ b/docs/templates/meta.json
@ -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",
--- a/docs/templates/sdk/index.mdx
+++ b/docs/templates/sdk/index.mdx
@ -40,6 +40,12 @@ export const sdkSections = [
      { name: "ServerTeamProfile", href: "types/team-profile#serverteamprofile", icon: "type" },
    ]
  },
+  {
+    title: "Email",
+    items: [
+      { name: "SendEmailOptions", href: "types/email#sendemailoptions", icon: "type" },
+    ]
+  },
  {
    title: "Hooks", 
    items: [
--- a/docs/templates/sdk/meta.json
+++ b/docs/templates/sdk/meta.json
@ -14,6 +14,7 @@
    "types/team-permission",
    "types/team-profile",
    "types/contact-channel",
+    "types/email",
    "types/api-key",
    "types/project",
    "types/connected-account",
--- a/docs/templates/sdk/objects/stack-app.mdx
+++ b/docs/templates/sdk/objects/stack-app.mdx
@ -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#sendemailoptions)) - 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}>
--- a/docs/templates/sdk/types/email.mdx
+++ b/docs/templates/sdk/types/email.mdx
@ -0,0 +1,201 @@
+---
+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](#sendemailoptions)
+
+---
+
+# `SendEmailOptions`
+
+Options for sending emails via the `sendEmail` method on `StackServerApp`.
+
+### Table of Contents
+
+<ClickableTableOfContents code={`type SendEmailOptions = {
+  userIds: string[];  //$stack-link-to:#sendemailoptionsuserids
+  themeId?: string | null | false;  //$stack-link-to:#sendemailoptionsthemeid
+  subject?: string;  //$stack-link-to:#sendemailoptionssubject
+  notificationCategoryName?: string;  //$stack-link-to:#sendemailoptionsnotificationcategoryname
+  html?: string;  //$stack-link-to:#sendemailoptionshtml
+  templateId?: string;  //$stack-link-to:#sendemailoptionstemplateid
+  variables?: Record<string, any>;  //$stack-link-to:#sendemailoptionsvariables
+};`} />
+
+<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. Cannot be used together with `templateId` or `variables`.
+    </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. Cannot be used together with `html`.
+    </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>