docs/templates/concepts/emails.mdx (4)

170-170: Fix stray double semicolon in import

There’s an extra semicolon in the import statement.

Apply this diff:

-import { stackServerApp } from '@stackframe/stack';;
+import { stackServerApp } from '@stackframe/stack';

---

105-105: Grammar: add article “a”

Minor grammar improvement in the “Password Reset” bullet.

Apply this diff:

-- **Password Reset**: `password_reset` - Sent when users request password reset
+- **Password Reset**: `password_reset` - Sent when users request a password reset

---

68-68: Prefer unknown over any for template variables

Using unknown is safer and aligns with TS best practices in docs.

Apply this diff:

-  variables?: Record<string, any>;      // Template variables
+  variables?: Record<string, unknown>;  // Template variables

---

172-176: Undefined variable in example (userId)

The snippet uses userId without defining it. Add a line to resolve/derive it for clarity.

Apply this diff:

 export async function inviteUser(email: string) {
-  const result = await stackServerApp.sendEmail({
+  // Resolve the user ID before sending (e.g., create or look up by email)
+  const userId = await getUserIdByEmail(email); // implement accordingly
+
+  const result = await stackServerApp.sendEmail({
     userIds: [userId], // Get user ID first

docs/docs-platform.yml (2)

113-116: Remove trailing spaces (YAML lint error)

YAMLlint flags trailing spaces at Line 113. Trim to keep CI green.

   - path: concepts/backend-integration.mdx
     platforms: ["next", "react", "js", "python"]
-  
+
   - path: concepts/emails.mdx
     platforms: ["next", "react", "js"]  # No Python (server-side email functionality)

---

233-236: Remove trailing spaces (YAML lint error)

YAMLlint flags trailing spaces at Line 233. Trim the blank line.

   - path: sdk/types/user.mdx
     platforms: ["next", "react", "js"]  # No Python
-  
+
   - path: sdk/types/email.mdx
     platforms: ["next", "react", "js"]  # No Python

docs/templates/sdk/types/email.mdx (1)

6-10: Minor wording/spacing nit

There appears to be a double space before “On this page:” per linter context. Use a single space after the preceding sentence to avoid visual glitches in some renderers.

docs/templates/sdk/objects/stack-app.mdx (1)

832-867: Examples/readme quality: consider showing success handling

Optional: add a quick success branch to the examples to mirror other sections (e.g., log success) for parity and clarity.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

docs/templates/concepts/emails.mdx (1)

172-176: Undefined variable in example: userId.

The example references userId without defining it, which will mislead readers.

Apply one of these minimal fixes:

• Keep the function signature and use a placeholder, plus a clarifying comment:

 export async function inviteUser(email: string) {
   const result = await stackServerApp.sendEmail({
-    userIds: [userId], // Get user ID first
+    userIds: [/* userId */], // Look up the user's ID from the email before calling sendEmail
     templateId: 'invitation-template',
     subject: 'You\'re invited!',
     variables: {
       inviteUrl: 'https://yourapp.com/invite/token123',
     },
   });

• Or change the function to accept a userId directly:

-export async function inviteUser(email: string) {
+export async function inviteUser(userId: string) {
   const result = await stackServerApp.sendEmail({
-    userIds: [userId], // Get user ID first
+    userIds: [userId],
     templateId: 'invitation-template',
     subject: 'You\'re invited!',
     variables: {
       inviteUrl: 'https://yourapp.com/invite/token123',
     },
   });

If helpful, I can add a fuller snippet that resolves userId from an email using listUsers({ query: email }) with basic guards.

docs/templates/sdk/types/email.mdx (4)

15-17: Call out constraints at the type-level (mutual exclusivity and requirement).

Make the html vs templateId rules explicit up-front to prevent misuse.

 Options for sending emails via the `sendEmail` method on `StackServerApp`.
 
+<Info type="warning">
+Exactly one of <code>html</code> or <code>templateId</code> must be provided. Do not provide both.
+When <code>templateId</code> is provided, you can pass <code>variables</code>. If <code>html</code> is provided, <code>variables</code> are ignored.
+</Info>

---

19-27: Prefer unknown over any for variables type.

Avoids losing type-safety while still allowing flexible payloads.

 <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
+  variables?: Record<string, unknown>;  //$stack-link-to:#sendemailoptionsvariables
 };`} />

---

55-71: Clarify themeId semantics (false vs null).

“null for no theme, false for default theme” is easy to misread. Please confirm the intended behavior and consider rephrasing with a short table or explicit examples (what happens when omitted/undefined).

---

183-185: Align snippet with safer typing (unknown).

Mirror the top-level type recommendation in the property snippet.

-        variables?: Record<string, any>
+        variables?: Record<string, unknown>

docs/templates/sdk/objects/stack-app.mdx (1)

803-873: Add constraints note, narrow KnownErrors, and make example logging consistent.

• Add a short constraints note to prevent passing both html and templateId.
• Narrow the KnownErrors in the signature to the three listed errors for clarity.
• Log error.message (or error.code) like other examples for consistency.

 <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
+
+    <Info type="warning">
+    Exactly one of <code>html</code> or <code>templateId</code> must be provided. Do not provide both.
+    When <code>templateId</code> is provided, you can pass <code>variables</code>. If <code>html</code> is provided, <code>variables</code> are ignored.
+    </Info>
 
     **Returns:** `Promise<Result<void, KnownErrors>>`
 
     The method returns a `Result` object that can contain specific error types:
@@
 <AsideSection title="Signature">
 
 ```typescript
-declare function sendEmail(options: SendEmailOptions): Promise<Result<void, KnownErrors>>;
+declare function sendEmail(
+  options: SendEmailOptions
+): Promise<Result<
+  void,
+  | KnownErrors["RequiresCustomEmailServer"]
+  | KnownErrors["SchemaError"]
+  | KnownErrors["UserIdDoesNotExist"]
+>>;

@@ if (result.status === 'error') { - console.error('Failed to send email:', result.error); + console.error('Failed to send email:', result.error.message); } @@ if (result.status === 'error') { - console.error('Failed to send email:', result.error); + console.error('Failed to send email:', result.error.message); } ```

docs/templates/concepts/emails.mdx (1)

24-24: Standardize import path for consistency.

Elsewhere you import from '@stackframe/stack'. Using a relative './stack' here may confuse readers.

-import { stackServerApp } from './stack';
+import { stackServerApp } from '@stackframe/stack';

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

docs/templates/concepts/emails.mdx (1)

183-191: Example bug: userId is undefined in sendEmail payload.

Pass a userId (or show a lookup) before calling sendEmail. Easiest fix: accept userId in the function signature. This was flagged previously as well.

-export async function inviteUser(email: string) {
+export async function inviteUser(userId: string) {
   const result = await stackServerApp.sendEmail({
-    userIds: [userId], // Get user ID first
+    userIds: [userId],
     templateId: 'invitation-template',
     subject: 'You\'re invited!',
     variables: {
       inviteUrl: 'https://yourapp.com/invite/token123',
     },
   });

If you intend to accept an email, add a brief preceding step/comment to resolve userId from that email via your Users API, then pass it here.

docs/templates/concepts/emails.mdx (7)

6-6: Grammar fix: clarify subject and agreement.

"provides emails that allows" → "provides an email system that allows".

-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.
+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.

---

35-35: Make imports consistent and canonical.

Two examples use different import sources. Prefer the package import for consistency unless this page intentionally demonstrates a local helper. If not intentional, align them.

-import { stackServerApp } from './stack';
+import { stackServerApp } from '@stackframe/stack';

If you do intend to show a local helper, add a short note explaining that './stack' re-exports a configured instance.

Also applies to: 181-181

---

54-65: Template example: avoid implying subject is required when using template.

If templates provide their own subject (common), including subject here may confuse readers about precedence. Either remove it or add a note that it overrides the template subject.

 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',
   },
 });

---

69-69: Explain themeId semantics (false vs null).

You document themeId?: string | null | false but not what null/false mean. Add a one-liner to prevent ambiguity.

-The `sendEmail` method accepts the following options:
+The `sendEmail` method accepts the following options:
+Note: set `themeId` to `false` to disable theming, or to `null` to use the project's default theme.

---

71-81: Avoid duplicating SDK types in Concepts; link to the single source of truth.

Inlining SendEmailOptions risks drift versus the SDK docs (this PR also adds docs/templates/sdk/types/email.mdx). Replace this block with a link/reference to the SDK type.

-```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
-};
-```
+See the SDK type reference for the authoritative shape: [SendEmailOptions](/sdk/types/email).

---

173-176: Grammar: singular subject.

"Emails integrates" → "The email system integrates".

-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.
+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.

---

21-27: Minor style: terminate bullets with periods for consistency.

Optional polish to improve readability and satisfy grammar linters.

-- **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
+- **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.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

docs/templates/concepts/emails.mdx (1)

83-107: Nice, concrete error-handling example.

Clear mapping of error codes with a concise switch improves developer experience.