Brand transactional auth emails per app

.changeset/per-app-verify-email.md

@@ -0,0 +1,15 @@
+---
+"@agent-native/core": patch
+---
+
+Brand transactional auth emails per app. Signup verification and password
+reset emails now send from `<app-slug>@agent-native.com` with reply-to
+hello@agent-native.com and per-app subjects/headings ("Verify your email for
+Agent-Native <App>" / "Reset your Agent-Native <App> password"). The
+verification email body also includes the app's one-line description (competitor
+names reframed as "replacement"); the reset email omits the pitch since it's a
+security email. Unknown apps fall back to the generic "Agent Native" branding.
+
+The branded sender and reply-to are applied only when the configured
+EMAIL_FROM is already on agent-native.com, so self-hosted deployments keep
+their own verified sender and support mailbox.

packages/core/src/server/app-name.ts

@@ -51,3 +51,41 @@ export function getAppName(): string | undefined {
   cachedFromPkg = name ?? undefined;
   return name;
 }
+
+/**
+ * Resolve the app's slug — the machine-readable identifier used for the
+ * per-app transactional email sender (e.g. `clips@agent-native.com`).
+ *
+ * Prefer the first-party template name matched by package.json (safe even on
+ * serverless runtimes where `process.cwd()` may expose a bogus name). Fall
+ * back to slugifying the resolved display name so custom `APP_NAME` overrides
+ * still produce a usable local-part. Returns `undefined` when nothing resolves.
+ */
+export function getAppSlug(): string | undefined {
+  const pkg = readPkg();
+  if (pkg?.name) {
+    const tmpl = TEMPLATES.find((t) => t.name === pkg.name);
+    if (tmpl) return tmpl.name;
+  }
+  const name = getAppName();
+  if (!name) return undefined;
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || undefined;
+}
+
+/**
+ * One-line description of the app, used to tailor transactional email bodies
+ * so recipients recognize which app they signed up for. Sourced from the
+ * first-party template metadata; `undefined` for unknown apps.
+ */
+export function getAppDescription(): string | undefined {
+  const pkg = readPkg();
+  if (pkg?.name) {
+    const tmpl = TEMPLATES.find((t) => t.name === pkg.name);
+    if (tmpl) return tmpl.hint;
+  }
+  return undefined;
+}

packages/core/src/server/better-auth-instance.ts

@@ -906,11 +906,11 @@ async function createBetterAuthInstance(
           ""
         ).replace(/\/$/, "");
         const resetUrl = `${appUrl}${appBasePath}/_agent-native/auth/reset?token=${encodeURIComponent(token)}`;
-        const { subject, html, text } = renderResetPasswordEmail({
+        const { subject, html, text, appSender } = renderResetPasswordEmail({
           email: user.email,
           resetUrl,
         });
-        await sendEmail({ to: user.email, subject, html, text });
+        await sendEmail({ to: user.email, subject, html, text, appSender });
       },
     },
     emailVerification: {
@@ -933,11 +933,11 @@ async function createBetterAuthInstance(
         const verifyUrl = verifyBasePath
           ? url.replace(/(\/\/[^/]+)(\/)/, `$1${verifyBasePath}$2`)
           : url;
-        const { subject, html, text } = renderVerifySignupEmail({
+        const { subject, html, text, appSender } = renderVerifySignupEmail({
           email: user.email,
           verifyUrl,
         });
-        await sendEmail({ to: user.email, subject, html, text });
+        await sendEmail({ to: user.email, subject, html, text, appSender });
       },
     },
     socialProviders,

packages/core/src/server/email-templates.ts

@@ -11,13 +11,22 @@
  * site — keeps the transactional look-and-feel consistent.
  */
 
-import { getAppName } from "./app-name.js";
+import { getAppName, getAppSlug, getAppDescription } from "./app-name.js";
 import { renderEmail, emailStrong } from "./email-template.js";
 
+/** Shared reply-to for the framework's transactional emails. */
+export const AGENT_NATIVE_REPLY_TO = "hello@agent-native.com";
+
 export interface RenderedEmailMessage {
   subject: string;
   html: string;
   text: string;
+  /**
+   * Per-app sender branding, applied by `sendEmail` only on first-party
+   * agent-native.com deployments. Self-hosted deployments keep the sender and
+   * reply-to they configured via EMAIL_FROM.
+   */
+  appSender?: { name: string; slug: string; replyTo?: string };
 }
 
 /**
@@ -89,28 +98,62 @@ export interface RenderVerifySignupEmailArgs {
   verifyUrl: string;
 }
 
+/**
+ * Customer-facing description overrides for the verification email body. The
+ * default descriptions come from the app-picker hints, which name competitors
+ * for internal positioning; these rewrites frame them as "replacement" for a
+ * customer-facing email without changing the picker copy.
+ */
+const VERIFY_EMAIL_DESCRIPTIONS: Record<string, string> = {
+  calendar:
+    "Agent-native Google Calendar replacement — manage events, sync, and public booking",
+  content:
+    "Open-source Obsidian/Notion replacement for MDX — edit local docs with agent assistance",
+  slides:
+    "Agent-native Google Slides replacement — generate and edit React presentations",
+  analytics:
+    "Agent-native Amplitude/Mixpanel replacement — connect data sources, prompt for charts",
+  mail: "Agent-native Superhuman replacement — email client with keyboard shortcuts and AI triage",
+};
+
 export function renderVerifySignupEmail(
   args: RenderVerifySignupEmailArgs,
 ): RenderedEmailMessage {
   const email = stripCrlf(args.email);
-  const appName = resolveAppName();
+  const appName = getAppName();
+  // Brand each app's verification email as "Agent-Native <App>" so recipients
+  // can tell which app they signed up for. Fall back to the generic name when
+  // the app can't be resolved (unknown/serverless runtime).
+  const brand = appName ? `Agent-Native ${stripCrlf(appName)}` : "Agent Native";
+  const slug = appName ? getAppSlug() : undefined;
+  const description = appName
+    ? ((slug && VERIFY_EMAIL_DESCRIPTIONS[slug]) ?? getAppDescription())
+    : undefined;
+
+  const paragraphs = [
+    `Thanks for signing up for ${emailStrong(brand)}. To finish creating your account, confirm that ${emailStrong(email)} is your email address.`,
+  ];
+  if (description) {
+    paragraphs.push(`${stripCrlf(description).replace(/\.\s*$/, "")}.`);
+  }
+  paragraphs.push(`This link expires in 1 hour.`);
 
   const { html, text } = renderEmail({
-    brandName: appName,
-    preheader: `Confirm ${email} to finish setting up your ${appName} account.`,
-    heading: `Verify your email for ${appName}`,
-    paragraphs: [
-      `Thanks for signing up for ${emailStrong(appName)}. To finish creating your account, confirm that ${emailStrong(email)} is your email address.`,
-      `This link expires in 1 hour.`,
-    ],
+    brandName: brand,
+    preheader: `Confirm ${email} to finish setting up your ${brand} account.`,
+    heading: `Verify your email for ${brand}`,
+    paragraphs,
     cta: { label: "Verify email", url: args.verifyUrl },
     footer: `If you didn't sign up, you can safely ignore this email.`,
   });
 
   return {
-    subject: `Verify your email for ${appName}`,
+    subject: `Verify your email for ${brand}`,
     html,
     text,
+    appSender: slug
+      ? { name: brand, slug, replyTo: AGENT_NATIVE_REPLY_TO }
+      : undefined,
   };
 }
 
@@ -129,12 +172,16 @@ export function renderResetPasswordEmail(
   args: RenderResetPasswordEmailArgs,
 ): RenderedEmailMessage {
   const email = stripCrlf(args.email);
-  const appName = resolveAppName();
+  const appName = getAppName();
+  // Match the verification email branding so password resets are clearly tied
+  // to the specific app. No value pitch here — it's a security email.
+  const brand = appName ? `Agent-Native ${stripCrlf(appName)}` : "Agent Native";
+  const slug = appName ? getAppSlug() : undefined;
 
   const { html, text } = renderEmail({
-    brandName: appName,
+    brandName: brand,
     preheader: `Reset the password for ${email}. This link expires in 1 hour.`,
-    heading: `Reset your ${appName} password`,
+    heading: `Reset your ${brand} password`,
     paragraphs: [
       `Someone requested a password reset for ${emailStrong(email)}. Click the button below to choose a new password.`,
       `This link expires in 1 hour.`,
@@ -144,8 +191,11 @@ export function renderResetPasswordEmail(
   });
 
   return {
-    subject: `Reset your ${appName} password`,
+    subject: `Reset your ${brand} password`,
     html,
     text,
+    appSender: slug
+      ? { name: brand, slug, replyTo: AGENT_NATIVE_REPLY_TO }
+      : undefined,
   };
 }

packages/core/src/server/email.spec.ts

@@ -9,6 +9,53 @@ describe("sendEmail", () => {
     vi.unstubAllGlobals();
   });
 
+  it("applies per-app sender branding on agent-native.com deployments", async () => {
+    vi.stubEnv("SENDGRID_API_KEY", "sendgrid-example-key");
+    vi.stubEnv("EMAIL_FROM", "Agent Native <noreply@agent-native.com>");
+    const fetchMock = vi.fn(async () => new Response(null, { status: 202 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await sendEmail({
+      to: "reader@example.com",
+      subject: "Verify your email",
+      html: "<p>hi</p>",
+      appSender: {
+        name: "Agent-Native Clips",
+        slug: "clips",
+        replyTo: "hello@agent-native.com",
+      },
+    });
+
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(body.from).toEqual({
+      name: "Agent-Native Clips",
+      email: "clips@agent-native.com",
+    });
+    expect(body.reply_to).toEqual({ email: "hello@agent-native.com" });
+  });
+
+  it("keeps a self-hosted verified sender and reply-to untouched", async () => {
+    vi.stubEnv("SENDGRID_API_KEY", "sendgrid-example-key");
+    vi.stubEnv("EMAIL_FROM", "Acme <noreply@acme.com>");
+    const fetchMock = vi.fn(async () => new Response(null, { status: 202 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await sendEmail({
+      to: "reader@example.com",
+      subject: "Verify your email",
+      html: "<p>hi</p>",
+      appSender: {
+        name: "Agent-Native Clips",
+        slug: "clips",
+        replyTo: "hello@agent-native.com",
+      },
+    });
+
+    const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(body.from).toEqual({ name: "Acme", email: "noreply@acme.com" });
+    expect(body.reply_to).toBeUndefined();
+  });
+
   it("maps inline CID attachments for SendGrid", async () => {
     vi.stubEnv("SENDGRID_API_KEY", "sendgrid-example-key");
     vi.stubEnv("EMAIL_FROM", "Agent Native <reports@example.com>");

packages/core/src/server/email.ts

@@ -32,6 +32,14 @@ export interface SendEmailArgs {
   from?: string;
   cc?: string | string[];
   replyTo?: string;
+  /**
+   * Per-app branding for first-party agent-native.com deployments. Applied
+   * only when the configured EMAIL_FROM is already on agent-native.com, so a
+   * self-hosted deployment keeps its own verified sender and support mailbox
+   * instead of sending as an unverified address a provider would reject.
+   * An explicit `from` / `replyTo` always wins.
+   */
+  appSender?: { name: string; slug: string; replyTo?: string };
   inReplyTo?: string;
   references?: string;
   attachments?: EmailAttachment[];
@@ -123,14 +131,37 @@ function getFromAddress(
   return "Agent Native <onboarding@resend.dev>";
 }
 
+const AGENT_NATIVE_SENDER_DOMAIN = "agent-native.com";
+
+/**
+ * Resolve per-app sender branding, but only for deployments whose configured
+ * sender is already on agent-native.com. Any other (or missing) EMAIL_FROM
+ * means we cannot prove the branded address is a verified sender, so the
+ * deployment's own configuration is left untouched.
+ */
+function resolveAppSender(
+  configuredFrom: string | undefined,
+  appSender: SendEmailArgs["appSender"],
+): { from: string; replyTo?: string } | undefined {
+  if (!configuredFrom || !appSender) return undefined;
+  const address = parseSendGridFrom(configuredFrom).email.toLowerCase();
+  if (!address.endsWith(`@${AGENT_NATIVE_SENDER_DOMAIN}`)) return undefined;
+  return {
+    from: `${appSender.name} <${appSender.slug}@${AGENT_NATIVE_SENDER_DOMAIN}>`,
+    replyTo: appSender.replyTo,
+  };
+}
+
 async function sendEmailWithSignal(
   args: SendEmailArgs,
   signal?: AbortSignal,
 ): Promise<void> {
   const config = await resolveEmailTransport();
   signal?.throwIfAborted();
   const provider = config.provider;
-  const from = getFromAddress(config, args.from);
+  const branded = resolveAppSender(config.from, args.appSender);
+  const from = getFromAddress(config, args.from ?? branded?.from);
+  const replyTo = args.replyTo ?? branded?.replyTo;
   const attachments = resolveAttachments(args);
 
   if (provider === "resend") {
@@ -142,7 +173,7 @@ async function sendEmailWithSignal(
       text: args.text,
     };
     if (args.cc) payload.cc = Array.isArray(args.cc) ? args.cc : [args.cc];
-    if (args.replyTo) payload.reply_to = args.replyTo;
+    if (replyTo) payload.reply_to = replyTo;
     if (attachments?.length) {
       payload.attachments = attachments.map((a) => ({
         filename: a.filename,
@@ -193,7 +224,7 @@ async function sendEmailWithSignal(
         { type: "text/html", value: args.html },
       ],
     };
-    if (args.replyTo) sgPayload.reply_to = parseSendGridFrom(args.replyTo);
+    if (replyTo) sgPayload.reply_to = parseSendGridFrom(replyTo);
     const sgHeaders: Record<string, string> = {};
     if (args.inReplyTo) sgHeaders["In-Reply-To"] = args.inReplyTo;
     if (args.references) sgHeaders["References"] = args.references;