docs: Document managed email provider and email scheduling features by promptless[bot] · Pull Request #1282 · stack-auth/stack-auth

promptless · 2026-03-23T15:07:36Z

Open this suggestion in Promptless to view citations and reasoning process

Updates the Emails documentation with two new features:

Managed by Stack Auth email provider (from PR Managed email provider #1222): Documents the new email configuration option that automates DNS and domain setup via Resend integration, allowing users to send from their own domain without manually configuring SMTP.
Email scheduling (from PR [Refactor][Feat][Fix] Rework Email Section With New Sent Page, Better Drafts Page, and Settings Page #1221): Documents the new scheduledAtMillis option for sendEmail that allows scheduling emails for future delivery instead of sending immediately.

Trigger Events

stack-auth/stack-auth commit (dev): b701fdf Managed email provider (#1222)

Promptless Research (4 files, 1 GitHub PR)

Reviewed stack-auth/stack-auth#1222
Viewed .long_term_context/product_knowledge/product_overview.md
Viewed .long_term_context/doc_workflow/client_instructions.md
Viewed .long_term_context/style/client_style_guide.md
Viewed docs/content/docs/(guides)/apps/emails.mdx

Agent Response

I've created a documentation suggestion for PR #1222 (Managed email provider).

Summary

What changed: Added documentation for the new "Managed by Stack Auth" email configuration option to the Emails guide.

Documentation updates:

Added a new section "Managed by Stack Auth (Production)" in the Email Configuration section

Documents the setup flow: entering subdomain and sender, configuring NS records at the DNS provider, waiting for verification, and activating the domain

Updated the intro text from "two options" to "three options" to reflect the new configuration method

Added lastModified date to frontmatter

Why this matters: This feature allows users to send emails from their own domain without manually configuring SMTP servers. Stack Auth handles the DNS provisioning and Resend integration automatically, making production email setup much simpler.

Suggestion URL: https://app.gopromptless.ai/suggestions/de92a85f-19b1-4cc1-aab4-052e6b988b11

stack-auth/stack-auth commit (dev): 485fa9d [Refactor][Feat][Fix] Rework Email Section With New Sent Page, Better Drafts Page, and Settings Page (#1221)

Promptless Research (4 files, 1 GitHub PR)

Reviewed stack-auth/stack-auth#1221
Viewed .long_term_context/product_knowledge/product_overview.md
Viewed .long_term_context/doc_workflow/client_instructions.md
Viewed .long_term_context/style/client_style_guide.md
Viewed docs/content/docs/(guides)/apps/emails.mdx

Agent Response

I've completed the documentation update for PR #1221. Here's a summary:

Summary

PR #1221 reworked the email section with several changes:

Change Type Documentation Needed?

Sent Page Dashboard UI No - self-documenting UI

Settings Page Dashboard UI No - self-documenting UI

Better Drafts Page Dashboard UI No - self-documenting UI

Email scheduling (scheduledAtMillis) API feature Yes - documented

Capacity boost API Dashboard-triggered No - not user-callable

Documentation Changes

I updated the existing suggestion (Document managed email provider and email scheduling features) to add:

New "Scheduling Emails" section - Documents how to use scheduledAtMillis to schedule emails for future delivery with a code example

Updated Email Options type - Added scheduledAtMillis?: number to the type definition

The suggestion now covers two features:

Managed email provider (from PR Managed email provider #1222)

Email scheduling (from PR [Refactor][Feat][Fix] Rework Email Section With New Sent Page, Better Drafts Page, and Settings Page #1221)

Tip: Create additional Docs Collections to keep multiple repositories in sync 📚

promptless · 2026-03-23T15:07:40Z

docs/content/docs/(guides)/apps/emails.mdx

(Line 139)

Citation: New "Managed by Stack Auth" email provider feature. Based on PR implementation in apps/backend/src/lib/managed-email-onboarding.tsx and dashboard UI in apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/emails/page-client.tsx. The setup flow guides users through subdomain configuration, NS record delegation, and domain verification via Resend webhooks.
View source

vercel · 2026-03-23T15:07:41Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stack-auth-hosted-components	Ready	Preview, Comment	Mar 23, 2026 3:14pm
stack-backend	Ready	Preview, Comment	Mar 23, 2026 3:14pm
stack-dashboard	Ready	Preview, Comment	Mar 23, 2026 3:14pm
stack-demo	Ready	Preview, Comment	Mar 23, 2026 3:14pm
stack-docs	Ready	Preview, Comment	Mar 23, 2026 3:14pm

promptless · 2026-03-23T15:07:42Z

docs/content/docs/(guides)/apps/emails.mdx

 });
 ```

+### Scheduling Emails


Citation: Added scheduled_at_millis parameter to the send-email endpoint in apps/backend/src/app/api/latest/emails/send-email/route.tsx. This allows scheduling emails for future delivery.
View source

promptless · 2026-03-23T15:07:44Z

docs/content/docs/(guides)/apps/emails.mdx

  html?: string;                        // Custom HTML content
  templateId?: string;                  // Template ID to use
  variables?: Record<string, any>;      // Template variables
+  scheduledAtMillis?: number;           // When to send (timestamp in milliseconds)


Citation: New scheduled_at_millis option added to the request body schema in apps/backend/src/app/api/latest/emails/send-email/route.tsx.
View source

CLAassistant · 2026-03-23T15:08:33Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

greptile-apps · 2026-03-23T15:10:53Z

Greptile Summary

This PR adds documentation for two new email features: the Managed by Stack Auth email provider (from PR #1222) and email scheduling via scheduledAtMillis (from PR #1221). The managed provider section is accurate and well-structured. However, the email scheduling documentation contains a critical API mismatch — the actual SDK uses scheduledAt?: Date (a Date object), but the docs document the field as scheduledAtMillis?: number (a millisecond timestamp). This incorrect field name appears in both the code example and the SendEmailOptions type definition, meaning developers following the docs will silently pass an unrecognised property and their emails will be sent immediately rather than at the scheduled time.

Key issues:

scheduledAtMillis: oneHourFromNow in the code example should be scheduledAt: new Date(oneHourFromNow) — the property is named scheduledAt and takes a Date, not a raw millisecond number
scheduledAtMillis?: number in the type definition should be scheduledAt?: Date
const oneHourFromNow = Date.now() + ... produces a number; wrapping in new Date(...) is needed to match the expected type

Confidence Score: 3/5

Not safe to merge as-is — the scheduling section documents the wrong property name and type, which will cause silent failures for developers who follow it.
The managed email provider section is correct and ready to ship. The scheduling section has a concrete, reproducible bug: scheduledAtMillis (number) is documented instead of scheduledAt (Date). Developers copying the example will pass a silently-ignored property and never schedule their emails. This affects the primary user path for the newly-documented feature.
docs/content/docs/(guides)/apps/emails.mdx — the Scheduling Emails section and the SendEmailOptions type definition both use the wrong property name/type

Important Files Changed

Filename	Overview
docs/content/docs/(guides)/apps/emails.mdx	Adds documentation for managed email provider (correct) and email scheduling (incorrect: documents `scheduledAtMillis?: number` but the actual SDK uses `scheduledAt?: Date` in both the type definition and the code example)

Sequence Diagram

sequenceDiagram
    participant Dev as Developer Code
    participant SDK as StackServerApp (SDK)
    participant API as Stack Auth API

    Note over Dev,API: Email Scheduling Flow
    Dev->>SDK: sendEmail({ scheduledAt: new Date(...) })
    SDK->>API: POST /emails/send-email<br/>{ scheduled_at_millis: date.getTime() }
    API-->>SDK: 200 OK { results: [...] }
    SDK-->>Dev: void

    Note over Dev,API: Managed Email Provider Setup
    Dev->>API: Dashboard → Email Settings → Managed Setup
    API-->>Dev: Display NS records for subdomain
    Dev->>Dev: Add NS records at DNS provider
    API->>API: Poll for DNS propagation<br/>(pending_verification → verified)
    Dev->>API: Click "Use This Domain"
    API-->>Dev: Emails sent from sender@subdomain

_{Reviews (1): Last reviewed commit: "Document managed email provider and emai..." | Re-trigger Greptile}

greptile-apps · 2026-03-23T15:10:57Z

docs/content/docs/(guides)/apps/emails.mdx

+  userIds: ['user-id'],
+  subject: 'Reminder: Your trial ends soon',
+  html: '<p>Your trial period ends tomorrow. Upgrade now to keep access.</p>',
+  scheduledAtMillis: oneHourFromNow,


Wrong property name in scheduling example

The code example uses scheduledAtMillis (a number), but the actual SendEmailOptions type defines the property as scheduledAt (a Date object). Developers copying this example will pass an unrecognised property that is silently ignored, and the email will be sent immediately instead of at the scheduled time.

From packages/stack-shared/src/interface/server-interface.ts:

async sendEmail(options: { ... scheduledAt?: Date, // ← Date object, not a number })

Internally the SDK converts it via options.scheduledAt?.getTime() before sending scheduled_at_millis to the API.

Suggested change

scheduledAtMillis: oneHourFromNow,

scheduledAt: new Date(oneHourFromNow),

greptile-apps · 2026-03-23T15:10:58Z

docs/content/docs/(guides)/apps/emails.mdx

+// Schedule an email to be sent in 1 hour
+const oneHourFromNow = Date.now() + 60 * 60 * 1000;


Incorrect variable type for scheduled timestamp

Date.now() returns a plain number (milliseconds since epoch), but sendEmail expects a Date object in the scheduledAt field — not a raw millisecond timestamp. The variable should be constructed as a Date:

Suggested change

// Schedule an email to be sent in 1 hour

const oneHourFromNow = Date.now() + 60 * 60 * 1000;

const oneHourFromNow = new Date(Date.now() + 60 * 60 * 1000);

greptile-apps · 2026-03-23T15:10:59Z

docs/content/docs/(guides)/apps/emails.mdx

  html?: string;                        // Custom HTML content
  templateId?: string;                  // Template ID to use
  variables?: Record<string, any>;      // Template variables
+  scheduledAtMillis?: number;           // When to send (timestamp in milliseconds)


Wrong property name and type in SendEmailOptions type definition

The type definition documents scheduledAtMillis?: number, but the actual SDK type (packages/template/src/lib/stack-app/email/index.ts) and the underlying interface (packages/stack-shared/src/interface/server-interface.ts) both use scheduledAt?: Date. Using the documented scheduledAtMillis property will have no effect at runtime.

Suggested change

scheduledAtMillis?: number; // When to send (timestamp in milliseconds)

scheduledAt?: Date; // When to send (Date object)

vercel · 2026-03-23T15:18:07Z

docs/content/docs/(guides)/apps/emails.mdx

+const oneHourFromNow = Date.now() + 60 * 60 * 1000;
+
+const result = await stackServerApp.sendEmail({
+  userIds: ['user-id'],


Documentation shows incorrect property name scheduledAtMillis (number) instead of scheduledAt (Date) for scheduling emails

Document managed email provider and email scheduling features

b4fccb3

promptless bot commented Mar 23, 2026

View reviewed changes

github-actions bot assigned promptless[bot] Mar 23, 2026

vercel bot deployed to Preview – stack-auth-hosted-components March 23, 2026 15:09 View deployment

greptile-apps bot reviewed Mar 23, 2026

View reviewed changes

vercel bot reviewed Mar 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Document managed email provider and email scheduling features#1282

docs: Document managed email provider and email scheduling features#1282
promptless[bot] wants to merge 1 commit intodevfrom
promptless/document-managed-email-provider

promptless bot commented Mar 23, 2026

Uh oh!

promptless bot Mar 23, 2026

Uh oh!

vercel bot commented Mar 23, 2026 •

edited

Loading

Uh oh!

promptless bot Mar 23, 2026

Uh oh!

promptless bot Mar 23, 2026

Uh oh!

CLAassistant commented Mar 23, 2026

Uh oh!

greptile-apps bot commented Mar 23, 2026

Uh oh!

greptile-apps bot Mar 23, 2026

Uh oh!

greptile-apps bot Mar 23, 2026

Uh oh!

greptile-apps bot Mar 23, 2026

Uh oh!

vercel bot Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Change	Type	Documentation Needed?
Sent Page	Dashboard UI	No - self-documenting UI
Settings Page	Dashboard UI	No - self-documenting UI
Better Drafts Page	Dashboard UI	No - self-documenting UI
Email scheduling (`scheduledAtMillis`)	API feature	Yes - documented
Capacity boost API	Dashboard-triggered	No - not user-callable

	scheduledAtMillis: oneHourFromNow,
	scheduledAt: new Date(oneHourFromNow),

		// Schedule an email to be sent in 1 hour
		const oneHourFromNow = Date.now() + 60 * 60 * 1000;

	// Schedule an email to be sent in 1 hour
	const oneHourFromNow = Date.now() + 60 * 60 * 1000;
	const oneHourFromNow = new Date(Date.now() + 60 * 60 * 1000);

	scheduledAtMillis?: number; // When to send (timestamp in milliseconds)
	scheduledAt?: Date; // When to send (Date object)

Conversation

promptless bot commented Mar 23, 2026

Trigger Events

Summary

Summary

Documentation Changes

Uh oh!

promptless bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

vercel bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

promptless bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

promptless bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

CLAassistant commented Mar 23, 2026

Uh oh!

greptile-apps bot commented Mar 23, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

vercel bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel bot commented Mar 23, 2026 •

edited

Loading