Uh oh!
There was an error while loading. Please reload this page.
feat(backend): transactional email send with user_id recipient - #9010
Conversation
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: 277a62b The changes in this PR will be included in the next version bump. This PR includes changesets to release 10 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Repository UI (inherited) Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughThis PR adds ChangesTransactional email API
Sequence Diagram(s)sequenceDiagram
participant createBackendApiClient
participant EmailApi
participant ClerkBackendAPI as Clerk Backend API
participant Email as Email resource
createBackendApiClient->>EmailApi: emails.create(params)
EmailApi->>ClerkBackendAPI: POST /v1/email
ClerkBackendAPI-->>EmailApi: Email JSON
EmailApi->>Email: fromJSON(data.user_id)
Email-->>createBackendApiClient: created Email resource
Estimated review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
@clerk/astro@clerk/backend@clerk/chrome-extension@clerk/clerk-js@clerk/electron@clerk/electron-passkeys@clerk/eslint-plugin@clerk/expo@clerk/expo-passkeys@clerk/express@clerk/fastify@clerk/hono@clerk/localizations@clerk/nextjs@clerk/nuxt@clerk/react@clerk/react-router@clerk/shared@clerk/tanstack-react-start@clerk/testing@clerk/ui@clerk/upgrade@clerk/vuecommit: |
API Changes Report
Summary
No API Changes DetectedAll packages have stable APIs with no detected changes. Report generated by Break Check Last ran on |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
packages/backend/src/api/endpoints/EmailApi.ts (1)
92-112: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd an explicit
Promise<Email>return type to this public method.This is exported API surface, so leaving the return type inferred makes the contract easier to widen accidentally. Based on learnings, exported/public TypeScript APIs in this repo should keep explicit return type annotations. As per coding guidelines, "Always define explicit return types for functions, especially public APIs."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/EmailApi.ts` around lines 92 - 112, The public EmailApi.create method currently relies on inferred return typing, which can make the exported API contract easier to widen unintentionally. Update the create method in EmailApi to explicitly declare Promise<Email> as its return type, keeping the existing this.request<Email>(...) behavior unchanged and ensuring the public API surface remains clearly typed.Sources: Coding guidelines, Learnings
packages/backend/src/api/factory.ts (1)
47-80: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftGive
createBackendApiClienta named return type.This exported factory is the main public surface for
@clerk/backend, and adding endpoints by inference makes accidental API-shape changes easy to miss. Please extract a named client interface/type and annotate the factory with it explicitly. Based on learnings, exported/public TypeScript APIs in this repo should keep explicit return type annotations. As per coding guidelines, "Always define explicit return types for functions, especially public APIs."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/factory.ts` around lines 47 - 80, `createBackendApiClient` currently relies on inferred return shape, which can hide accidental public API changes; define a named client interface/type for the object it returns and annotate the factory explicitly. Use the existing `createBackendApiClient` function and the API properties it constructs (for example `actorTokens`, `agentTasks`, `apiKeys`, `billing`, `clients`, `emails`) to build the type, then update the exported function signature to return that type directly.Sources: Coding guidelines, Learnings
packages/backend/src/api/resources/Email.ts (1)
3-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDocument the new
userIdfield before it becomes part of the public
Email.userIdis new public/reference-facing surface, but there’s no JSDoc here explaining when it is populated or how it relates totoEmailAddress. Add a short field-level doc comment, and this likely needs Docs-team awareness since generated reference docs come from JSDoc inpackages/**. As per path instructions, "Treat JSDoc on public/reference-facing APIs as customer-facing documentation, not ordinary internal comments." As per coding guidelines, "All public APIs must be documented with JSDoc."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/Email.ts` around lines 3 - 17, The Email public model now exposes a new userId field without the required customer-facing JSDoc. Add a short field-level doc comment in the Email class constructor for userId, explaining when it is populated and how it relates to toEmailAddress, so generated reference docs stay accurate. Make sure the documentation is placed directly on the Email constructor parameter alongside the other fields and treat this as public API documentation.Sources: Coding guidelines, Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/backend/src/api/__tests__/EmailApi.test.ts`:
- Around line 30-95: Add a new unit test for EmailApi.emails.create that
exercises text-only content serialization. The current EmailApi.test cases only
cover the html path, so extend the existing create tests in EmailApi.test to
call apiClient.emails.create with text instead of html and assert the request
body sent by the email API uses the expected text field (alongside the existing
to/from/replyTo shape). Make sure the new test also validates the response
mapping still works for this content mode.
In `@packages/backend/src/api/endpoints/EmailApi.ts`:
- Around line 58-90: Update CreateEmailParams in EmailApi so the html/text
requirement is enforced by the type system instead of just docs: make the shape
a union that requires at least one of html or text while still allowing both,
and keep the existing runtime validation in the create/send path for JS callers.
Use the CreateEmailParams and any emails.create-related types or helpers in
EmailApi to locate the change, and ensure the validation error clearly tells
developers that one of html or text must be provided.
---
Nitpick comments:
In `@packages/backend/src/api/endpoints/EmailApi.ts`:
- Around line 92-112: The public EmailApi.create method currently relies on
inferred return typing, which can make the exported API contract easier to widen
unintentionally. Update the create method in EmailApi to explicitly declare
Promise<Email> as its return type, keeping the existing this.request<Email>(...)
behavior unchanged and ensuring the public API surface remains clearly typed.
In `@packages/backend/src/api/factory.ts`:
- Around line 47-80: `createBackendApiClient` currently relies on inferred
return shape, which can hide accidental public API changes; define a named
client interface/type for the object it returns and annotate the factory
explicitly. Use the existing `createBackendApiClient` function and the API
properties it constructs (for example `actorTokens`, `agentTasks`, `apiKeys`,
`billing`, `clients`, `emails`) to build the type, then update the exported
function signature to return that type directly.
In `@packages/backend/src/api/resources/Email.ts`:
- Around line 3-17: The Email public model now exposes a new userId field
without the required customer-facing JSDoc. Add a short field-level doc comment
in the Email class constructor for userId, explaining when it is populated and
how it relates to toEmailAddress, so generated reference docs stay accurate.
Make sure the documentation is placed directly on the Email constructor
parameter alongside the other fields and treat this as public API documentation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: fe756ae6-779b-471d-8761-085c4e14baea
📒 Files selected for processing (6)
.changeset/clerk-email-send.mdpackages/backend/src/api/__tests__/EmailApi.test.tspackages/backend/src/api/endpoints/EmailApi.tspackages/backend/src/api/endpoints/index.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Email.ts
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Co-authored-by: Robert Soriano <sorianorobertc@gmail.com>
cbnsndwch
commented
Jun 26, 2026
Thank you! |
Summary
Adds internal transactional email sending with a recipient that can be addressed either by a literal email address or by a Clerk user ID (resolved to the user's primary email server-side).
POST /v1/email, gated behind thetransactional_email_enabledinstance flag.tois a discriminated union (address|user_id); auser_idis resolved to the user's primary email on the server.Emailclient with aRecipient(Address or UserID).clerkClient.emails.create;toaccepts{ address }or{ userId }.Verified end-to-end against the local stack: both the address and user_id paths return 200, with
user_idresolving server-side.Changes in this repo
Experimental @clerk/backend emails.create; to accepts { address } or { userId }.
Summary by CodeRabbit
emails.create().replyToandsubject, and HTML/text content (with HTML preferred when both are provided).Companion PRs