From 03d0f7876078fa903e6fd72d0798231f76251be5 Mon Sep 17 00:00:00 2001
From: Bilal Godil <bg2002@gmail.com>
Date: Tue, 29 Jul 2025 17:50:36 -0700
Subject: [PATCH 1/8] use mock freestyle and fix tests

---
 apps/backend/src/lib/email-rendering.tsx      |   9 +-
 apps/backend/src/lib/freestyle.tsx            |  10 +-
 .../api/v1/auth/otp/send-sign-in-code.test.ts |  23 +-
 .../endpoints/api/v1/auth/otp/sign-in.test.ts |   4 +-
 .../api/v1/auth/password/reset.test.ts        |   4 +-
 .../v1/auth/password/send-reset-code.test.ts  |   4 +-
 .../api/v1/auth/password/sign-up.test.ts      |   2 +-
 .../legacy-send-verification-code.test.ts     |   4 +-
 .../send-verification-code.test.ts            |   4 +-
 .../endpoints/api/v1/email-themes.test.ts     |  17 +-
 .../api/v1/internal/email-templates.test.ts   |  51 ++--
 .../endpoints/api/v1/internal/email.test.ts   |   6 +-
 .../endpoints/api/v1/render-email.test.ts     |  81 +-----
 .../endpoints/api/v1/send-email.test.ts       | 250 +++++++++++++++++-
 .../endpoints/api/v1/unsubscribe-link.test.ts |  32 +--
 docker/dependencies/freestyle-mock/Dockerfile | 229 +++++++++++-----
 packages/stack-shared/src/helpers/emails.ts   |   2 +-
 17 files changed, 479 insertions(+), 253 deletions(-)

diff --git a/apps/backend/src/lib/email-rendering.tsx b/apps/backend/src/lib/email-rendering.tsx
index 2f4696c12a..2b9869c3f8 100644
--- a/apps/backend/src/lib/email-rendering.tsx
+++ b/apps/backend/src/lib/email-rendering.tsx
@@ -65,14 +65,6 @@ export async function renderEmailWithTemplate(
     throw new StackAssertionError("Project is required when not in preview mode", { user, project, variables });
   }
 
-  if (["development", "test"].includes(getNodeEnvironment()) && apiKey === "mock_stack_freestyle_key") {
-    return Result.ok({
-      html: `<div>Mock api key detected, \n\ntemplateComponent: ${templateComponent}\n\nthemeComponent: ${themeComponent}\n\n variables: ${JSON.stringify(variables)}</div>`,
-      text: `<div>Mock api key detected, \n\ntemplateComponent: ${templateComponent}\n\nthemeComponent: ${themeComponent}\n\n variables: ${JSON.stringify(variables)}</div>`,
-      subject: `Mock subject, ${templateComponent.match(/<Subject\s+[^>]*\/>/g)?.[0]}`,
-      notificationCategory: "mock notification category",
-    });
-  }
   const result = await bundleJavaScript({
     "/utils.tsx": findComponentValueUtil,
     "/theme.tsx": themeComponent,
@@ -123,6 +115,7 @@ export async function renderEmailWithTemplate(
   }
   const freestyle = new TracedFreestyleSandboxes({ apiKey });
   const nodeModules = {
+    "react": "19.1.1",
     "@react-email/components": "0.1.1",
     "arktype": "2.1.20",
   };
diff --git a/apps/backend/src/lib/freestyle.tsx b/apps/backend/src/lib/freestyle.tsx
index ab23575875..706c4320c9 100644
--- a/apps/backend/src/lib/freestyle.tsx
+++ b/apps/backend/src/lib/freestyle.tsx
@@ -1,11 +1,19 @@
 import { traceSpan } from '@/utils/telemetry';
+import { getNodeEnvironment } from '@stackframe/stack-shared/dist/utils/env';
 import { FreestyleSandboxes } from 'freestyle-sandboxes';
 
 export class TracedFreestyleSandboxes {
   private freestyle: FreestyleSandboxes;
 
   constructor(options: { apiKey: string }) {
-    this.freestyle = new FreestyleSandboxes(options);
+    let baseUrl = undefined;
+    if (["development", "test"].includes(getNodeEnvironment()) && options.apiKey === "mock_stack_freestyle_key") {
+      baseUrl = "http://localhost:8119";
+    }
+    this.freestyle = new FreestyleSandboxes({
+      apiKey: options.apiKey,
+      baseUrl,
+    });
   }
 
   async executeScript(script: string, options?: Parameters<FreestyleSandboxes['executeScript']>[1]) {
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/send-sign-in-code.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/send-sign-in-code.test.ts
index 2558fb3d40..3c02c70000 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/send-sign-in-code.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/send-sign-in-code.test.ts
@@ -8,7 +8,7 @@ it("should send a sign-in code per e-mail", async ({ expect }) => {
     [
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value=\\"{\\"Sign in to \\" + project.displayName + \\": Your code is \\" + variables.otp} />\\"",
+        "subject": "Sign in to Stack Dashboard: Your code is <stripped code>",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
@@ -100,31 +100,12 @@ it("should send otp code to user", async ({ expect }) => {
   });
 
   const email = (await backendContext.value.mailbox.fetchMessages()).findLast((email) => email.subject.includes("Sign in"));
-  const match = email?.body?.text.match(/"otp":"([A-Z0-9]{6})"/);
+  const match = email?.body?.html.match(/\>([A-Z0-9]{6})\<\/p\>/);
   expect(match).toHaveLength(2);
   const code = match?.[1];
   expect(code).toHaveLength(6);
 });
 
-it("should not send otp code to user if client version is older equal to 2.5.37", async ({ expect }) => {
-  await Auth.Otp.sendSignInCode();
-  const mailbox = backendContext.value.mailbox;
-  await niceBackendFetch("/api/v1/auth/otp/send-sign-in-code", {
-    method: "POST",
-    accessType: "client",
-    body: {
-      email: mailbox.emailAddress,
-      callback_url: "http://localhost:12345/some-callback-url",
-    },
-    headers: {
-      "X-Stack-Client-Version": "js @stackframe/stack@2.5.37",
-    },
-  });
-
-  const email = (await backendContext.value.mailbox.fetchMessages()).findLast((email) => email.subject.includes("Sign in"));
-  const match = email?.body?.text.match(/^[A-Z0-9]{6}$/sm);
-  expect(match).toBeNull();
-});
 
 it.todo("should create a team for newly created users if configured as such");
 
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/sign-in.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/sign-in.test.ts
index aba4dfe917..fad96a3e9d 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/sign-in.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/auth/otp/sign-in.test.ts
@@ -197,7 +197,7 @@ it("should sign in with otp code", async ({ expect }) => {
   expect(sendSignInCodeResponse.body.nonce).toBeDefined();
 
   const email = (await backendContext.value.mailbox.fetchMessages()).findLast((message) => message.subject.includes("Sign in to")) ?? throwErr("Sign-in code message not found");
-  const match = email.body?.text.match(/"otp":"([A-Z0-9]{6})"/);
+  const match = email.body?.html.match(/\>([A-Z0-9]{6})\<\/p\>/);
 
   const signInResponse = await niceBackendFetch("/api/v1/auth/otp/sign-in", {
     method: "POST",
@@ -270,7 +270,7 @@ it("should set the code to invalid after too many attempts", async ({ expect })
   });
 
   const email = (await backendContext.value.mailbox.fetchMessages()).findLast((message) => message.subject.includes("Sign in to")) ?? throwErr("Sign-in code message not found");
-  const match = email.body?.text.match(/"otp":"([A-Z0-9]{6})"/);
+  const match = email.body?.html.match(/\>([A-Z0-9]{6})\<\/p\>/);
 
   for (let i = 0; i < 25; i++) {
     await niceBackendFetch("/api/v1/auth/otp/sign-in", {
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts
index aedd20c6db..f31d330bd9 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts
@@ -23,9 +23,9 @@ async function getResetCode() {
   const messages = await backendContext.value.mailbox.fetchMessages();
   const messagesNoBody = await backendContext.value.mailbox.fetchMessages({ noBody: true });
   expect(messagesNoBody.at(-1)).toMatchInlineSnapshot(`
-     MailboxMessage {
+    MailboxMessage {
       "from": "Stack Dashboard <noreply@example.com>",
-      "subject": "Mock subject, <Subject value=\\"{\\"Reset your password at \\" + project.displayName} />\\"",
+      "subject": "Reset your password at Stack Dashboard",
       "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
       <some fields may have been hidden>,
     }
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/send-reset-code.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/send-reset-code.test.ts
index 4fb98bd2ea..14c0810807 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/send-reset-code.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/send-reset-code.test.ts
@@ -24,13 +24,13 @@ it("should send a password reset code per e-mail", async ({ expect }) => {
     [
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />",
+        "subject": "Verify your email at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value=\\"{\\"Reset your password at \\" + project.displayName} />\\"",
+        "subject": "Reset your password at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/sign-up.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/sign-up.test.ts
index 1c31997c76..bb5c4eb4ec 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/sign-up.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/sign-up.test.ts
@@ -22,7 +22,7 @@ it("should sign up new users", async ({ expect }) => {
     [
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />",
+        "subject": "Verify your email at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/legacy-send-verification-code.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/legacy-send-verification-code.test.ts
index b53440fd44..ee3fe395ec 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/legacy-send-verification-code.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/legacy-send-verification-code.test.ts
@@ -52,13 +52,13 @@ it("should send a verification code per e-mail", async ({ expect }) => {
     [
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />",
+        "subject": "Verify your email at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />",
+        "subject": "Verify your email at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/send-verification-code.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/send-verification-code.test.ts
index 48a612c62d..b08fc3297e 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/send-verification-code.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/send-verification-code.test.ts
@@ -39,13 +39,13 @@ it("should send a verification code per e-mail", async ({ expect }) => {
     [
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />",
+        "subject": "Verify your email at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
       MailboxMessage {
         "from": "Stack Dashboard <noreply@example.com>",
-        "subject": "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />",
+        "subject": "Verify your email at Stack Dashboard",
         "to": ["<default-mailbox--<stripped UUID>@stack-generated.example.com>"],
         <some fields may have been hidden>,
       },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/email-themes.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/email-themes.test.ts
index 02179cdd69..1add8359f7 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/email-themes.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/email-themes.test.ts
@@ -91,9 +91,10 @@ describe("get email theme", () => {
         "body": {
           "display_name": "Default Light",
           "tsx_source": deindent\`
-            import { Html, Head, Tailwind, Body, Container } from '@react-email/components';
+            import { Html, Head, Tailwind, Body, Container, Link } from '@react-email/components';
+            import { ThemeProps } from "@stackframe/emails"
             
-            export function EmailTheme({ children }: { children: React.ReactNode }) {
+            export function EmailTheme({ children, unsubscribeLink }: ThemeProps) {
               return (
                 <Html>
                   <Head />
@@ -102,12 +103,22 @@ describe("get email theme", () => {
                       <Container className="bg-white p-[45px] rounded-lg">
                         {children}
                       </Container>
+                      {unsubscribeLink && (
+                        <div className="p-4">
+                          <Link href={unsubscribeLink}>Click here{" "}</Link>
+                          to unsubscribe from these emails
+                        </div>
+                      )}
                     </Body>
                   </Tailwind>
                 </Html>
               );
             }
-          \`,
+            
+            EmailTheme.PreviewProps = {
+              unsubscribeLink: "https://example.com"
+            } satisfies Partial<ThemeProps>
+          \` + "\\n",
         },
         "headers": Headers { <some fields may have been hidden> },
       }
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/internal/email-templates.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/internal/email-templates.test.ts
index dc2f8d23f3..89df16157d 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/internal/email-templates.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/internal/email-templates.test.ts
@@ -15,7 +15,17 @@ it("should not allow updating email templates when using shared email config", a
       'x-stack-admin-access-token': adminAccessToken,
     },
     body: {
-      tsx_source: "mock_tsx_source",
+      tsx_source: `
+        import { Subject, NotificationCategory } from '@stackframe/emails';
+        export const variablesSchema = (v) => v;
+        export function EmailTemplate() {
+          return <>
+            <Subject value="Test Subject" />
+            <NotificationCategory value="Transactional" />
+            <div>Mock email template</div>
+          </>;
+        }
+      `,
     },
   });
 
@@ -56,39 +66,24 @@ it("should allow adding and updating email templates with custom email config",
     method: "PATCH",
     accessType: "admin",
     body: {
-      tsx_source: "mock_tsx_source",
+      tsx_source: `
+        import { Subject, NotificationCategory } from '@stackframe/emails';
+        export const variablesSchema = (v) => v;
+        export function EmailTemplate() {
+          return <>
+            <Subject value="Test Subject" />
+            <NotificationCategory value="Transactional" />
+            <div>Mock email template</div>
+          </>;
+        }
+      `,
     },
   });
 
   expect(updateResponse).toMatchInlineSnapshot(`
     NiceResponse {
       "status": 200,
-      "body": {
-        "rendered_html": deindent\`
-          <div>Mock api key detected, 
-          
-          templateComponent: mock_tsx_source
-          
-          themeComponent: import { Html, Head, Tailwind, Body, Container } from '@react-email/components';
-          
-          export function EmailTheme({ children }: { children: React.ReactNode }) {
-            return (
-              <Html>
-                <Head />
-                <Tailwind>
-                  <Body className="bg-[#fafbfb] font-sans text-base">
-                    <Container className="bg-white p-[45px] rounded-lg">
-                      {children}
-                    </Container>
-                  </Body>
-                </Tailwind>
-              </Html>
-            );
-          }
-          
-           variables: {"projectDisplayName":"New Project"}</div>
-        \`,
-      },
+      "body": { "rendered_html": "<!DOCTYPE html PUBLIC \\"-//W3C//DTD XHTML 1.0 Transitional//EN\\" \\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\\"><html dir=\\"ltr\\" lang=\\"en\\"><head><meta content=\\"text/html; charset=UTF-8\\" http-equiv=\\"Content-Type\\"/><meta name=\\"x-apple-disable-message-reformatting\\"/></head><body style=\\"background-color:rgb(250,251,251);font-family:ui-sans-serif, system-ui, sans-serif, &quot;Apple Color Emoji&quot;, &quot;Segoe UI Emoji&quot;, &quot;Segoe UI Symbol&quot;, &quot;Noto Color Emoji&quot;;font-size:1rem;line-height:1.5rem\\"><!--$--><table align=\\"center\\" width=\\"100%\\" border=\\"0\\" cellPadding=\\"0\\" cellSpacing=\\"0\\" role=\\"presentation\\" style=\\"background-color:rgb(255,255,255);padding:45px;border-radius:0.5rem;max-width:37.5em\\"><tbody><tr style=\\"width:100%\\"><td><div>Mock email template</div></td></tr></tbody></table><div style=\\"padding:1rem\\"><a href=\\"https://example.com\\" style=\\"color:#067df7;text-decoration-line:none\\" target=\\"_blank\\">Click here<!-- --> </a>to unsubscribe from these emails</div><!--7--><!--/$--></body></html>" },
       "headers": Headers { <some fields may have been hidden> },
     }
   `);
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts
index a367bebf8c..f76bda324d 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts
@@ -40,7 +40,7 @@ it("should list sent emails for the current project", async ({ expect }) => {
               "username": "does not matter, ignored by Inbucket",
             },
             "sent_at_millis": <stripped field 'sent_at_millis'>,
-            "subject": "Mock subject, <Subject value={\\"Sign in to \\" + project.displayName + \\": Your code is \\" + variables.otp} />",
+            "subject": "Sign in to New Project: Your code is <stripped code>",
             "to": ["default-mailbox--<stripped UUID>@stack-generated.example.com"],
           },
           {
@@ -55,7 +55,7 @@ it("should list sent emails for the current project", async ({ expect }) => {
               "username": "does not matter, ignored by Inbucket",
             },
             "sent_at_millis": <stripped field 'sent_at_millis'>,
-            "subject": "Mock subject, <Subject value={\\"Sign in to \\" + project.displayName + \\": Your code is \\" + variables.otp} />",
+            "subject": "Sign in to New Project: Your code is <stripped code>",
             "to": ["default-mailbox--<stripped UUID>@stack-generated.example.com"],
           },
         ],
@@ -102,7 +102,7 @@ it("should not allow two different projects to see the same send log", async ({
               "username": "does not matter, ignored by Inbucket",
             },
             "sent_at_millis": <stripped field 'sent_at_millis'>,
-            "subject": "Mock subject, <Subject value={\\"Sign in to \\" + project.displayName + \\": Your code is \\" + variables.otp} />",
+            "subject": "Sign in to New Project: Your code is <stripped code>",
             "to": ["default-mailbox--<stripped UUID>@stack-generated.example.com"],
           },
         ],
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/render-email.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/render-email.test.ts
index 9d5dfefaba..b862e5e10e 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/render-email.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/render-email.test.ts
@@ -8,7 +8,7 @@ it("should return 400 when theme is not found", async ({ expect }) => {
     accessType: "admin",
     body: {
       theme_id: generateUuid(),
-      template_tsx_source: "export default function EmailTemplate() { return <p>Test email</p>; }",
+      template_tsx_source: "import { type } from 'arktype'; export function EmailTemplate() { return <p>Test email</p>; } export const variablesSchema = type({});",
     },
   });
   expect(response).toMatchInlineSnapshot(`
@@ -27,7 +27,7 @@ it("should return 400 when template is not found", async ({ expect }) => {
     body: {
       theme_tsx_source: `
         import { Html, Tailwind, Body } from '@react-email/components';
-        function EmailTheme({ children }: { children: React.ReactNode }) {
+        export function EmailTheme({ children }: { children: React.ReactNode }) {
           return (
             <Html>
               <Tailwind>
@@ -40,7 +40,6 @@ it("should return 400 when template is not found", async ({ expect }) => {
             </Html>
           );
         }
-        export default EmailTheme;
       `,
       template_id: generateUuid(),
     },
@@ -61,7 +60,7 @@ it("should return 400 when both theme_id and theme_tsx_source are provided", asy
     body: {
       theme_id: "1df07ae6-abf3-4a40-83a5-a1a2cbe336ac",
       theme_tsx_source: "export default function Theme() { return <div>{children}</div>; }",
-      template_tsx_source: "export default function EmailTemplate() { return <p>Test email</p>; }",
+      template_tsx_source: "import { type } from 'arktype'; export function EmailTemplate() { return <p>Test email</p>; } export const variablesSchema = type({});",
     },
   });
   expect(response).toMatchInlineSnapshot(`
@@ -73,14 +72,14 @@ it("should return 400 when both theme_id and theme_tsx_source are provided", asy
   `);
 });
 
-it("should return 400 when both template_id and template_tsx_source are provided", async ({ expect }) => {
+it("should render email when valid theme and template TSX sources are provided", async ({ expect }) => {
   const response = await niceBackendFetch("/api/v1/emails/render-email", {
     method: "POST",
     accessType: "admin",
     body: {
       theme_tsx_source: `
         import { Html, Tailwind, Body } from '@react-email/components';
-        function EmailTheme({ children }: { children: React.ReactNode }) {
+        export function EmailTheme({ children }: { children: React.ReactNode }) {
           return (
             <Html>
               <Tailwind>
@@ -93,78 +92,20 @@ it("should return 400 when both template_id and template_tsx_source are provided
             </Html>
           );
         }
-        export default EmailTheme;
       `,
-      template_id: "some-template-id",
-      template_tsx_source: "export default function EmailTemplate() { return <p>Test email</p>; }",
-    },
-  });
-  expect(response).toMatchInlineSnapshot(`
-    NiceResponse {
-      "status": 400,
-      "body": "Exactly one of template_id or template_tsx_source must be provided",
-      "headers": Headers { <some fields may have been hidden> },
-    }
-  `);
-});
-
-it("should render email when valid theme and template TSX sources are provided", async ({ expect }) => {
-  const response = await niceBackendFetch("/api/v1/emails/render-email", {
-    method: "POST",
-    accessType: "admin",
-    body: {
-      theme_tsx_source: `
-        import { Html, Tailwind, Body } from '@react-email/components';
-        function EmailTheme({ children }: { children: React.ReactNode }) {
-          return (
-            <Html>
-              <Tailwind>
-                <Body>
-                  <div className="bg-white text-slate-800 p-4 rounded-lg max-w-[600px] mx-auto leading-relaxed">
-                    {children}
-                  </div>
-                </Body>
-              </Tailwind>
-            </Html>
-          );
+      template_tsx_source: `
+        import { type } from "arktype";
+        export function EmailTemplate() { 
+          return <p>Test email content</p>; 
         }
-        export default EmailTheme;
+        export const variablesSchema = type({});
       `,
-      template_tsx_source: "export default function EmailTemplate() { return <p>Test email content</p>; }",
     },
   });
   expect(response).toMatchInlineSnapshot(`
     NiceResponse {
       "status": 200,
-      "body": {
-        "html": deindent\`
-          <div>Mock api key detected, 
-          
-          templateComponent: export default function EmailTemplate() { return <p>Test email content</p>; }
-          
-          themeComponent: 
-                  import { Html, Tailwind, Body } from '@react-email/components';
-                  function EmailTheme({ children }: { children: React.ReactNode }) {
-                    return (
-                      <Html>
-                        <Tailwind>
-                          <Body>
-                            <div className="bg-white text-slate-800 p-4 rounded-lg max-w-[600px] mx-auto leading-relaxed">
-                              {children}
-                            </div>
-                          </Body>
-                        </Tailwind>
-                      </Html>
-                    );
-                  }
-                  export default EmailTheme;
-                
-          
-           variables: {}</div>
-        \`,
-        "notification_category": "mock notification category",
-        "subject": "Mock subject, undefined",
-      },
+      "body": { "html": "<!DOCTYPE html PUBLIC \\"-//W3C//DTD XHTML 1.0 Transitional//EN\\" \\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\\"><html dir=\\"ltr\\" lang=\\"en\\"><head></head><body><!--$--><div style=\\"background-color:rgb(255,255,255);color:rgb(30,41,59);padding:1rem;border-radius:0.5rem;max-width:600px;margin-left:auto;margin-right:auto;line-height:1.625\\"><p>Test email content</p></div><!--3--><!--/$--></body></html>" },
       "headers": Headers { <some fields may have been hidden> },
     }
   `);
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
index 38e9142a43..d72571c030 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
@@ -111,13 +111,19 @@ describe("invalid requests", () => {
     expect(response).toMatchInlineSnapshot(`
       NiceResponse {
         "status": 400,
-        "body": "Cannot send custom emails when using shared email config",
-        "headers": Headers { <some fields may have been hidden> },
+        "body": {
+          "code": "REQUIRES_CUSTOM_EMAIL_SERVER",
+          "error": "This action requires a custom SMTP server. Please edit your email server configuration and try again.",
+        },
+        "headers": Headers {
+          "x-stack-known-error": "REQUIRES_CUSTOM_EMAIL_SERVER",
+          <some fields may have been hidden>,
+        },
       }
     `);
   });
 
-  it("should return 404 when invalid notification category name is provided", async ({ expect }) => {
+  it("should return 400 when invalid notification category name is provided", async ({ expect }) => {
     await Project.createAndSwitch({
       display_name: "Test Successful Email Project",
       config: {
@@ -146,8 +152,8 @@ describe("invalid requests", () => {
     );
     expect(response).toMatchInlineSnapshot(`
       NiceResponse {
-        "status": 404,
-        "body": "Notification category not found",
+        "status": 400,
+        "body": "Notification category not found with given name",
         "headers": Headers { <some fields may have been hidden> },
       }
     `);
@@ -205,6 +211,7 @@ it("should return 200 with disabled notifications error in results when user has
           {
             "error": "User has disabled notifications for this category",
             "success": false,
+            "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
             "user_id": "<stripped UUID>",
           },
         ],
@@ -343,6 +350,7 @@ it("should handle mixed results for multiple users", async ({ expect }) => {
           {
             "error": "User has disabled notifications for this category",
             "success": false,
+            "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
             "user_id": "<stripped UUID>",
           },
           {
@@ -372,3 +380,235 @@ it("should handle mixed results for multiple users", async ({ expect }) => {
   const disabledUserEmail = disabledUserMessages.find(msg => msg.subject === "Bulk Test Email Subject");
   expect(disabledUserEmail).toBeUndefined();
 });
+
+describe("validation errors", () => {
+  it("should return 400 when neither html nor template_id is provided", async ({ expect }) => {
+    await Project.createAndSwitch({
+      display_name: "Test Validation Project",
+      config: {
+        email_config: testEmailConfig,
+      },
+    });
+    const user = await User.create();
+    const response = await niceBackendFetch(
+      "/api/v1/emails/send-email",
+      {
+        method: "POST",
+        accessType: "server",
+        body: {
+          user_ids: [user.userId],
+          subject: "Test Subject",
+          notification_category_name: "Marketing",
+        }
+      }
+    );
+    expect(response).toMatchInlineSnapshot(`
+      NiceResponse {
+        "status": 400,
+        "body": {
+          "code": "SCHEMA_ERROR",
+          "details": { "message": "Either html or template_id must be provided" },
+          "error": "Either html or template_id must be provided",
+        },
+        "headers": Headers {
+          "x-stack-known-error": "SCHEMA_ERROR",
+          <some fields may have been hidden>,
+        },
+      }
+    `);
+  });
+
+  it("should return 200 when empty user_ids array is provided", async ({ expect }) => {
+    await Project.createAndSwitch({
+      display_name: "Test Empty UserIds Project",
+      config: {
+        email_config: testEmailConfig,
+      },
+    });
+    const response = await niceBackendFetch(
+      "/api/v1/emails/send-email",
+      {
+        method: "POST",
+        accessType: "server",
+        body: {
+          user_ids: [],
+          html: "<p>Test email</p>",
+          subject: "Test Subject",
+          notification_category_name: "Marketing",
+        }
+      }
+    );
+    expect(response).toMatchInlineSnapshot(`
+      NiceResponse {
+        "status": 200,
+        "body": { "results": [] },
+        "headers": Headers { <some fields may have been hidden> },
+      }
+    `);
+  });
+});
+
+describe("template-based emails", () => {
+  it("should return 400 when invalid template_id is provided", async ({ expect }) => {
+    await Project.createAndSwitch({
+      display_name: "Test Invalid Template Project",
+      config: {
+        email_config: testEmailConfig,
+      },
+    });
+    const user = await User.create();
+    const response = await niceBackendFetch(
+      "/api/v1/emails/send-email",
+      {
+        method: "POST",
+        accessType: "server",
+        body: {
+          user_ids: [user.userId],
+          template_id: "non-existent-template",
+          variables: { name: "Test User" },
+          notification_category_name: "Marketing",
+        }
+      }
+    );
+    expect(response).toMatchInlineSnapshot(`
+      NiceResponse {
+        "status": 400,
+        "body": "Template not found with given id",
+        "headers": Headers { <some fields may have been hidden> },
+      }
+    `);
+  });
+
+  it("should return 400 when invalid theme_id is provided", async ({ expect }) => {
+    await Project.createAndSwitch({
+      display_name: "Test Invalid Theme Project",
+      config: {
+        email_config: testEmailConfig,
+      },
+    });
+    const user = await User.create();
+    const response = await niceBackendFetch(
+      "/api/v1/emails/send-email",
+      {
+        method: "POST",
+        accessType: "server",
+        body: {
+          user_ids: [user.userId],
+          html: "<p>Test email with invalid theme</p>",
+          subject: "Test Subject",
+          theme_id: "non-existent-theme",
+          notification_category_name: "Marketing",
+        }
+      }
+    );
+    expect(response).toMatchInlineSnapshot(`
+      NiceResponse {
+        "status": 400,
+        "body": {
+          "code": "SCHEMA_ERROR",
+          "details": {
+            "message": deindent\`
+              Request validation failed on POST /api/v1/emails/send-email:
+                - The theme to use for the email. If not specified, the default theme will be used. is invalid
+            \`,
+          },
+          "error": deindent\`
+            Request validation failed on POST /api/v1/emails/send-email:
+              - The theme to use for the email. If not specified, the default theme will be used. is invalid
+          \`,
+        },
+        "headers": Headers {
+          "x-stack-known-error": "SCHEMA_ERROR",
+          <some fields may have been hidden>,
+        },
+      }
+    `);
+  });
+});
+
+describe("notification categories", () => {
+  it("should return 200 and send email successfully with Transactional category", async ({ expect }) => {
+    await Project.createAndSwitch({
+      display_name: "Test Transactional Project",
+      config: {
+        email_config: testEmailConfig,
+      },
+    });
+    const user = await User.create();
+    const response = await niceBackendFetch(
+      "/api/v1/emails/send-email",
+      {
+        method: "POST",
+        accessType: "server",
+        body: {
+          user_ids: [user.userId],
+          html: "<p>Transactional email</p>",
+          subject: "Transactional Test Subject",
+          notification_category_name: "Transactional",
+        }
+      }
+    );
+    expect(response).toMatchInlineSnapshot(`
+      NiceResponse {
+        "status": 200,
+        "body": {
+          "results": [
+            {
+              "success": true,
+              "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
+              "user_id": "<stripped UUID>",
+            },
+          ],
+        },
+        "headers": Headers { <some fields may have been hidden> },
+      }
+    `);
+
+    // Verify the email was sent
+    const messages = await user.mailbox.fetchMessages();
+    const sentEmail = messages.find(msg => msg.subject === "Transactional Test Subject");
+    expect(sentEmail).toBeDefined();
+  });
+
+  it("should default to Transactional category when notification_category_name is not provided", async ({ expect }) => {
+    await Project.createAndSwitch({
+      display_name: "Test Default Category Project",
+      config: {
+        email_config: testEmailConfig,
+      },
+    });
+    const user = await User.create();
+    const response = await niceBackendFetch(
+      "/api/v1/emails/send-email",
+      {
+        method: "POST",
+        accessType: "server",
+        body: {
+          user_ids: [user.userId],
+          html: "<p>Default category email</p>",
+          subject: "Default Category Test Subject",
+        }
+      }
+    );
+    expect(response).toMatchInlineSnapshot(`
+      NiceResponse {
+        "status": 200,
+        "body": {
+          "results": [
+            {
+              "success": true,
+              "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
+              "user_id": "<stripped UUID>",
+            },
+          ],
+        },
+        "headers": Headers { <some fields may have been hidden> },
+      }
+    `);
+
+    // Verify the email was sent
+    const messages = await user.mailbox.fetchMessages();
+    const sentEmail = messages.find(msg => msg.subject === "Default Category Test Subject");
+    expect(sentEmail).toBeDefined();
+  });
+});
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts
index 546db73112..848b7d6131 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts
@@ -145,35 +145,5 @@ it("unsubscribe link should not be sent for emails with transactional notificati
   const messages = await user.mailbox.fetchMessages();
   const sentEmail = messages.find(msg => msg.subject === "Custom Test Email Subject");
   expect(sentEmail).toBeDefined();
-  expect(sentEmail!.body?.html).toMatchInlineSnapshot(`
-    deindent\`
-      <div>Mock api key detected, 
-      
-      templateComponent: export function EmailTemplate() {
-        return <>
-          <div dangerouslySetInnerHTML={{ __html: "<h1>Test Email</h1><p>This is a test email with HTML content.</p>"}} />
-          
-        </>
-      };
-      
-      themeComponent: import { Html, Head, Tailwind, Body, Container } from '@react-email/components';
-      
-      export function EmailTheme({ children }: { children: React.ReactNode }) {
-        return (
-          <Html>
-            <Head />
-            <Tailwind>
-              <Body className="bg-[#fafbfb] font-sans text-base">
-                <Container className="bg-white p-[45px] rounded-lg">
-                  {children}
-                </Container>
-              </Body>
-            </Tailwind>
-          </Html>
-        );
-      }
-      
-       variables: {}</div>
-    \`
-  `);
+  expect(sentEmail!.body?.html).toMatchInlineSnapshot(`"<!DOCTYPE html PUBLIC \\"-//W3C//DTD XHTML 1.0 Transitional//EN\\" \\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\\"><html dir=\\"ltr\\" lang=\\"en\\"><head><meta content=\\"text/html; charset=UTF-8\\" http-equiv=\\"Content-Type\\"/><meta name=\\"x-apple-disable-message-reformatting\\"/></head><body style=\\"background-color:rgb(250,251,251);font-family:ui-sans-serif, system-ui, sans-serif, &quot;Apple Color Emoji&quot;, &quot;Segoe UI Emoji&quot;, &quot;Segoe UI Symbol&quot;, &quot;Noto Color Emoji&quot;;font-size:1rem;line-height:1.5rem\\"><!--$--><table align=\\"center\\" width=\\"100%\\" border=\\"0\\" cellPadding=\\"0\\" cellSpacing=\\"0\\" role=\\"presentation\\" style=\\"background-color:rgb(255,255,255);padding:45px;border-radius:0.5rem;max-width:37.5em\\"><tbody><tr style=\\"width:100%\\"><td><div><h1>Test Email</h1><p>This is a test email with HTML content.</p></div></td></tr></tbody></table><!--7--><!--/$--></body></html>"`);
 });
diff --git a/docker/dependencies/freestyle-mock/Dockerfile b/docker/dependencies/freestyle-mock/Dockerfile
index 1b336a082c..ef95b8b958 100644
--- a/docker/dependencies/freestyle-mock/Dockerfile
+++ b/docker/dependencies/freestyle-mock/Dockerfile
@@ -1,90 +1,177 @@
-FROM denoland/deno:1.46.1
+FROM oven/bun:1
 
 # ---- app setup --------------------------------------------------------------
 WORKDIR /app
 
+# Create package.json for global dependencies
+RUN cat <<'EOF' > package.json
+{
+  "name": "freestyle-mock",
+  "dependencies": {
+    "arktype": "2.1.2",
+    "react": "19.1.1",
+    "@react-email/components": "0.1.1"
+  }
+}
+EOF
+
+# Install global dependencies
+RUN bun install
+
 # Drop the whole server inline
 RUN cat <<'EOF' > server.ts
-import { serve } from "https://deno.land/std@0.224.0/http/server.ts";
-import { ensureDir } from "https://deno.land/std@0.224.0/fs/ensure_dir.ts";
-import { join } from "https://deno.land/std@0.224.0/path/mod.ts";
+import { serve } from "bun";
+import { mkdir, writeFile, rm } from "fs/promises";
+import { join } from "path";
+import { spawn } from "child_process";
 
 type LogLine = { message: string; type: string };
 
-serve(async (req) => {
-  const url = new URL(req.url);
-  if (!(req.method === "POST" && url.pathname === "/execute/v1/script")) {
-    return new Response("Not found", { status: 404 });
-  }
-
-  const { script, config = {} } = await req.json();
-
-  // 1. temp dir --------------------------------------------------------------
-  const workDir = join("/tmp", "job-" + crypto.randomUUID());
-  await ensureDir(workDir);
-
-  // 2. write user script -----------------------------------------------------
-  const scriptFile = join(workDir, "user_script.ts");
-  await Deno.writeTextFile(scriptFile, script);
-
-  // 3. (optional) pre-cache npm deps ----------------------------------------
-  if (config.nodeModules && Object.keys(config.nodeModules).length) {
-    const pkgs = Object.entries<string>(config.nodeModules).map(
-      ([name, ver]) => `npm:${name}@${ver}`,
-    );
-    await new Deno.Command("deno", {
-      cwd: workDir,
-      args: ["cache", "--unstable", "--node-modules-dir", ...pkgs],
-    }).output();
-  }
+serve({
+  port: 8080,
+  async fetch(req) {
+    const url = new URL(req.url);
+    if (!(req.method === "POST" && url.pathname === "/execute/v1/script")) {
+      return new Response("Not found", { status: 404 });
+    }
+
+    const { script, config = {} } = await req.json();
+
+    // 1. temp dir --------------------------------------------------------------
+    const workDir = join("/tmp", "job-" + crypto.randomUUID());
+    await mkdir(workDir, { recursive: true });
+
+    // 2. write user script and runner files -----------------------------------
+    // Write the user script as-is
+    const scriptFile = join(workDir, "script.ts");
+    await writeFile(scriptFile, script);
+    
+    // Write a runner that imports from the user script
+    const runnerScript = `
+const logs: Array<{ message: string; type: string }> = [];
+
+// Capture console output
+const originalConsole = { ...console };
+const logMethods = ['log', 'info', 'warn', 'error', 'debug'];
+logMethods.forEach(method => {
+  (console as any)[method] = (...args: any[]) => {
+    logs.push({ message: args.map(String).join(' '), type: method });
+    (originalConsole as any)[method](...args);
+  };
+});
+
+// Import the user function
+import userFunction from './script.ts';
+
+try {
+  const result = await (typeof userFunction === 'function' ? userFunction() : userFunction);
+  console.log(JSON.stringify({ result, logs }));
+} catch (error) {
+  console.error(JSON.stringify({ error: error.message, logs }));
+  process.exit(1);
+}
+`;
+    const runnerFile = join(workDir, "runner.ts");
+    await writeFile(runnerFile, runnerScript);
+
+    // 2.1. create package.json for dependencies -------------------------------
+    const packageJson = {
+      type: "module",
+      dependencies: config.nodeModules || {}
+    };
+    const packageJsonFile = join(workDir, "package.json");
+    await writeFile(packageJsonFile, JSON.stringify(packageJson, null, 2));
+
+    // 3. install dependencies -------------------------------------------------
+    if (config.nodeModules && Object.keys(config.nodeModules).length) {
+      const installProcess = spawn("bun", ["install"], {
+        cwd: workDir,
+        stdio: "pipe"
+      });
+      
+      await new Promise((resolve, reject) => {
+        installProcess.on("close", (code) => {
+          if (code === 0) resolve(void 0);
+          else reject(new Error(`bun install failed with code ${code}`));
+        });
+      });
+    }
+
+    // 4. run user script & capture logs ---------------------------------------
+    const logs: LogLine[] = [];
+    
+    let result: unknown = null;
+    try {
+      // Set environment variables
+      const env = { ...process.env, ...(config.envVars ?? {}) };
+
+      // ── spawn a new Bun process ──
+      const bunProcess = spawn("bun", ["run", runnerFile], {
+        cwd: workDir,
+        env,
+        stdio: "pipe"
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      bunProcess.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      bunProcess.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      await new Promise((resolve, reject) => {
+        bunProcess.on("close", (code) => {
+          if (code === 0) resolve(void 0);
+          else reject(new Error(stderr || `Process exited with code ${code}`));
+        });
+      });
+
+      if (stderr) {
+        throw new Error(stderr);
+      }
 
-  // 4. run user script & capture logs ---------------------------------------
-  const logs: LogLine[] = [];
-  const proxied = new Proxy(console, {
-    get(t, p) {
-      if (typeof p === "string" && typeof t[p as keyof Console] === "function") {
-        return (...args: unknown[]) => {
-          logs.push({ message: args.map(String).join(" "), type: p });
-          // @ts-ignore - let it still log to container stdout
-          t[p](...args);
-        };
+      // Parse the wrapped script output
+      try {
+        const lines = stdout.trim().split('\n');
+        const lastLine = lines[lines.length - 1];
+        const parsed = JSON.parse(lastLine);
+        
+        if (parsed && typeof parsed === "object") {
+          if ("error" in parsed) {
+            throw new Error(parsed.error);
+          }
+          result = parsed.result;
+          logs.push(...(parsed.logs || []));
+        } else {
+          result = parsed;
+        }
+      } catch (parseError) {
+        // If JSON parsing fails, treat stdout as the result
+        result = stdout.trim();
       }
-      // @ts-ignore
-      return t[p];
-    },
-  });
-
-  let result: unknown = null;
-  try {
-    const original = globalThis.console;
-    // @ts-ignore
-    globalThis.console = proxied;
-
-    for (const [k, v] of Object.entries(config.envVars ?? {})) Deno.env.set(k, v);
-
-    const mod = await import(`file://${scriptFile}?t=${Date.now()}`);
-    if (typeof mod.default !== "function") throw new Error("default export missing");
-    result = await mod.default();
-
-    // @ts-ignore
-    globalThis.console = original;
-  } catch (err) {
-    return new Response(JSON.stringify({ error: err.message, logs }), {
-      status: 500,
+
+    } catch (err: any) {
+      return new Response(JSON.stringify({ error: err.message, logs }), {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      });
+    } finally {
+      try { await rm(workDir, { recursive: true }); } catch { /* ignore */ }
+    }
+
+    return new Response(JSON.stringify({ result, logs }), {
       headers: { "Content-Type": "application/json" },
     });
-  } finally {
-    try { await Deno.remove(workDir, { recursive: true }); } catch { /* ignore */ }
-  }
-
-  return new Response(JSON.stringify({ result, logs }), {
-    headers: { "Content-Type": "application/json" },
-  });
-}, { port: 8080 });
+  },
+});
 EOF
 
 # ---- network ----------------------------------------------------------------
 EXPOSE 8080
 
 # ---- launch -----------------------------------------------------------------
-CMD ["deno", "run", "--unstable", "-A", "server.ts"]
+CMD ["bun", "run", "server.ts"]
diff --git a/packages/stack-shared/src/helpers/emails.ts b/packages/stack-shared/src/helpers/emails.ts
index 23c49d22a2..e48e578c1d 100644
--- a/packages/stack-shared/src/helpers/emails.ts
+++ b/packages/stack-shared/src/helpers/emails.ts
@@ -98,7 +98,7 @@ export function EmailTheme({ children, unsubscribeLink }: ThemeProps) {
 
 EmailTheme.PreviewProps = {
   unsubscribeLink: "https://example.com"
-} satisfies Partial<ThemeProps>  
+} satisfies Partial<ThemeProps>
 `;
 
 

From ab18f017200430141fa89ccc40be888363c34cc7 Mon Sep 17 00:00:00 2001
From: Bilal Godil <bg2002@gmail.com>
Date: Tue, 29 Jul 2025 18:27:19 -0700
Subject: [PATCH 2/8] fix tests and esbuild initialization

---
 .../api/latest/emails/send-email/route.tsx    |  4 ++-
 .../api/v1/contact-channels/verify.test.ts    |  2 +-
 .../endpoints/api/v1/send-email.test.ts       |  4 +--
 packages/stack-shared/src/utils/esbuild.tsx   | 29 +++++++++++--------
 4 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/apps/backend/src/app/api/latest/emails/send-email/route.tsx b/apps/backend/src/app/api/latest/emails/send-email/route.tsx
index d55b964102..478ef1e124 100644
--- a/apps/backend/src/app/api/latest/emails/send-email/route.tsx
+++ b/apps/backend/src/app/api/latest/emails/send-email/route.tsx
@@ -29,7 +29,9 @@ export const POST = createSmartRouteHandler({
     }).defined(),
     body: yupObject({
       user_ids: yupArray(yupString().defined()).defined(),
-      theme_id: templateThemeIdSchema.nullable().label("The theme to use for the email. If not specified, the default theme will be used."),
+      theme_id: templateThemeIdSchema.nullable().meta({
+        openapiField: { description: "The theme to use for the email. If not specified, the default theme will be used." }
+      }),
       html: yupString().optional(),
       subject: yupString().optional(),
       notification_category_name: yupString().optional(),
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/verify.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/verify.test.ts
index e8a37af055..b1d21a80a0 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/verify.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/contact-channels/verify.test.ts
@@ -18,7 +18,7 @@ it("each verification code that was already requested can be used exactly once",
   await ContactChannels.sendVerificationCode();
   const mailbox = backendContext.value.mailbox;
   const messages = await mailbox.fetchMessages();
-  const verifyMessages = messages.filter((message) => message.subject === "Mock subject, <Subject value={\`Verify your email at \${project.displayName}\`} />");
+  const verifyMessages = messages.filter((message) => message.subject === "Verify your email at Stack Dashboard");
   const verificationCodes = verifyMessages.map((message) => message.body?.text.match(/http:\/\/localhost:12345\/some-callback-url\?code=([a-zA-Z0-9]+)/)?.[1] ?? throwErr("Verification code not found"));
   expect(verificationCodes).toHaveLength(3);
 
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
index d72571c030..337d987826 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
@@ -509,12 +509,12 @@ describe("template-based emails", () => {
           "details": {
             "message": deindent\`
               Request validation failed on POST /api/v1/emails/send-email:
-                - The theme to use for the email. If not specified, the default theme will be used. is invalid
+                - body.theme_id is invalid
             \`,
           },
           "error": deindent\`
             Request validation failed on POST /api/v1/emails/send-email:
-              - The theme to use for the email. If not specified, the default theme will be used. is invalid
+              - body.theme_id is invalid
           \`,
         },
         "headers": Headers {
diff --git a/packages/stack-shared/src/utils/esbuild.tsx b/packages/stack-shared/src/utils/esbuild.tsx
index b163c01f51..6cf5074df6 100644
--- a/packages/stack-shared/src/utils/esbuild.tsx
+++ b/packages/stack-shared/src/utils/esbuild.tsx
@@ -4,24 +4,29 @@ import { StackAssertionError, throwErr } from "./errors";
 import { Result } from "./results";
 import { isBrowserLike } from './env';
 
+const esbuildWasmUrl = `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`;
+
 let esbuildInitializePromise: Promise<void> | null = null;
 // esbuild requires self property to be set, and it is not set by default in nodejs
 (globalThis.self as any) ??= globalThis as any;
 
-export async function initializeEsbuild() {
+export function initializeEsbuild(): Promise<void> {
   if (!esbuildInitializePromise) {
-    esbuildInitializePromise = esbuild.initialize(isBrowserLike() ? {
-      wasmURL: `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`,
-    } : {
-      wasmModule: (
-        await fetch(`https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`)
-          .then(wasm => wasm.arrayBuffer())
-          .then(wasm => new WebAssembly.Module(wasm))
-      ),
-      worker: false,
-    });
+    // assign immediately so no one else will race in
+    esbuildInitializePromise = (async () => {
+      if (isBrowserLike()) {
+        await esbuild.initialize({
+          wasmURL: esbuildWasmUrl,
+        });
+      } else {
+        const wasmBuffer = await fetch(esbuildWasmUrl).then(r => r.arrayBuffer());
+        const wasmModule = new WebAssembly.Module(wasmBuffer);
+        await esbuild.initialize({ wasmModule, worker: false });
+      }
+    })();
   }
-  await esbuildInitializePromise;
+
+  return esbuildInitializePromise;
 }
 
 export async function bundleJavaScript(sourceFiles: Record<string, string> & { '/entry.js': string }, options: {

From 0f3768b41075d5f82044a9bc946df85327837284 Mon Sep 17 00:00:00 2001
From: Konstantin Wohlwend <n2d4xc@gmail.com>
Date: Thu, 31 Jul 2025 17:36:14 -0700
Subject: [PATCH 3/8] Update Freestyle mock port from 8119 to 8122

---
 apps/backend/src/lib/freestyle.tsx      | 2 +-
 apps/dev-launchpad/public/index.html    | 2 +-
 docker/dependencies/docker.compose.yaml | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/backend/src/lib/freestyle.tsx b/apps/backend/src/lib/freestyle.tsx
index cb3a004c8f..e00aca09bf 100644
--- a/apps/backend/src/lib/freestyle.tsx
+++ b/apps/backend/src/lib/freestyle.tsx
@@ -9,7 +9,7 @@ export class TracedFreestyleSandboxes {
   constructor(options: { apiKey: string }) {
     let baseUrl = undefined;
     if (["development", "test"].includes(getNodeEnvironment()) && options.apiKey === "mock_stack_freestyle_key") {
-      baseUrl = "http://localhost:8119";
+      baseUrl = "http://localhost:8122";
     }
     this.freestyle = new FreestyleSandboxes({
       apiKey: options.apiKey,
diff --git a/apps/dev-launchpad/public/index.html b/apps/dev-launchpad/public/index.html
index b169d676bb..00e6d58173 100644
--- a/apps/dev-launchpad/public/index.html
+++ b/apps/dev-launchpad/public/index.html
@@ -111,7 +111,7 @@ <h2 style="margin-top: 64px;">Background services</h2>
         4318: OTel collector
       </li>
       <li>
-        8119: Freestyle mock
+        8122: Freestyle mock
       </li>
     </ul>
     <noscript>
diff --git a/docker/dependencies/docker.compose.yaml b/docker/dependencies/docker.compose.yaml
index b175975461..7fb1a286d1 100644
--- a/docker/dependencies/docker.compose.yaml
+++ b/docker/dependencies/docker.compose.yaml
@@ -143,7 +143,7 @@ services:
     image: freestyle-mock
     container_name: freestyle-mock
     ports:
-      - "8119:8080"       # POST http://localhost:8119/execute/v1/script
+      - "8122:8080"       # POST http://localhost:8122/execute/v1/script
     environment:
       DENO_DIR: /deno-cache
     volumes:

From ef490935aae3e00bf92f19d0f3ea35b8c6a8e46e Mon Sep 17 00:00:00 2001
From: Konstantin Wohlwend <n2d4xc@gmail.com>
Date: Thu, 31 Jul 2025 17:36:26 -0700
Subject: [PATCH 4/8] fixup!

---
 docker/dependencies/docker.compose.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docker/dependencies/docker.compose.yaml b/docker/dependencies/docker.compose.yaml
index 7fb1a286d1..4580278cdc 100644
--- a/docker/dependencies/docker.compose.yaml
+++ b/docker/dependencies/docker.compose.yaml
@@ -143,7 +143,7 @@ services:
     image: freestyle-mock
     container_name: freestyle-mock
     ports:
-      - "8122:8080"       # POST http://localhost:8122/execute/v1/script
+      - "8122:8080"       # POST http://localhost:8119/execute/v1/script
     environment:
       DENO_DIR: /deno-cache
     volumes:

From 0a1b36df16faaa9ef6eb63b12529648a47f88051 Mon Sep 17 00:00:00 2001
From: Bilal Godil <bg2002@gmail.com>
Date: Fri, 1 Aug 2025 16:56:17 -0700
Subject: [PATCH 5/8] fix tests

---
 .../endpoints/api/v1/send-email.test.ts       | 89 ++++++-------------
 .../endpoints/api/v1/unsubscribe-link.test.ts |  2 -
 2 files changed, 26 insertions(+), 65 deletions(-)

diff --git a/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
index 337d987826..ccf51faf83 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts
@@ -56,14 +56,14 @@ describe("invalid requests", () => {
         email_config: testEmailConfig,
       },
     });
-    const userId = randomUUID();
+    const user = await User.create();
     const response = await niceBackendFetch(
       "/api/v1/emails/send-email",
       {
         method: "POST",
         accessType: "server",
         body: {
-          user_ids: [userId],
+          user_ids: [user.userId],
           html: "<p>Test email</p>",
           subject: "Test Subject",
           notification_category_name: "Marketing",
@@ -76,8 +76,7 @@ describe("invalid requests", () => {
         "body": {
           "results": [
             {
-              "error": "User not found",
-              "success": false,
+              "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
               "user_id": "<stripped UUID>",
             },
           ],
@@ -209,8 +208,6 @@ it("should return 200 with disabled notifications error in results when user has
       "body": {
         "results": [
           {
-            "error": "User has disabled notifications for this category",
-            "success": false,
             "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
             "user_id": "<stripped UUID>",
           },
@@ -251,15 +248,7 @@ it("should return 200 with no primary email error in results when user does not
   expect(response).toMatchInlineSnapshot(`
     NiceResponse {
       "status": 200,
-      "body": {
-        "results": [
-          {
-            "error": "User does not have a primary email",
-            "success": false,
-            "user_id": "<stripped UUID>",
-          },
-        ],
-      },
+      "body": { "results": [{ "user_id": "<stripped UUID>" }] },
       "headers": Headers { <some fields may have been hidden> },
     }
   `);
@@ -288,20 +277,19 @@ it("should return 200 and send email successfully", async ({ expect }) => {
   );
 
   expect(response).toMatchInlineSnapshot(`
-      NiceResponse {
-        "status": 200,
-        "body": {
-          "results": [
-            {
-              "success": true,
-              "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
-              "user_id": "<stripped UUID>",
-            },
-          ],
-        },
-        "headers": Headers { <some fields may have been hidden> },
-      }
-    `);
+    NiceResponse {
+      "status": 200,
+      "body": {
+        "results": [
+          {
+            "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
+            "user_id": "<stripped UUID>",
+          },
+        ],
+      },
+      "headers": Headers { <some fields may have been hidden> },
+    }
+  `);
 
   // Verify the email was actually sent by checking the mailbox
   const messages = await user.mailbox.fetchMessages();
@@ -310,7 +298,7 @@ it("should return 200 and send email successfully", async ({ expect }) => {
   expect(sentEmail!.body?.html).toMatchInlineSnapshot(`"http://localhost:8102/api/v1/emails/unsubscribe-link?code=%3Cstripped+query+param%3E"`);
 });
 
-it("should handle mixed results for multiple users", async ({ expect }) => {
+it("should handle user that does not exist", async ({ expect }) => {
   await Project.createAndSwitch({
     display_name: "Test Mixed Results Project",
     config: {
@@ -344,41 +332,18 @@ it("should handle mixed results for multiple users", async ({ expect }) => {
 
   expect(response).toMatchInlineSnapshot(`
     NiceResponse {
-      "status": 200,
+      "status": 400,
       "body": {
-        "results": [
-          {
-            "error": "User has disabled notifications for this category",
-            "success": false,
-            "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
-            "user_id": "<stripped UUID>",
-          },
-          {
-            "error": "User not found",
-            "success": false,
-            "user_id": "<stripped UUID>",
-          },
-          {
-            "success": true,
-            "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
-            "user_id": "<stripped UUID>",
-          },
-        ],
+        "code": "USER_ID_DOES_NOT_EXIST",
+        "details": { "user_id": "<stripped UUID>" },
+        "error": "The given user with the ID <stripped UUID> does not exist.",
+      },
+      "headers": Headers {
+        "x-stack-known-error": "USER_ID_DOES_NOT_EXIST",
+        <some fields may have been hidden>,
       },
-      "headers": Headers { <some fields may have been hidden> },
     }
   `);
-
-  // Verify only the successful user received the email
-  const successfulUserMessages = await successfulUser.mailbox.fetchMessages();
-  const sentEmail = successfulUserMessages.find(msg => msg.subject === "Bulk Test Email Subject");
-  expect(sentEmail).toBeDefined();
-  expect(sentEmail!.body?.html).toMatchInlineSnapshot(`"http://localhost:8102/api/v1/emails/unsubscribe-link?code=%3Cstripped+query+param%3E"`);
-
-  // Verify the user with disabled notifications did not receive the email
-  const disabledUserMessages = await userWithDisabledNotifications.mailbox.fetchMessages();
-  const disabledUserEmail = disabledUserMessages.find(msg => msg.subject === "Bulk Test Email Subject");
-  expect(disabledUserEmail).toBeUndefined();
 });
 
 describe("validation errors", () => {
@@ -554,7 +519,6 @@ describe("notification categories", () => {
         "body": {
           "results": [
             {
-              "success": true,
               "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
               "user_id": "<stripped UUID>",
             },
@@ -596,7 +560,6 @@ describe("notification categories", () => {
         "body": {
           "results": [
             {
-              "success": true,
               "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
               "user_id": "<stripped UUID>",
             },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts
index 848b7d6131..34fb91ad43 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts
@@ -37,7 +37,6 @@ it("unsubscribe link should be sent and update notification preference", async (
       "body": {
         "results": [
           {
-            "success": true,
             "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
             "user_id": "<stripped UUID>",
           },
@@ -132,7 +131,6 @@ it("unsubscribe link should not be sent for emails with transactional notificati
       "body": {
         "results": [
           {
-            "success": true,
             "user_email": "unindexed-mailbox--<stripped UUID>@stack-generated.example.com",
             "user_id": "<stripped UUID>",
           },

From c36f51e6a267ead144b7bc27ef3fbe21ef83d4bd Mon Sep 17 00:00:00 2001
From: Bilal Godil <bg2002@gmail.com>
Date: Fri, 1 Aug 2025 17:31:27 -0700
Subject: [PATCH 6/8] fix email test

---
 apps/e2e/tests/js/email.test.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/apps/e2e/tests/js/email.test.ts b/apps/e2e/tests/js/email.test.ts
index 11f97104e0..62957e9374 100644
--- a/apps/e2e/tests/js/email.test.ts
+++ b/apps/e2e/tests/js/email.test.ts
@@ -50,6 +50,10 @@ it("should successfully send email with template", async ({ expect }) => {
   const result = await serverApp.sendEmail({
     userIds: [user.id],
     templateId: DEFAULT_TEMPLATE_IDS.sign_in_invitation,
+    variables: {
+      teamDisplayName: "Test Team",
+      signInInvitationLink: "https://example.com",
+    },
     subject: "Welcome!",
   });
 

From 9d0240c86ed662a08beb680f01bda967dd99a013 Mon Sep 17 00:00:00 2001
From: Bilal Godil <bg2002@gmail.com>
Date: Fri, 1 Aug 2025 17:34:26 -0700
Subject: [PATCH 7/8] fix lint

---
 .../src/lib/stack-app/apps/implementations/server-app-impl.ts   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts b/packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts
index b6e9a3ef1c..8a6cb347ed 100644
--- a/packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts
+++ b/packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts
@@ -943,7 +943,7 @@ export class _StackServerAppImplIncomplete<HasTokenStore extends boolean, Projec
   // END_PLATFORM
 
   async sendEmail(options: SendEmailOptions): Promise<Result<void, KnownErrors["RequiresCustomEmailServer"] | KnownErrors["SchemaError"] | KnownErrors["UserIdDoesNotExist"]>> {
-    return this._interface.sendEmail(options);
+    return await this._interface.sendEmail(options);
   }
 
   protected override async _refreshSession(session: InternalSession) {

From 4137933e49b4f4607726cd99b1feeff0bf762118 Mon Sep 17 00:00:00 2001
From: Bilal Godil <bg2002@gmail.com>
Date: Fri, 1 Aug 2025 18:09:31 -0700
Subject: [PATCH 8/8] fix flaky test

---
 .../tests/backend/endpoints/api/v1/auth/password/reset.test.ts  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts
index f31d330bd9..dd6aa5ef71 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/auth/password/reset.test.ts
@@ -22,7 +22,7 @@ async function getResetCode() {
   `);
   const messages = await backendContext.value.mailbox.fetchMessages();
   const messagesNoBody = await backendContext.value.mailbox.fetchMessages({ noBody: true });
-  expect(messagesNoBody.at(-1)).toMatchInlineSnapshot(`
+  expect(messagesNoBody.find(m => m.subject.includes("Reset your password at"))).toMatchInlineSnapshot(`
     MailboxMessage {
       "from": "Stack Dashboard <noreply@example.com>",
       "subject": "Reset your password at Stack Dashboard",