Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(workflows): add a step-by-step wizard for transactional emails (#124088)

Meikel Ratz9e44f258d290
diff --git a/frontend/src/products.tsx b/frontend/src/products.tsx
index da0cac69bca6..1eac64193f2e 100644
--- a/frontend/src/products.tsx
+++ b/frontend/src/products.tsx
@@ -393,6 +393,7 @@ export const productRoutes: Record<string, [string, string]> = {
'/transactional/suppression': ['Transactional', 'transactional'],
'/transactional/reputation': ['Transactional', 'transactional'],
'/transactional/settings': ['Transactional', 'transactional'],
+ '/transactional/new': ['Transactional', 'transactional'],
'/transactional/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],
'/broadcasts/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],
'/broadcasts/new': ['Broadcast', 'broadcast'],
@@ -2031,6 +2032,7 @@ export const productUrls = {
broadcast: (id: string): string => `/broadcasts/${id}`,
broadcastNew: (): string => '/broadcasts/new',
transactional: (tab?: MessagingNavTabKey): string => `/transactional${tab ? `/${tab}` : ''}`,
+ transactionalNew: (): string => '/transactional/new',
transactionalTemplate: (id: string): string => `/transactional/library/templates/${id}`,
broadcastsTemplate: (id: string): string => `/broadcasts/library/templates/${id}`,
}
diff --git a/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx b/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx
index 0cd075d75986..7d7bc1782788 100644
--- a/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx
+++ b/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx
@@ -34,7 +34,8 @@ export function EmailSenderForm({
senders: EmailSender[]
onChangeFrom: (from: EmailTemplateFrom) => void
onChangeReplyTo: (replyTo: string) => void
- onDone: () => void
+ /** Shows a Done button, for when the form sits in a dropdown. */
+ onDone?: () => void
}): JSX.Element {
const sender = senders.find((candidate) => candidate.id === from.integrationId)
const domain = senderDomain(sender)
@@ -106,11 +107,13 @@ export function EmailSenderForm({
data-attr="transactional-email-reply-to"
/>
</LemonField.Pure>
- <div className="flex justify-end">
- <LemonButton type="primary" size="small" onClick={onDone}>
- Done
- </LemonButton>
- </div>
+ {onDone ? (
+ <div className="flex justify-end">
+ <LemonButton type="primary" size="small" onClick={onDone}>
+ Done
+ </LemonButton>
+ </div>
+ ) : null}
</div>
)
}
diff --git a/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx b/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx
index e990f2d12462..870dac0a65a8 100644
--- a/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx
+++ b/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx
@@ -144,6 +144,9 @@ function DestinationEmailTemplaterForm({
fieldsHidden?: boolean
}): JSX.Element {
const { logicProps, mergeTags, activeContentTab, emailTemplate } = useValues(emailTemplaterLogic)
+ // The editor rebuilds itself when its options change, so it keeps the tags it started with.
+ // Later changes reach it through setMergeTags in the logic.
+ const [initialMergeTags] = useState(mergeTags)
const { setEmailEditorRef, onEmailEditorReady } = useActions(emailTemplaterLogic)
return (
@@ -202,7 +205,7 @@ function DestinationEmailTemplaterForm({
onReady={() => onEmailEditorReady()}
minHeight={20}
options={{
- mergeTags,
+ mergeTags: initialMergeTags,
displayMode: 'email',
appearance: {
actionBar: {
@@ -547,6 +550,9 @@ function NativeEmailTemplaterForm({
visibleFields,
emailTemplate,
} = useValues(emailTemplaterLogic)
+ // The editor rebuilds itself when its options change, so it keeps the tags it started with.
+ // Later changes reach it through setMergeTags in the logic.
+ const [initialMergeTags] = useState(mergeTags)
const { setEmailEditorRef, onEmailEditorReady, setActiveContentTab, hideAdvancedField, revealAdvancedField } =
useActions(emailTemplaterLogic)
// With the AI panel integration on, chat sits beside the editor and width is scarce, so the
@@ -726,7 +732,7 @@ function NativeEmailTemplaterForm({
onReady={() => onEmailEditorReady()}
minHeight={20}
options={{
- mergeTags,
+ mergeTags: initialMergeTags,
displayMode: 'email',
appearance: {
actionBar: {
diff --git a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts
index c4af268fa340..36b88fe6d841 100644
--- a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts
+++ b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts
@@ -156,6 +156,47 @@ describe('emailTemplaterLogic', () => {
})
})
+ describe('merge tags', () => {
+ beforeEach(() => {
+ useMocks({ get: { '/api/projects/:team_id/property_definitions/': { results: [{ name: 'email' }] } } })
+ })
+
+ it.each([
+ { type: 'native_email_template', variables: undefined, expected: ['email'] },
+ {
+ type: 'native_email_transactional_template',
+ variables: { variables: { first_name: '', reset_link: '' } },
+ expected: ['variables.first_name', 'variables.reset_link'],
+ },
+ ] as const)('$type offers $expected', async ({ type, variables, expected }) => {
+ logic = emailTemplaterLogic(makeProps({ type, variables }))
+ logic.mount()
+ await expectLogic(logic).toFinishAllListeners()
+
+ const offered = Object.keys(logic.values.mergeTags).filter((key) => !key.startsWith('unsubscribe'))
+ expect(offered).toEqual(expected)
+ })
+
+ it('pushes a newly added variable into the open editor', async () => {
+ const setMergeTags = jest.fn()
+ const props = makeProps({ type: 'native_email_transactional_template', variables: { variables: {} } })
+ logic = emailTemplaterLogic(props)
+ logic.mount()
+ logic.actions.setEmailEditorRef({
+ editor: { setMergeTags, addEventListener: jest.fn(), loadDesign: jest.fn() },
+ } as any)
+ logic.actions.onEmailEditorReady()
+
+ emailTemplaterLogic({ ...props, variables: { variables: { code: '' } } })
+
+ expect(setMergeTags).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ 'variables.code': expect.objectContaining({ value: '{{ variables.code }}' }),
+ })
+ )
+ })
+ })
+
describe('modal content tab default', () => {
it.each([
{
diff --git a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx
index 7c31f17bcdbb..16467bceb6b9 100644
--- a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx
+++ b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx
@@ -188,6 +188,46 @@ export function buildPersonPropertyMergeValue(name: string): string {
return `{{person.properties['${escaped}']}}`
}
+/** The merge tags the visual editor offers. A transactional email gets its own variables instead of person properties. */
+export function buildMergeTags(
+ personPropertyDefinitions: PropertyDefinition[],
+ type: EmailTemplaterType,
+ variables: Record<string, any> | undefined
+): UnlayerMergeTags {
+ const tags: UnlayerMergeTags = {
+ unsubscribe_url: {
+ name: 'Unsubscribe URL',
+ value: '{{unsubscribe_url}}',
+ sample: 'https://example.com/unsubscribe/12345',
+ },
+ unsubscribe_url_one_click: {
+ name: 'One-Click Unsubscribe URL',
+ value: '{{unsubscribe_url_one_click}}',
+ sample: 'https://example.com/unsubscribe/12345?one_click_unsubscribe=1',
+ },
+ }
+
+ // A transactional email can't read person properties. It reads what the API call passes in
+ // `message_data`, which the caller lists under `variables.variables`.
+ if (type === 'native_email_transactional_template') {
+ Object.keys(variables?.variables ?? {}).forEach((name) => {
+ tags[`variables.${name}`] = { name, value: `{{ variables.${name} }}`, sample: name }
+ })
+ return tags
+ }
+
+ // Add person properties as merge tags
+ personPropertyDefinitions.forEach((property: PropertyDefinition) => {
+ tags[property.name] = {
+ name: property.name,
+ value: buildPersonPropertyMergeValue(property.name),
+ sample: property.example || `Sample ${property.name}`,
+ }
+ })
+
+ return tags
+}
+
export interface EmailTemplaterLogicProps {
value: EmailTemplate | null
onChange: (value: EmailTemplate) => void
@@ -393,7 +433,11 @@ export interface emailTemplaterLogicActions {
export interface emailTemplaterLogicMeta {
__keaTypeGenInternalSelectorTypes: {
logicProps: (arg: any) => EmailTemplaterLogicProps
- mergeTags: (personPropertyDefinitions: PropertyDefinition[]) => UnlayerMergeTags
+ mergeTags: (
+ personPropertyDefinitions: PropertyDefinition[],
+ arg: EmailTemplaterType,
+ arg2: Record<string, any> | undefined
+ ) => UnlayerMergeTags
unlayerEditorProjectId: (preflight: PreflightStatus | null) => 275430 | undefined
emailMediaLibraryEnabled: (arg: EmailTemplaterType, unlayerEditorProjectId: 275430 | undefined) => boolean
unlayerEditorUser: (
@@ -533,32 +577,16 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([
selectors({
logicProps: [() => [(_, props) => props], (props: EmailTemplaterLogicProps) => props],
mergeTags: [
- (s) => [s.personPropertyDefinitions],
- (personPropertyDefinitions: PropertyDefinition[]): UnlayerMergeTags => {
- const tags: UnlayerMergeTags = {
- unsubscribe_url: {
- name: 'Unsubscribe URL',
- value: '{{unsubscribe_url}}',
- sample: 'https://example.com/unsubscribe/12345',
- },
- unsubscribe_url_one_click: {
- name: 'One-Click Unsubscribe URL',
- value: '{{unsubscribe_url_one_click}}',
- sample: 'https://example.com/unsubscribe/12345?one_click_unsubscribe=1',
- },
- }
-
- // Add person properties as merge tags
- personPropertyDefinitions.forEach((property: PropertyDefinition) => {
- tags[property.name] = {
- name: property.name,
- value: buildPersonPropertyMergeValue(property.name),
- sample: property.example || `Sample ${property.name}`,
- }
- })
-
- return tags
- },
+ (s) => [
+ s.personPropertyDefinitions,
+ (_, props: EmailTemplaterLogicProps) => props.type,
+ (_, props: EmailTemplaterLogicProps) => props.variables,
+ ],
+ (
+ personPropertyDefinitions: PropertyDefinition[],
+ type: EmailTemplaterType,
+ variables: Record<string, any> | undefined
+ ): UnlayerMergeTags => buildMergeTags(personPropertyDefinitions, type, variables),
],
unlayerEditorProjectId: [
(s) => [s.preflight],
@@ -649,6 +677,14 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([
})),
listeners(({ props, values, actions, cache }) => ({
+ // Person properties load after the editor starts, and the editor only reads its options once.
+ loadPersonPropertyDefinitionsSuccess: () => {
+ const mergeTags = buildMergeTags(values.personPropertyDefinitions, props.type, props.variables)
+ if (values.isEmailEditorReady && !objectsEqual(mergeTags, cache.lastMergeTags)) {
+ cache.lastMergeTags = mergeTags
+ values.emailEditorRef?.editor?.setMergeTags?.(mergeTags)
+ }
+ },
onEmailEditorReady: () => {
const editor = values.emailEditorRef?.editor
if (editor && values.emailMediaLibraryEnabled) {
@@ -662,6 +698,9 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([
// Both layouts rebaseline on load: the modal submit compares its export against the
// baseline to tell a no-op save from a real edit.
values.emailEditorRef?.editor?.addEventListener('design:loaded', () => actions.designLoaded())
+ // The editor read its merge tags when it started, so any added since then are pushed in.
+ cache.lastMergeTags = buildMergeTags(values.personPropertyDefinitions, props.type, props.variables)
+ values.emailEditorRef?.editor?.setMergeTags?.(cache.lastMergeTags)
if (props.value?.design) {
cache.lastEditorDesign = props.value.design
values.emailEditorRef?.editor?.loadDesign(props.value.design)
@@ -916,6 +955,13 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([
})),
propsChanged(({ actions, props, values, cache }, oldProps) => {
+ // A transactional email's merge tags follow the variables it uses, so the open editor gets new ones.
+ // Built from the new props here: a selector would still return its cached value until the store changes.
+ const mergeTags = buildMergeTags(values.personPropertyDefinitions, props.type, props.variables)
+ if (values.isEmailEditorReady && !objectsEqual(mergeTags, cache.lastMergeTags)) {
+ cache.lastMergeTags = mergeTags
+ values.emailEditorRef?.editor?.setMergeTags?.(mergeTags)
+ }
if (props.value && !objectsEqual(props.value, oldProps.value)) {
actions.resetEmailTemplate(props.value)
autoRevealAdvancedFields(actions, props)
diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx
index 6b03be375af9..3c6d83aefaa6 100644
--- a/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx
+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx
@@ -30,6 +30,7 @@ import { SceneContent } from '~/layout/scenes/components/SceneContent'
import { SceneTitleSection } from '~/layout/scenes/components/SceneTitleSection'
import { ProductKey } from '~/queries/schema/schema-general'
+import { transactionalEditorGlobals, variablesInEmail } from '../Transactional/wizard/emailVariables'
import { WorkflowInvocations } from '../Workflows/WorkflowInvocations'
import { workflowLogic } from '../Workflows/workflowLogic'
import { WorkflowMetrics } from '../Workflows/WorkflowMetrics'
@@ -90,7 +91,6 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
isSavingDraft,
isDiscardingDraft,
isSavingSensitive,
- createAsTransactional,
} = useValues(logic)
const transactionalEmailsEnabled = useFeatureFlag('WORKFLOWS_TRANSACTIONAL_EMAIL_API')
const todayRailNav = useFeatureFlag('TODAY_RAIL_NAV')
@@ -138,10 +138,15 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
onChange={(value) => setTemplateValue('content.email', value)}
onChangeTemplating={(templating) => setTemplateValue('content.email.templating', templating)}
type={
- template?.transactional_hog_flow_id || createAsTransactional
+ template?.transactional_hog_flow_id
? 'native_email_transactional_template'
: 'native_email_template'
}
+ variables={
+ template?.transactional_hog_flow_id
+ ? transactionalEditorGlobals(variablesInEmail(template.content.email))
+ : undefined
+ }
layout="inline"
/>
)}
@@ -261,12 +266,6 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
</Tooltip>
)}
</>
- ) : createAsTransactional ? (
- <Tooltip title="Saving creates the email and makes it transactional, so you can send it from your code.">
- <LemonTag type="success" className="ml-1">
- Transactional
- </LemonTag>
- </Tooltip>
) : undefined
}
actions={
diff --git a/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx b/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx
index 587b873a72a7..778b66644edb 100644
--- a/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx
+++ b/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx
@@ -6,15 +6,25 @@ import { CodeSnippet, Language } from 'lib/components/CodeSnippet'
import { teamLogic } from 'scenes/teamLogic'
import { urls } from 'scenes/urls'
-export function TransactionalEmailApiExample({ templateId }: { templateId: string }): JSX.Element {
+export function TransactionalEmailApiExample({
+ templateId,
+ variables,
+}: {
+ templateId: string
+ /** The email's `{{ variables.* }}` names. The snippet shows a sample when the email uses none. */
+ variables?: string[]
+}): JSX.Element {
const { currentTeamIdStrict } = useValues(teamLogic)
+ const messageData = variables?.length
+ ? `{ ${variables.map((name) => `"${name}": "..."`).join(', ')} }`
+ : '{ "first_name": "Jane", "reset_link": "https://example.com/reset" }'
const snippet = `curl -X POST ${window.location.origin}/api/projects/${currentTeamIdStrict}/messaging_templates/${templateId}/send/ \\
-H "Authorization: Bearer $POSTHOG_PROJECT_SECRET_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"identifiers": { "distinct_id": "jane-distinct-id" },
- "message_data": { "first_name": "Jane", "reset_link": "https://example.com/reset" }
+ "message_data": ${messageData}
}'`
return (
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index ae2e0a4c6a97..979b3d0caab5 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -3,7 +3,6 @@ import { expectLogic } from 'kea-test-utils'
import { FEATURE_FLAGS } from 'lib/constants'
import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
-import { removeProjectIdIfPresent } from 'lib/utils/kea-router'
import { useMocks } from '~/mocks/jest'
import { initKeaTests } from '~/test/init'
@@ -11,7 +10,6 @@ import type { ResourceEditedEvent } from '~/types'
import { resourceEditedLogic } from 'products/notifications/frontend/resourceEditedLogic'
-import { NEW_TEMPLATE } from './constants'
import { messageTemplateLogic } from './messageTemplateLogic'
jest.mock('lib/lemon-ui/LemonToast', () => ({
@@ -465,28 +463,5 @@ describe('messageTemplateLogic', () => {
expect(logic.values.template.name).toEqual('Renamed while converting')
}
})
-
- test.each([
- ['from the Transactional section converts it and opens it', { transactional: 'true' }, 1, '/created-id'],
- ['as a plain template leaves it alone', {}, 0, '/workflows/library'],
- ])('first save of a new template started %s', async (_name, search, expectedConversions, expectedPath) => {
- const makeTransactional = jest.fn(() => [200, { id: 'created-id', transactional_hog_flow_id: 'flow-id' }])
- useMocks({
- post: {
- '/api/projects/:team_id/messaging_templates/': { ...NEW_TEMPLATE, id: 'created-id' },
- '/api/projects/:team_id/messaging_templates/:id/make_transactional/': makeTransactional,
- },
- })
- router.actions.push('/workflows/library/templates/new', search)
- logic = messageTemplateLogic({ id: 'new' })
- logic.mount()
-
- await expectLogic(logic, () => {
- logic.actions.saveTemplate(logic.values.template)
- }).toFinishAllListeners()
-
- expect(makeTransactional).toHaveBeenCalledTimes(expectedConversions)
- expect(removeProjectIdIfPresent(router.values.location.pathname)).toMatch(new RegExp(`${expectedPath}$`))
- })
})
})
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
index 089fde78f8ba..2ae498c2cacb 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
@@ -34,7 +34,7 @@ import type { HogFunctionType, ResourceEditedEvent, UserBasicType } from '../../
import type { IntegrationType } from '../../../../frontend/src/types'
import { workflowLogic } from '../Workflows/workflowLogic'
import { NEW_TEMPLATE } from './constants'
-import { TRANSACTIONAL_PARAM, newTemplateAgentLogic } from './newTemplateAgentLogic'
+import { newTemplateAgentLogic } from './newTemplateAgentLogic'
import { TemplateSection, templateLibraryUrl, templateSectionFor, templateUrlInSection } from './templateSection'
import { MessageTemplate } from './types'
@@ -63,7 +63,6 @@ export interface messageTemplateLogicValues {
integrations: IntegrationType[] | null // integrationsLogic
aiComposerAvailable: boolean // newTemplateAgentLogic
currentTeamIdStrict: number | string // teamLogic
- createAsTransactional: boolean
deferredExternalEdit: ResourceEditedEvent | null
draftOutOfDate: boolean
draftsEnabled: boolean
@@ -447,9 +446,8 @@ export interface messageTemplateLogicMeta {
key: string
__keaTypeGenInternalSelectorTypes: {
logicProps: (arg: MessageTemplateLogicProps) => MessageTemplateLogicProps
- createAsTransactional: (searchParams: Record<string, any>, arg: MessageTemplateLogicProps) => boolean
transactionalHogFlowId: (originalTemplate: MessageTemplate) => string | null
- isTransactional: (transactionalHogFlowId: string | null, createAsTransactional: boolean) => boolean
+ isTransactional: (transactionalHogFlowId: string | null) => boolean
section: (location: { hash: string; pathname: string; search: string }) => TemplateSection
listUrl: (isTransactional: boolean, section: TemplateSection) => string
draftsEnabled: (transactionalHogFlowId: string | null) => boolean
@@ -657,21 +655,14 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
],
}),
selectors({
- // A new template started from the Transactional section. Its first save also makes it transactional.
- createAsTransactional: [
- () => [router.selectors.searchParams, (_, props: MessageTemplateLogicProps) => props],
- (searchParams: Record<string, any>, props: MessageTemplateLogicProps): boolean =>
- props.id === 'new' && !props.messageId && searchParams[TRANSACTIONAL_PARAM] === 'true',
- ],
// The saved state decides it: an unsaved template can't be transactional yet.
transactionalHogFlowId: [
(s) => [s.originalTemplate],
(originalTemplate: MessageTemplate): string | null => originalTemplate.transactional_hog_flow_id ?? null,
],
isTransactional: [
- (s) => [s.transactionalHogFlowId, s.createAsTransactional],
- (transactionalHogFlowId: string | null, createAsTransactional: boolean): boolean =>
- !!transactionalHogFlowId || createAsTransactional,
+ (s) => [s.transactionalHogFlowId],
+ (transactionalHogFlowId: string | null): boolean => !!transactionalHogFlowId,
],
// The nav section the page was opened under. Links from the page stay in it.
section: [
@@ -1013,21 +1004,6 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
lemonToast.error('Failed to save template. Please try again.')
},
saveTemplateSuccess: async ({ template }) => {
- if (values.createAsTransactional && template.id) {
- actions.resetTemplate(template)
- actions.setOriginalTemplate(template)
- try {
- await messagingTemplatesMakeTransactionalCreate(String(values.currentTeamIdStrict), template.id, {})
- lemonToast.success('Transactional email created. Send it from the API tab.')
- } catch (error: any) {
- // The template exists either way. Its API tab offers "Make transactional" to try again.
- lemonToast.error(
- `Template created. Couldn't make it transactional: ${error?.detail ?? 'unknown error'}. Try again from the API tab.`
- )
- }
- router.actions.replace(urls.transactionalTemplate(template.id))
- return
- }
lemonToast.success(
props.id === 'new' ? 'Template created' : values.draftsEnabled ? 'Published' : 'Template saved'
)
diff --git a/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts b/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts
index ca77e00bdbbf..372a617cc524 100644
--- a/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts
+++ b/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts
@@ -92,9 +92,6 @@ export interface newTemplateAgentLogicActions {
startNewTemplate: () => {
value: true
}
- startNewTransactionalEmail: () => {
- value: true
- }
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
@@ -122,9 +119,6 @@ export type newTemplateAgentLogicType = MakeLogicType<
newTemplateAgentLogicMeta
>
-// pinned: URL search param - the new-template editor reads it to make the template transactional on its first save
-export const TRANSACTIONAL_PARAM = 'transactional'
-
/** Entry, mode and picked starting point for the AI-first "New template" page. */
export const newTemplateAgentLogic = kea<newTemplateAgentLogicType>([
path(['products', 'workflows', 'frontend', 'library', 'newTemplateAgentLogic']),
@@ -141,7 +135,6 @@ export const newTemplateAgentLogic = kea<newTemplateAgentLogicType>([
})),
actions({
startNewTemplate: true,
- startNewTransactionalEmail: true,
openEditorFromAiComposer: true,
setPickedTemplate: (template: MessageTemplate | null) => ({ template }),
}),
@@ -194,10 +187,6 @@ export const newTemplateAgentLogic = kea<newTemplateAgentLogicType>([
values.aiFirstNewEnabled ? { [EDITOR_MODE_PARAM]: AI_COMPOSER_MODE_VALUE } : {}
)
},
- // Skips the AI composer, which writes a plain template.
- startNewTransactionalEmail: () => {
- router.actions.push(urls.workflowsLibraryTemplateNew(), { [TRANSACTIONAL_PARAM]: 'true' })
- },
// The editor URL keeps the composer from rendering again, and the editor opens its picker for it.
openEditorFromAiComposer: () => {
router.actions.push(urls.workflowsLibraryTemplateNew(), { [EDITOR_MODE_PARAM]: EDITOR_MODE_VALUE })
diff --git a/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx b/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx
index 79cc6f0be270..45e2b3dbe671 100644
--- a/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx
+++ b/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx
@@ -1,4 +1,5 @@
-import { useActions, useMountedLogic, useValues } from 'kea'
+import { useMountedLogic, useValues } from 'kea'
+import { router } from 'kea-router'
import { IconLock } from '@posthog/icons'
import { LemonTag, Link } from '@posthog/lemon-ui'
@@ -14,13 +15,11 @@ import { urls } from 'scenes/urls'
import { AccessControlLevel, AccessControlResourceType } from '~/types'
import { messageTemplatesLogic } from '../TemplateLibrary/messageTemplatesLogic'
-import { newTemplateAgentLogic } from '../TemplateLibrary/newTemplateAgentLogic'
import { MessageTemplate } from '../TemplateLibrary/types'
export function TransactionalEmailsTable(): JSX.Element {
useMountedLogic(messageTemplatesLogic)
const { transactionalTemplates, templatesLoading } = useValues(messageTemplatesLogic)
- const { startNewTransactionalEmail } = useActions(newTemplateAgentLogic)
if (!templatesLoading && transactionalTemplates.length === 0) {
return (
@@ -28,7 +27,7 @@ export function TransactionalEmailsTable(): JSX.Element {
thingName="transactional email"
description="Send emails from your code with one API call. Use them for emails a person triggers, like password resets, receipts and sign-in codes. This tab shows how many were sent, delivered and failed in the last 7 days."
docsURL="https://posthog.com/docs/workflows"
- action={startNewTransactionalEmail}
+ action={() => router.actions.push(urls.transactionalNew())}
disabledReason={
getAccessControlDisabledReason(AccessControlResourceType.Workflow, AccessControlLevel.Editor) ??
undefined
diff --git a/products/workflows/frontend/Transactional/TransactionalScene.tsx b/products/workflows/frontend/Transactional/TransactionalScene.tsx
index 721fe5597b3e..1ff7688fefdb 100644
--- a/products/workflows/frontend/Transactional/TransactionalScene.tsx
+++ b/products/workflows/frontend/Transactional/TransactionalScene.tsx
@@ -1,4 +1,4 @@
-import { useActions, useValues } from 'kea'
+import { useValues } from 'kea'
import { router } from 'kea-router'
import { LemonButton } from '@posthog/lemon-ui'
@@ -25,8 +25,8 @@ import {
MessagingNavTabKey,
isMessagingSetupTab,
} from '../messagingTabs'
-import { newTemplateAgentLogic } from '../TemplateLibrary/newTemplateAgentLogic'
import { TransactionalEmailsTable } from './TransactionalEmailsTable'
+import { TransactionalEmailWizard } from './wizard/TransactionalEmailWizard'
export const scene: SceneExport = {
component: TransactionalScene,
@@ -35,19 +35,24 @@ export const scene: SceneExport = {
export function TransactionalScene(): JSX.Element {
const { location } = useValues(router)
- const { startNewTransactionalEmail } = useActions(newTemplateAgentLogic)
const showTransactional = useFeatureFlag('WORKFLOWS_TRANSACTIONAL_EMAIL_API')
const todayRailNav = useFeatureFlag('TODAY_RAIL_NAV')
// The tab routes are literal paths, so the tab is the last path segment rather than a route param.
- const lastSegment = location.pathname.split('/').pop() as MessagingNavTabKey
- const currentTab: MessagingNavTabKey | 'transactional' = MESSAGING_NAV_TAB_KEYS.includes(lastSegment)
- ? lastSegment
+ const lastSegment = location.pathname.split('/').pop() ?? ''
+ const currentTab: MessagingNavTabKey | 'transactional' = MESSAGING_NAV_TAB_KEYS.includes(
+ lastSegment as MessagingNavTabKey
+ )
+ ? (lastSegment as MessagingNavTabKey)
: 'transactional'
if (!showTransactional) {
return <NotFound object="page" />
}
+ if (lastSegment === 'new') {
+ return <TransactionalEmailWizard />
+ }
+
return (
<SceneContent>
<SceneTitleSection
@@ -63,7 +68,7 @@ export function TransactionalScene(): JSX.Element {
{todayRailNav ? (
<Button
data-attr="new-transactional-email"
- onClick={startNewTransactionalEmail}
+ onClick={() => router.actions.push(urls.transactionalNew())}
variant="primary"
>
New transactional email
@@ -71,7 +76,7 @@ export function TransactionalScene(): JSX.Element {
) : (
<LemonButton
data-attr="new-transactional-email"
- onClick={startNewTransactionalEmail}
+ to={urls.transactionalNew()}
type="primary"
size="small"
>
diff --git a/products/workflows/frontend/Transactional/wizard/TransactionalEmailWizard.tsx b/products/workflows/frontend/Transactional/wizard/TransactionalEmailWizard.tsx
new file mode 100644
index 000000000000..ed345b2f73b3
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/TransactionalEmailWizard.tsx
@@ -0,0 +1,98 @@
+import { useActions, useMountedLogic, useValues } from 'kea'
+
+import { LemonButton } from '@posthog/lemon-ui'
+
+import { GuidedWizardStep, GuidedWizardStepper } from 'lib/components/GuidedWizard/GuidedWizardStepper'
+import { urls } from 'scenes/urls'
+
+import { SceneContent } from '~/layout/scenes/components/SceneContent'
+import { SceneTitleSection } from '~/layout/scenes/components/SceneTitleSection'
+
+import { ContentStep } from './steps/ContentStep'
+import { NameStep } from './steps/NameStep'
+import { SenderStep } from './steps/SenderStep'
+import { SendStep } from './steps/SendStep'
+import { TransactionalEmailWizardStep, transactionalEmailWizardLogic } from './transactionalEmailWizardLogic'
+
+const STEPS: GuidedWizardStep<TransactionalEmailWizardStep>[] = [
+ { step: 'name', label: 'Name', dataAttr: 'transactional-email-wizard-step-name' },
+ { step: 'sender', label: 'Sender', dataAttr: 'transactional-email-wizard-step-sender' },
+ { step: 'content', label: 'Content', dataAttr: 'transactional-email-wizard-step-content' },
+ { step: 'send', label: 'Send from your code', dataAttr: 'transactional-email-wizard-step-send' },
+]
+
+const STEP_CONTENT: Record<TransactionalEmailWizardStep, () => JSX.Element> = {
+ name: NameStep,
+ sender: SenderStep,
+ content: ContentStep,
+ send: SendStep,
+}
+
+export function TransactionalEmailWizard(): JSX.Element {
+ useMountedLogic(transactionalEmailWizardLogic)
+ const { currentStep, currentStepErrors, isCreating } = useValues(transactionalEmailWizardLogic)
+ const { setStep, nextStep, previousStep, createTransactionalEmail } = useActions(transactionalEmailWizardLogic)
+ const StepContent = STEP_CONTENT[currentStep]
+ const isFirstStep = currentStep === STEPS[0].step
+ const isLastStep = currentStep === STEPS[STEPS.length - 1].step
+
+ return (
+ <SceneContent data-attr="transactional-email-wizard">
+ <SceneTitleSection
+ name="New transactional email"
+ description="Write the email once, then send it from your code with one API call"
+ resourceType={{ type: 'transactional' }}
+ actions={
+ <LemonButton type="secondary" size="small" to={urls.transactional()}>
+ Cancel
+ </LemonButton>
+ }
+ />
+ <GuidedWizardStepper
+ steps={STEPS}
+ currentStep={currentStep}
+ // The draft is already on its way, so edits made now would be lost.
+ onStepClick={isCreating ? undefined : setStep}
+ className="flex-wrap"
+ aria-label="Transactional email wizard progress"
+ />
+ {/* The editor stays mounted, so an edit still saving when you leave Content isn't lost. */}
+ <div hidden={currentStep !== 'content'}>
+ <ContentStep />
+ </div>
+ {currentStep !== 'content' ? <StepContent /> : null}
+ <div className="flex justify-between gap-2 border-t pt-3">
+ {isFirstStep ? (
+ <span />
+ ) : (
+ <LemonButton
+ type="secondary"
+ onClick={previousStep}
+ disabledReason={isCreating ? 'Creating the email' : undefined}
+ >
+ Back
+ </LemonButton>
+ )}
+ {isLastStep ? (
+ <LemonButton
+ type="primary"
+ onClick={createTransactionalEmail}
+ loading={isCreating}
+ data-attr="transactional-email-wizard-create"
+ >
+ Create transactional email
+ </LemonButton>
+ ) : (
+ <LemonButton
+ type="primary"
+ onClick={nextStep}
+ disabledReason={currentStepErrors[0]}
+ data-attr="transactional-email-wizard-next"
+ >
+ Next
+ </LemonButton>
+ )}
+ </div>
+ </SceneContent>
+ )
+}
diff --git a/products/workflows/frontend/Transactional/wizard/emailVariables.test.ts b/products/workflows/frontend/Transactional/wizard/emailVariables.test.ts
new file mode 100644
index 000000000000..8f4f7a49cd53
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/emailVariables.test.ts
@@ -0,0 +1,41 @@
+import { variablesInEmail } from './emailVariables'
+
+describe('variablesInEmail', () => {
+ test.each([
+ [
+ 'finds a variable in the body',
+ { subject: 'Hi', html: '<a href="{{ variables.reset_link }}">Reset</a>' },
+ ['reset_link'],
+ ],
+ [
+ 'keeps first-seen order across subject and body, without duplicates',
+ { subject: 'Hi {{ variables.first_name }}', html: '{{variables.code}} {{ variables.first_name }}' },
+ ['first_name', 'code'],
+ ],
+ ['reads past a Liquid filter', { subject: '{{ variables.name | default: "there" }}', html: '' }, ['name']],
+ ['ignores person properties', { subject: '{{ person.properties.email }}', html: '' }, []],
+ [
+ 'finds a variable in a control tag',
+ { subject: '', html: '{% if variables.show_receipt %}Hi{% endif %}' },
+ ['show_receipt'],
+ ],
+ [
+ 'finds a variable used as a filter argument',
+ { subject: '{{ variables.name | default: variables.fallback_name }}', html: '' },
+ ['name', 'fallback_name'],
+ ],
+ ['ignores the word outside Liquid', { subject: 'See variables.example in the docs', html: '' }, []],
+ [
+ 'finds a variable in the sender name and reply-to',
+ {
+ subject: '',
+ html: '',
+ from: { name: '{{ variables.sender_name }}' },
+ replyTo: '{{ variables.reply_to }}',
+ },
+ ['sender_name', 'reply_to'],
+ ],
+ ])('%s', (_, email, expected) => {
+ expect(variablesInEmail({ text: '', from: '', ...email })).toEqual(expected)
+ })
+})
diff --git a/products/workflows/frontend/Transactional/wizard/emailVariables.ts b/products/workflows/frontend/Transactional/wizard/emailVariables.ts
new file mode 100644
index 000000000000..deb838df07c9
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/emailVariables.ts
@@ -0,0 +1,35 @@
+import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'
+
+// Any Liquid output `{{ … }}` or tag `{% … %}`. Variables can sit anywhere inside one, such as
+// `{% if variables.show_receipt %}` or `{{ variables.name | default: variables.fallback_name }}`.
+const LIQUID_EXPRESSION = /\{\{[\s\S]*?\}\}|\{%[\s\S]*?%\}/g
+const VARIABLE_REFERENCE = /\bvariables\.([A-Za-z_][A-Za-z0-9_]*)/g
+
+/** The `message_data` keys an email reads, in the order they first appear in its sender, subject, preheader and body. */
+export function variablesInEmail(
+ email: Pick<EmailTemplate, 'subject' | 'html' | 'text' | 'preheader' | 'from' | 'replyTo'>
+): string[] {
+ const from = typeof email.from === 'object' && email.from ? email.from : {}
+ const source = [from.name, from.email, email.replyTo, email.subject, email.preheader, email.html, email.text]
+ .filter(Boolean)
+ .join('\n')
+ const expressions = source.match(LIQUID_EXPRESSION) ?? []
+ return [
+ ...new Set(
+ expressions.flatMap((expression) => [...expression.matchAll(VARIABLE_REFERENCE)].map((match) => match[1]))
+ ),
+ ]
+}
+
+/** Editor globals for a transactional email: its variables feed the merge tags and Liquid autocomplete. */
+export function transactionalEditorGlobals(names: string[]): { variables: Record<string, string> } {
+ return { variables: Object.fromEntries(names.map((name) => [name, ''])) }
+}
+
+/** A name a person typed, made safe to use after `variables.`. */
+export function cleanVariableName(name: string): string {
+ return name
+ .trim()
+ .replace(/[^A-Za-z0-9_]/g, '_')
+ .replace(/^(\d)/, '_$1')
+}
diff --git a/products/workflows/frontend/Transactional/wizard/steps/ContentStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/ContentStep.tsx
new file mode 100644
index 000000000000..37d5ac0909bb
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/steps/ContentStep.tsx
@@ -0,0 +1,82 @@
+import { useActions, useValues } from 'kea'
+import { useState } from 'react'
+
+import { IconPlus } from '@posthog/icons'
+import { LemonButton, LemonInput, LemonTag } from '@posthog/lemon-ui'
+
+import { EmailTemplater } from 'scenes/hog-functions/email-templater/EmailTemplater'
+
+import { cleanVariableName } from '../emailVariables'
+import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'
+
+export function ContentStep(): JSX.Element {
+ const { draft, variables, panelVariables, editorGlobals } = useValues(transactionalEmailWizardLogic)
+ const { updateDraft, addVariable } = useActions(transactionalEmailWizardLogic)
+ const [newVariable, setNewVariable] = useState('')
+ const newVariableName = cleanVariableName(newVariable)
+ const submitNewVariable = (): void => {
+ if (newVariableName) {
+ addVariable(newVariableName)
+ setNewVariable('')
+ }
+ }
+
+ return (
+ <div className="flex flex-col @min-[64rem]/main-content:flex-row gap-4 min-h-[36rem]">
+ <div className="flex flex-col flex-1 min-w-0">
+ <EmailTemplater
+ value={draft.email}
+ onChange={(email) => updateDraft({ email })}
+ type="native_email_transactional_template"
+ variables={editorGlobals}
+ layout="inline"
+ />
+ </div>
+ <div
+ className="flex flex-col gap-2 @min-[64rem]/main-content:w-64 shrink-0 border rounded p-3 self-start"
+ data-attr="transactional-email-wizard-variables"
+ >
+ <div className="font-semibold">Variables your code sends</div>
+ <p className="text-secondary text-sm m-0">
+ Your code passes these in <code>message_data</code> with each send. Person properties aren't
+ available.
+ </p>
+ {panelVariables.length ? (
+ <ul className="flex flex-col gap-1 m-0 p-0 list-none">
+ {panelVariables.map((name) => (
+ <li key={name} className="flex items-center justify-between gap-2">
+ <code className="truncate">{name}</code>
+ {variables.includes(name) ? null : <LemonTag size="small">Not used yet</LemonTag>}
+ </li>
+ ))}
+ </ul>
+ ) : null}
+ <div className="flex gap-1">
+ <LemonInput
+ size="small"
+ className="flex-1 min-w-0"
+ placeholder="Variable name, like first_name"
+ value={newVariable}
+ onChange={setNewVariable}
+ onPressEnter={submitNewVariable}
+ data-attr="transactional-email-wizard-new-variable"
+ />
+ <LemonButton
+ size="small"
+ type="secondary"
+ icon={<IconPlus />}
+ disabledReason={!newVariableName ? 'Type a variable name first' : undefined}
+ onClick={submitNewVariable}
+ data-attr="transactional-email-wizard-add-variable"
+ >
+ Add
+ </LemonButton>
+ </div>
+ <p className="text-secondary text-sm m-0">
+ Insert one in the body from <b>Merge tags</b> in a text block's toolbar. In the subject, type it as{' '}
+ <code>{'{{ variables.first_name }}'}</code>.
+ </p>
+ </div>
+ </div>
+ )
+}
diff --git a/products/workflows/frontend/Transactional/wizard/steps/NameStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/NameStep.tsx
new file mode 100644
index 000000000000..e69f17f82d32
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/steps/NameStep.tsx
@@ -0,0 +1,50 @@
+import { useActions, useValues } from 'kea'
+
+import { LemonInput, LemonSwitch } from '@posthog/lemon-ui'
+
+import { LemonField } from 'lib/lemon-ui/LemonField'
+import { LemonTextArea } from 'lib/lemon-ui/LemonTextArea'
+
+import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'
+
+export function NameStep(): JSX.Element {
+ const { draft } = useValues(transactionalEmailWizardLogic)
+ const { updateDraft } = useActions(transactionalEmailWizardLogic)
+
+ return (
+ <div className="flex flex-col gap-4 max-w-160">
+ <LemonField.Pure label="Name" help="Only your team sees this.">
+ <LemonInput
+ autoFocus
+ value={draft.name}
+ placeholder="Password reset"
+ onChange={(name) => updateDraft({ name })}
+ data-attr="transactional-email-wizard-name"
+ />
+ </LemonField.Pure>
+ <LemonField.Pure label="Description" showOptional>
+ <LemonTextArea
+ value={draft.description}
+ placeholder="Sent when someone asks to reset their password"
+ onChange={(description) => updateDraft({ description })}
+ data-attr="transactional-email-wizard-description"
+ />
+ </LemonField.Pure>
+ <LemonSwitch
+ bordered
+ checked={draft.sensitive}
+ onChange={(sensitive) => updateDraft({ sensitive })}
+ label={
+ <div>
+ <div className="font-semibold">Protect sensitive data</div>
+ <div className="text-secondary text-sm font-normal">
+ For emails with login codes or reset links. PostHog keeps no copy of what each email
+ contained, and clicked links keep only the site address.
+ </div>
+ </div>
+ }
+ data-attr="transactional-email-wizard-sensitive"
+ />
+ </div>
+ )
+}
diff --git a/products/workflows/frontend/Transactional/wizard/steps/SendStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/SendStep.tsx
new file mode 100644
index 000000000000..3e933c5b91eb
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/steps/SendStep.tsx
@@ -0,0 +1,43 @@
+import { useValues } from 'kea'
+
+import { LemonTag } from '@posthog/lemon-ui'
+
+import { senderFrom } from 'scenes/hog-functions/email-templater/emailSenderFields'
+
+import { TransactionalEmailApiExample } from '../../../TemplateLibrary/TransactionalEmailApiExample'
+import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'
+
+export function SendStep(): JSX.Element {
+ const { draft, senders, variables } = useValues(transactionalEmailWizardLogic)
+ const from = senderFrom(draft.email)
+ const sender = senders.find((candidate) => candidate.id === from.integrationId)
+
+ return (
+ <div className="flex flex-col gap-4 max-w-200">
+ <dl className="grid grid-cols-[8rem_minmax(0,1fr)] gap-x-4 gap-y-1 m-0 border rounded p-3">
+ <dt className="text-secondary">Name</dt>
+ <dd className="m-0 flex gap-2 items-center flex-wrap">
+ {draft.name}
+ {draft.sensitive ? <LemonTag type="highlight">Sensitive</LemonTag> : null}
+ </dd>
+ <dt className="text-secondary">From</dt>
+ <dd className="m-0 truncate">{from.email || sender?.config?.email}</dd>
+ <dt className="text-secondary">Subject</dt>
+ <dd className="m-0 truncate">{draft.email.subject}</dd>
+ <dt className="text-secondary">Variables</dt>
+ <dd className="m-0 flex gap-1 flex-wrap">
+ {variables.length ? variables.map((name) => <code key={name}>{name}</code>) : 'None'}
+ </dd>
+ </dl>
+ <TransactionalEmailApiExample templateId="TEMPLATE_ID" variables={variables} />
+ <ul className="list-disc pl-6 m-0 flex flex-col gap-1 text-secondary">
+ <li>
+ <code>TEMPLATE_ID</code> is filled in on the email's page once you create it.
+ </li>
+ <li>Transactional emails ignore marketing opt-outs, so don't use them for marketing.</li>
+ <li>Later edits save as a draft until you publish them.</li>
+ <li>An email created here stays transactional.</li>
+ </ul>
+ </div>
+ )
+}
diff --git a/products/workflows/frontend/Transactional/wizard/steps/SenderStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/SenderStep.tsx
new file mode 100644
index 000000000000..754b1ce91778
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/steps/SenderStep.tsx
@@ -0,0 +1,63 @@
+import { useActions, useValues } from 'kea'
+
+import { LemonButton } from '@posthog/lemon-ui'
+
+import { ProductIntroduction } from 'lib/components/ProductIntroduction/ProductIntroduction'
+import { integrationsLogic } from 'lib/integrations/integrationsLogic'
+import { Spinner } from 'lib/lemon-ui/Spinner'
+import { senderFrom } from 'scenes/hog-functions/email-templater/emailSenderFields'
+import { EmailSenderForm } from 'scenes/hog-functions/email-templater/EmailSenderForm'
+import { urls } from 'scenes/urls'
+
+import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'
+
+export function SenderStep(): JSX.Element {
+ const { draft, senders } = useValues(transactionalEmailWizardLogic)
+ const { updateEmail } = useActions(transactionalEmailWizardLogic)
+ const { integrations, integrationsLoading } = useValues(integrationsLogic)
+ const { loadIntegrations } = useActions(integrationsLogic)
+
+ // A failed load clears the loading flag, and falls through to the retry below.
+ if (integrations === null && integrationsLoading) {
+ return <Spinner className="text-lg" />
+ }
+
+ if (senders.length === 0) {
+ return (
+ <ProductIntroduction
+ titleOverride="Set up a sending domain first"
+ thingName="email sender"
+ description="Transactional emails send from a verified domain. Verify one in a new tab, then check again here to finish this email."
+ isEmpty
+ actionElementOverride={
+ <div className="flex gap-2 flex-wrap">
+ <LemonButton type="primary" to={urls.transactional('channels')} targetBlank>
+ Set up a sending domain
+ </LemonButton>
+ {/* Domain setup opens in a new tab, so this picks up the sender without losing the email. */}
+ <LemonButton
+ type="secondary"
+ onClick={loadIntegrations}
+ loading={integrationsLoading}
+ data-attr="transactional-email-wizard-check-senders"
+ >
+ Check again
+ </LemonButton>
+ </div>
+ }
+ />
+ )
+ }
+
+ return (
+ <div className="max-w-160 [&>div]:w-full [&>div]:p-0">
+ <EmailSenderForm
+ from={senderFrom(draft.email)}
+ replyTo={draft.email.replyTo}
+ senders={senders}
+ onChangeFrom={(from) => updateEmail({ from })}
+ onChangeReplyTo={(replyTo) => updateEmail({ replyTo })}
+ />
+ </div>
+ )
+}
diff --git a/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.test.ts b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.test.ts
new file mode 100644
index 000000000000..cf5d3bf9e3e1
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.test.ts
@@ -0,0 +1,69 @@
+import { router } from 'kea-router'
+import { expectLogic } from 'kea-test-utils'
+
+import { removeProjectIdIfPresent } from 'lib/utils/kea-router'
+
+import { useMocks } from '~/mocks/jest'
+import { initKeaTests } from '~/test/init'
+
+import { transactionalEmailWizardLogic } from './transactionalEmailWizardLogic'
+
+jest.mock('lib/lemon-ui/LemonToast', () => ({ lemonToast: { success: jest.fn(), error: jest.fn() } }))
+
+describe('transactionalEmailWizardLogic', () => {
+ let logic: ReturnType<typeof transactionalEmailWizardLogic.build>
+ let createTemplate: jest.Mock
+ let makeTransactional: jest.Mock
+
+ beforeEach(() => {
+ createTemplate = jest.fn(() => [201, { id: 'created-id' }])
+ makeTransactional = jest.fn(() => [200, { id: 'created-id', transactional_hog_flow_id: 'flow-id' }])
+ useMocks({
+ get: {
+ '/api/environments/:team_id/integrations/': {
+ results: [
+ {
+ id: 7,
+ kind: 'email',
+ config: { email: '[email protected]', domain: 'example.com', verified: true },
+ },
+ ],
+ },
+ },
+ post: {
+ '/api/projects/:team_id/messaging_templates/': createTemplate,
+ '/api/projects/:team_id/messaging_templates/:id/make_transactional/': makeTransactional,
+ },
+ })
+ initKeaTests()
+ router.actions.push('/transactional/new')
+ logic = transactionalEmailWizardLogic()
+ logic.mount()
+ })
+
+ afterEach(() => {
+ logic.unmount()
+ })
+
+ test.each([
+ ['an email missing its sender is not created', {}, 0, 'sender', '/transactional/new'],
+ [
+ 'a complete email is created, made transactional, and opened in its section',
+ { from: { integrationId: 7 }, subject: 'Reset your password' },
+ 1,
+ 'name',
+ '/transactional/library/templates/created-id',
+ ],
+ ])('%s', async (_, emailPatch, expectedCalls, expectedStep, expectedPath) => {
+ await expectLogic(logic).toFinishAllListeners()
+ logic.actions.updateDraft({ name: 'Password reset' })
+ logic.actions.updateEmail(emailPatch)
+
+ await expectLogic(logic, () => logic.actions.createTransactionalEmail()).toFinishAllListeners()
+
+ expect(createTemplate).toHaveBeenCalledTimes(expectedCalls)
+ expect(makeTransactional).toHaveBeenCalledTimes(expectedCalls)
+ expect(removeProjectIdIfPresent(router.values.location.pathname)).toEqual(expectedPath)
+ expect(logic.values.currentStep).toEqual(expectedStep)
+ })
+})
diff --git a/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.ts b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.ts
new file mode 100644
index 000000000000..d222c9e89dd9
--- /dev/null
+++ b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.ts
@@ -0,0 +1,299 @@
+import { MakeLogicType, actions, afterMount, connect, kea, listeners, path, reducers, selectors } from 'kea'
+import { beforeUnload, router } from 'kea-router'
+import posthog from 'posthog-js'
+
+import { integrationsLogic } from 'lib/integrations/integrationsLogic'
+import { lemonToast } from 'lib/lemon-ui/LemonToast'
+import { senderAddressError, senderFrom } from 'scenes/hog-functions/email-templater/emailSenderFields'
+import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'
+import { teamLogic } from 'scenes/teamLogic'
+import { urls } from 'scenes/urls'
+
+import type { IntegrationType } from '~/types'
+
+import {
+ messagingTemplatesCreate,
+ messagingTemplatesMakeTransactionalCreate,
+} from 'products/messaging/frontend/generated/api'
+import type { MessageTemplateContentApi } from 'products/messaging/frontend/generated/api.schemas'
+
+import { NEW_TEMPLATE } from '../../TemplateLibrary/constants'
+import { cleanVariableName, transactionalEditorGlobals, variablesInEmail } from './emailVariables'
+
+export type TransactionalEmailWizardStep = 'name' | 'sender' | 'content' | 'send'
+
+export const TRANSACTIONAL_EMAIL_WIZARD_STEPS: TransactionalEmailWizardStep[] = ['name', 'sender', 'content', 'send']
+
+export interface TransactionalEmailDraft {
+ name: string
+ description: string
+ sensitive: boolean
+ email: EmailTemplate
+}
+
+const EMPTY_DRAFT: TransactionalEmailDraft = {
+ name: '',
+ description: '',
+ sensitive: false,
+ // The editor's starter design, with no subject, so nothing sends as "Hello from PostHog" by accident.
+ email: { ...NEW_TEMPLATE.content.email, subject: '' },
+}
+
+/** What still blocks each step, so Next and the stepper can say why. */
+export function wizardStepErrors(
+ draft: TransactionalEmailDraft,
+ senders: IntegrationType[]
+): Record<TransactionalEmailWizardStep, string[]> {
+ const from = senderFrom(draft.email)
+ const sender = senders.find((candidate) => candidate.id === from.integrationId)
+ const addressError = senderAddressError(from.email, sender)
+ return {
+ name: draft.name.trim() ? [] : ['Give the email a name'],
+ sender: !sender ? ['Choose who the email comes from'] : addressError ? [addressError] : [],
+ content: [
+ ...(draft.email.subject.trim() ? [] : ['Add a subject']),
+ ...(draft.email.html || draft.email.text ? [] : ['Add a body']),
+ ],
+ send: [],
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface transactionalEmailWizardLogicValues {
+ integrations: IntegrationType[] | null // integrationsLogic
+ currentTeamIdStrict: number | string // teamLogic
+ addedVariables: string[]
+ created: boolean
+ currentStep: TransactionalEmailWizardStep
+ currentStepErrors: string[]
+ draft: TransactionalEmailDraft
+ editorGlobals: {
+ variables: Record<string, string>
+ }
+ hasChanges: boolean
+ isCreating: boolean
+ panelVariables: string[]
+ senders: IntegrationType[]
+ stepErrors: Record<TransactionalEmailWizardStep, string[]>
+ variables: string[]
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface transactionalEmailWizardLogicActions {
+ addVariable: (name: string) => {
+ name: string
+ }
+ createTransactionalEmail: () => {
+ value: true
+ }
+ createTransactionalEmailFinished: (created: boolean) => {
+ created: boolean
+ }
+ nextStep: () => {
+ value: true
+ }
+ previousStep: () => {
+ value: true
+ }
+ resetWizard: () => {
+ value: true
+ }
+ setStep: (step: TransactionalEmailWizardStep) => {
+ step: TransactionalEmailWizardStep
+ }
+ updateDraft: (patch: Partial<TransactionalEmailDraft>) => {
+ patch: Partial<TransactionalEmailDraft>
+ }
+ updateEmail: (patch: Partial<EmailTemplate>) => {
+ patch: Partial<EmailTemplate>
+ }
+}
+
+// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
+export interface transactionalEmailWizardLogicMeta {
+ __keaTypeGenInternalSelectorTypes: {
+ senders: (integrations: IntegrationType[] | null) => IntegrationType[]
+ stepErrors: (
+ draft: TransactionalEmailDraft,
+ senders: IntegrationType[]
+ ) => Record<TransactionalEmailWizardStep, string[]>
+ currentStepErrors: (
+ stepErrors: Record<TransactionalEmailWizardStep, string[]>,
+ currentStep: TransactionalEmailWizardStep
+ ) => string[]
+ variables: (draft: TransactionalEmailDraft) => string[]
+ panelVariables: (variables: string[], addedVariables: string[]) => string[]
+ editorGlobals: (panelVariables: string[]) => {
+ variables: Record<string, string>
+ }
+ hasChanges: (draft: TransactionalEmailDraft) => boolean
+ }
+}
+
+export type transactionalEmailWizardLogicType = MakeLogicType<
+ transactionalEmailWizardLogicValues,
+ transactionalEmailWizardLogicActions,
+ Record<string, any>,
+ transactionalEmailWizardLogicMeta
+>
+
+export const transactionalEmailWizardLogic = kea<transactionalEmailWizardLogicType>([
+ path(['products', 'workflows', 'frontend', 'Transactional', 'wizard', 'transactionalEmailWizardLogic']),
+ connect(() => ({
+ values: [teamLogic, ['currentTeamIdStrict'], integrationsLogic, ['integrations']],
+ })),
+ actions({
+ setStep: (step: TransactionalEmailWizardStep) => ({ step }),
+ nextStep: true,
+ previousStep: true,
+ updateDraft: (patch: Partial<TransactionalEmailDraft>) => ({ patch }),
+ updateEmail: (patch: Partial<EmailTemplate>) => ({ patch }),
+ addVariable: (name: string) => ({ name }),
+ resetWizard: true,
+ createTransactionalEmail: true,
+ createTransactionalEmailFinished: (created: boolean) => ({ created }),
+ }),
+ reducers({
+ currentStep: [
+ 'name' as TransactionalEmailWizardStep,
+ {
+ setStep: (_, { step }) => step,
+ nextStep: (state) =>
+ TRANSACTIONAL_EMAIL_WIZARD_STEPS[
+ Math.min(
+ TRANSACTIONAL_EMAIL_WIZARD_STEPS.indexOf(state) + 1,
+ TRANSACTIONAL_EMAIL_WIZARD_STEPS.length - 1
+ )
+ ],
+ previousStep: (state) =>
+ TRANSACTIONAL_EMAIL_WIZARD_STEPS[Math.max(TRANSACTIONAL_EMAIL_WIZARD_STEPS.indexOf(state) - 1, 0)],
+ resetWizard: () => 'name',
+ },
+ ],
+ draft: [
+ EMPTY_DRAFT,
+ {
+ updateDraft: (state, { patch }) => ({ ...state, ...patch }),
+ updateEmail: (state, { patch }) => ({ ...state, email: { ...state.email, ...patch } }),
+ resetWizard: () => EMPTY_DRAFT,
+ },
+ ],
+ // Variables added in the panel before the email uses them, so they can be inserted from the editor.
+ addedVariables: [
+ [] as string[],
+ {
+ addVariable: (state, { name }) => {
+ const cleaned = cleanVariableName(name)
+ return cleaned && !state.includes(cleaned) ? [...state, cleaned] : state
+ },
+ resetWizard: () => [],
+ },
+ ],
+ isCreating: [
+ false,
+ {
+ createTransactionalEmail: () => true,
+ createTransactionalEmailFinished: () => false,
+ },
+ ],
+ // Set once the template exists, so leaving the page no longer asks to discard it.
+ created: [
+ false,
+ {
+ createTransactionalEmailFinished: (_, { created }) => created,
+ resetWizard: () => false,
+ },
+ ],
+ }),
+ selectors({
+ senders: [
+ (s) => [s.integrations],
+ (integrations: IntegrationType[] | null): IntegrationType[] =>
+ // make_transactional only accepts a verified sender.
+ (integrations ?? []).filter(
+ (integration) => integration.kind === 'email' && integration.config?.verified === true
+ ),
+ ],
+ stepErrors: [
+ (s) => [s.draft, s.senders],
+ (
+ draft: TransactionalEmailDraft,
+ senders: IntegrationType[]
+ ): Record<TransactionalEmailWizardStep, string[]> => wizardStepErrors(draft, senders),
+ ],
+ currentStepErrors: [
+ (s) => [s.stepErrors, s.currentStep],
+ (stepErrors: Record<TransactionalEmailWizardStep, string[]>, currentStep: TransactionalEmailWizardStep) =>
+ stepErrors[currentStep],
+ ],
+ variables: [(s) => [s.draft], (draft: TransactionalEmailDraft): string[] => variablesInEmail(draft.email)],
+ // Everything the editor offers as a merge tag: what the email uses, plus what was added and not used yet.
+ panelVariables: [
+ (s) => [s.variables, s.addedVariables],
+ (variables: string[], addedVariables: string[]): string[] => [
+ ...variables,
+ ...addedVariables.filter((name) => !variables.includes(name)),
+ ],
+ ],
+ editorGlobals: [
+ (s) => [s.panelVariables],
+ (panelVariables: string[]): { variables: Record<string, string> } =>
+ transactionalEditorGlobals(panelVariables),
+ ],
+ hasChanges: [(s) => [s.draft], (draft: TransactionalEmailDraft): boolean => draft !== EMPTY_DRAFT],
+ }),
+ listeners(({ actions, values }) => ({
+ createTransactionalEmail: async () => {
+ const firstInvalidStep = TRANSACTIONAL_EMAIL_WIZARD_STEPS.find((step) => values.stepErrors[step].length > 0)
+ if (firstInvalidStep) {
+ actions.setStep(firstInvalidStep)
+ actions.createTransactionalEmailFinished(false)
+ return
+ }
+ const { name, description, sensitive, email } = values.draft
+ const teamId = String(values.currentTeamIdStrict)
+ let templateId: string
+ try {
+ const template = await messagingTemplatesCreate(teamId, {
+ name: name.trim(),
+ description,
+ sensitive,
+ content: { templating: 'liquid', email } as unknown as MessageTemplateContentApi,
+ })
+ templateId = template.id
+ } catch (error: any) {
+ lemonToast.error(`Couldn't create the email: ${error?.detail ?? 'unknown error'}. Try again.`)
+ actions.createTransactionalEmailFinished(false)
+ return
+ }
+ try {
+ await messagingTemplatesMakeTransactionalCreate(teamId, templateId, {})
+ posthog.capture('transactional email created', { variable_count: values.variables.length, sensitive })
+ lemonToast.success('Transactional email created')
+ } catch (error: any) {
+ // The template exists either way. Its API tab offers "Make transactional" to try again.
+ posthog.capture('transactional email creation failed', { step: 'make_transactional' })
+ lemonToast.error(
+ `Email saved, but it couldn't be made transactional: ${error?.detail ?? 'unknown error'}. Try again from its API tab.`
+ )
+ }
+ actions.createTransactionalEmailFinished(true)
+ router.actions.replace(urls.transactionalTemplate(templateId))
+ },
+ setStep: ({ step }) => {
+ posthog.capture('transactional email wizard step viewed', { step })
+ },
+ nextStep: () => {
+ posthog.capture('transactional email wizard step viewed', { step: values.currentStep })
+ },
+ })),
+ afterMount(({ actions }) => {
+ // Each visit to /transactional/new starts a new email.
+ actions.resetWizard()
+ posthog.capture('transactional email wizard step viewed', { step: 'name' })
+ }),
+ beforeUnload(({ values }) => ({
+ enabled: () => values.hasChanges && !values.created,
+ message: 'Leave this email?\nNothing is saved until you create it.',
+ })),
+])
diff --git a/products/workflows/manifest.tsx b/products/workflows/manifest.tsx
index 64bf7e640554..79daab2e242a 100644
--- a/products/workflows/manifest.tsx
+++ b/products/workflows/manifest.tsx
@@ -86,6 +86,7 @@ export const manifest: ProductManifest = {
'/transactional/suppression': ['Transactional', 'transactional'],
'/transactional/reputation': ['Transactional', 'transactional'],
'/transactional/settings': ['Transactional', 'transactional'],
+ '/transactional/new': ['Transactional', 'transactional'],
// A template opened from a section's Templates tab stays in that section.
'/transactional/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],
'/broadcasts/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],
@@ -107,6 +108,7 @@ export const manifest: ProductManifest = {
broadcast: (id: string): string => `/broadcasts/${id}`,
broadcastNew: (): string => '/broadcasts/new',
transactional: (tab?: MessagingNavTabKey): string => `/transactional${tab ? `/${tab}` : ''}`,
+ transactionalNew: (): string => '/transactional/new',
transactionalTemplate: (id: string): string => `/transactional/library/templates/${id}`,
broadcastsTemplate: (id: string): string => `/broadcasts/library/templates/${id}`,
},
diff --git a/services/mcp/src/tools/links/app-url-manifest.json b/services/mcp/src/tools/links/app-url-manifest.json
index e655f0928e70..ba17aee7f682 100644
--- a/services/mcp/src/tools/links/app-url-manifest.json
+++ b/services/mcp/src/tools/links/app-url-manifest.json
@@ -1849,6 +1849,11 @@
"params": [],
"scope": "project"
},
+ "transactionalNew": {
+ "template": "/transactional/new",
+ "params": [],
+ "scope": "project"
+ },
"transactionalTemplate": {
"template": "/transactional/library/templates/{id}",
"params": ["id"],
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json
index d05a4e0eba6c..d0a1b79d8947 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json
@@ -13,7 +13,7 @@
"type": "object"
},
"url": {
- "description": "A path template copied verbatim from the catalog below (e.g. `/persons/{uuid}`). Its `{placeholders}` are filled from `params`. These slugs come from PostHog's canonical route table, so they are always correct — never pass a path that is not in this list.\n\n/account-connected/{kind}\n/account/credential-review\n/account/social-connected\n/activity-logs\n/activity/{tab}\n/agentic/account-mismatch\n/agentic/authorize\n/ai\n/ai-enrichment\n/ai-evals/evaluations\n/ai-evals/evaluations/offline/datasets/{id}\n/ai-evals/evaluations/offline/experiments\n/ai-evals/evaluations/offline/experiments/{experimentId}\n/ai-evals/evaluations/offline/experiments?tab=datasets\n/ai-evals/evaluations/scorers\n/ai-evals/evaluations/scorers/{scorerId}\n/ai-evals/evaluations/scorers/{scorerId}/offline\n/ai-evals/evaluations/templates\n/ai-evals/evaluations/{id}\n/ai-evals/taggers\n/ai-evals/taggers/{id}\n/ai-observability/clusters\n/ai-observability/clusters/{runId}/{clusterId}\n/ai-observability/dashboard\n/ai-observability/errors\n/ai-observability/generations\n/ai-observability/playground\n/ai-observability/reviews\n/ai-observability/self-driving\n/ai-observability/sentiment\n/ai-observability/sessions\n/ai-observability/sessions/{id}\n/ai-observability/tools\n/ai-observability/traces\n/ai-observability/traces/{id}\n/ai-observability/users\n/ai/history\n/alerts\n/analytics\n/analytics/all\n/analytics/mine\n/analytics/product-analytics\n/analytics/spaces\n/application-observability\n/approvals/{id}\n/autoresearch\n/autoresearch/new\n/autoresearch/{id}\n/bi\n/bi/new\n/bi/{insightShortId}\n/billing/authorization_status\n/broadcasts\n/broadcasts/library/templates/{id}\n/broadcasts/new\n/broadcasts/{id}\n/business-knowledge\n/business-knowledge/playground\n/business-knowledge/settings\n/business-knowledge/{id}\n/canvas\n/canvases\n/canvases/new\n/canvases/{id}\n/cli/authorize\n/cli/live\n/code-review\n/code/canvas/{channelId}/{dashboardId}\n/code/channel/{channelId}\n/code/loop/{loopId}\n/code/task/{taskId}\n/cohorts\n/cohorts/{id}\n/cohorts/{id}/calculation-history\n/connect/vercel/link\n/coupons/{campaign}\n/create-organization\n/cross-project-dashboards\n/cross-project-dashboards/{id}\n/customer_analytics\n/customer_analytics/accounts\n/customer_analytics/accounts/by-external-id/{externalId}\n/customer_analytics/accounts/{accountId}\n/customer_analytics/announcements\n/customer_analytics/configuration\n/customer_analytics/dashboard\n/customer_analytics/feature-requests\n/customer_analytics/feed\n/customer_analytics/journeys\n/customer_analytics/journeys/new\n/customer_analytics/journeys/templates\n/customer_analytics/journeys/{id}/edit\n/customer_analytics/notes\n/customer_analytics/tasks\n/dashboard\n/dashboard/templates/{templateId}/copy-to-project\n/dashboard/{id}\n/dashboard/{id}/sharing\n/dashboard/{id}/subscriptions\n/dashboard/{id}/subscriptions/{subscriptionId}\n/dashboard/{id}/tiles/{tileId}\n/data-catalog\n/data-catalog/metrics/{name}\n/data-catalog/new-metric\n/data-management/actions\n/data-management/actions/new\n/data-management/actions/new/\n/data-management/actions/{id}\n/data-management/annotations\n/data-management/annotations/{id}\n/data-management/core-events\n/data-management/database\n/data-management/destinations\n/data-management/event-filtering\n/data-management/events\n/data-management/events/{id}\n/data-management/events/{id}/edit\n/data-management/history\n/data-management/ingestion-warnings\n/data-management/ingestion-warnings-v2\n/data-management/managed-viewsets\n/data-management/materialized-columns\n/data-management/properties\n/data-management/properties/{id}\n/data-management/properties/{id}/edit\n/data-management/revenue\n/data-management/schema\n/data-management/sources\n/data-management/sources/{id}/schemas\n/data-management/sources/{sourceId}/schemas/{schemaId}\n/data-management/transformations\n/data-management/variables\n/data-management/variables/{id}\n/data-management/variables/{id}/edit\n/data-management/warehouse-destinations\n/data-management/warehouse-properties\n/data-ops\n/data-warehouse/connect\n/data-warehouse/new-source\n/debug\n/debug/hog\n/debug/precompute\n/early_access_features\n/early_access_features/{id}\n/embedded/{token}\n/endpoints\n/endpoints/{name}\n/engineering-analytics/authors\n/engineering-analytics/authors/{handle}\n/engineering-analytics/deploys\n/engineering-analytics/overview\n/engineering-analytics/pull-requests\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/runs/{runId}\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/workflows/{workflowName}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}/ci-explorer\n/engineering-analytics/teams\n/engineering-analytics/teams/{ownerTeam}\n/engineering-analytics/tests\n/engineering-analytics/workflows\n/error-tracking\n/error-tracking/alerts/new/{templateId}\n/error-tracking/alerts/{id}\n/error-tracking/fingerprint/{fingerprint}\n/error-tracking/{id}\n/etl\n/events/{id}/{timestamp}\n/experiments\n/experiments/shared-metrics\n/experiments/shared-metrics/{id}\n/experiments/staff\n/experiments/{id}\n/exports\n/feature-flags\n/feature-flags/new\n/feature-flags/staff\n/feature-flags/staff/cohorts\n/feature-flags/templates\n/feature-flags/{id}\n/files\n/functions/new/{templateId}\n/functions/{id}\n/games/368hedgehogs\n/games/flappyhog\n/games/shipit\n/groups/{groupTypeIndex}\n/groups/{groupTypeIndex}/new\n/groups/{groupTypeIndex}/{groupKey}\n/health\n/health/alerts\n/health/pipeline-status\n/health/sdk-health\n/health/{category}\n/heatmaps\n/heatmaps/new\n/heatmaps/recording\n/heatmaps/{id}\n/home\n/identity-matching\n/inbox\n/inbox/reports/triage\n/inbox/scout-trials\n/inbox/scouts/findings\n/inbox/scouts/runs\n/inbox/scouts/scratchpad\n/inbox/scouts/{skillName}\n/inbox/{tab}/{reportId}\n/insights\n/insights/new\n/insights/quick-start\n/insights/{id}\n/insights/{id}/edit\n/insights/{id}/sharing\n/insights/{id}/subscriptions\n/insights/{id}/subscriptions/{subscriptionId}\n/insights/{insightShortId}/alerts\n/instance/async_migrations\n/instance/async_migrations/future\n/instance/async_migrations/settings\n/instance/dead_letter_queue\n/instance/kafka_inspector\n/instance/metrics\n/instance/settings\n/instance/staff_users\n/instance/status\n/integrations/stripe/confirm-install\n/integrations/vercel/link-error\n/integrations/{kind}/callback\n/integrations/{slug}\n/legal\n/legal/new/{type}\n/login\n/login/2fa\n/login/2fa_setup\n/logs\n/logs/alerts/{alertId}/notifications/{hogFunctionId}\n/logs/alerts/{id}\n/logs/drop-rules/new\n/logs/drop-rules/{id}\n/logs/retention-rules/new\n/logs/retention-rules/{id}\n/managed_migrations\n/managed_migrations/new\n/marketing\n/mcp-analytics\n/mcp-analytics/activity\n/mcp-analytics/dashboard\n/mcp-analytics/intent-clustering\n/mcp-analytics/missing-capabilities\n/mcp-analytics/notifications\n/mcp-analytics/sessions\n/mcp-analytics/tool-quality\n/mcp-analytics/tool-quality/{toolName}\n/mcp-registry\n/mcp-servers\n/mcp-servers/agent/{id}\n/mcp-servers/member/{id}\n/mcp-servers/server/{id}\n/mcp-servers/{tab}\n/metrics\n/metrics/dashboard-review\n/models\n/models/{id}\n/move-to-cloud\n/my-tickets\n/notebooks\n/notebooks/widgets/{widgetId}\n/notebooks/{shortId}\n/oauth/authorize\n/onboarding\n/onboarding/simple\n/organization-deactivated\n/organization-pending-deletion\n/organization/billing\n/organization/billing/overview\n/organization/billing/real-time-usage\n/organization/confirm-creation\n/organization/create-project\n/organization/legal\n/organization/startups\n/person/{id}\n/persons\n/persons/{uuid}\n/pipeline/batch-exports/new/{service}\n/pipeline/batch-exports/{id}\n/pipeline/new/\n/pipeline/plugins/{id}\n/platform-alerts\n/platform-alerts/{id}\n/preflight\n/product_tours\n/product_tours/{id}\n/project-pending-deletion\n/prompt-management/prompts\n/prompt-management/prompts/{name}\n/pulse\n/replay-vision\n/replay-vision/new/goal\n/replay-vision/observations/{observationId}\n/replay-vision/{id}/budget\n/replay-vision/{id}/configure\n/replay-vision/{id}/details\n/replay-vision/{id}/goal\n/replay-vision/{id}/overview\n/replay-vision/{id}/triggers\n/replay/file-playback\n/replay/home\n/replay/kiosk\n/replay/playlists/{id}\n/replay/settings\n/replay/{id}\n/reset\n/reset/{userUuid}/{token}\n/reset_2fa/{userUuid}/{token}\n/resource-transfer/{resourceKind}/{resourceId}\n/sessions/{id}\n/settings/environment-approvals\n/settings/organization-authentication/{feature}/{configId}\n/settings/project\n/settings/user-feature-previews\n/shared/{token}\n/shared_dashboard/{shareToken}\n/signup\n/signup/{id}\n/site/{url}\n/skills\n/skills/community\n/skills/{categoryTab}\n/skills/{name}\n/slack-task-context\n/spaces\n/spaces/new\n/spaces/{id}\n/spaces/{id}/canvases\n/spaces/{id}/new\n/spaces/{id}/settings\n/sql\n/stamphog\n/stamphog/digests\n/stamphog/install/callback\n/stamphog/runs\n/startups\n/streamlit-apps\n/streamlit-apps/new\n/streamlit-apps/{id}\n/streamlit-apps/{id}/edit\n/subscriptions\n/subscriptions/new\n/subscriptions/{id}\n/subscriptions/{id}/edit\n/support\n/support/settings\n/support/tickets\n/support/tickets/{ticketId}\n/surveys\n/surveys/form/new\n/surveys/guided/new\n/surveys/{id}\n/tasks\n/tasks/new\n/tasks/{taskId}\n/terminal\n/themes/custom-css\n/toolbar\n/tools\n/tracing\n/tracing/retention-rules/new\n/tracing/retention-rules/{id}\n/transactional\n/transactional/library/templates/{id}\n/unsubscribe\n/uptime-monitoring\n/verify_email\n/visual-review\n/visual-review/repos/{repoOwner}/{repoName}/flakiness\n/visual-review/repos/{repoOwner}/{repoName}/runs\n/visual-review/repos/{repoOwner}/{repoName}/runs/{runId}\n/visual-review/repos/{repoOwner}/{repoName}/snapshots\n/visual-review/repos/{repoOwner}/{repoName}/{runType}/snapshots/{identifier}\n/visual-review/runs/{runId}\n/visual-review/settings\n/web\n/web-scripts\n/web-scripts/new\n/web/agents\n/web/bots\n/web/content-autopilot\n/web/health\n/web/live\n/web/marketing\n/web/page-performance\n/web/page-reports\n/web/recap\n/web/session-attribution-explorer\n/web/web-vitals\n/welcome\n/wizard/runs\n/workflows\n/workflows/channels/email/{id}\n/workflows/library/messages/{id}\n/workflows/library/templates/new\n/workflows/library/templates/{id}\n/workflows/new/workflow\n/workflows/{id}/{tab}",
+ "description": "A path template copied verbatim from the catalog below (e.g. `/persons/{uuid}`). Its `{placeholders}` are filled from `params`. These slugs come from PostHog's canonical route table, so they are always correct — never pass a path that is not in this list.\n\n/account-connected/{kind}\n/account/credential-review\n/account/social-connected\n/activity-logs\n/activity/{tab}\n/agentic/account-mismatch\n/agentic/authorize\n/ai\n/ai-enrichment\n/ai-evals/evaluations\n/ai-evals/evaluations/offline/datasets/{id}\n/ai-evals/evaluations/offline/experiments\n/ai-evals/evaluations/offline/experiments/{experimentId}\n/ai-evals/evaluations/offline/experiments?tab=datasets\n/ai-evals/evaluations/scorers\n/ai-evals/evaluations/scorers/{scorerId}\n/ai-evals/evaluations/scorers/{scorerId}/offline\n/ai-evals/evaluations/templates\n/ai-evals/evaluations/{id}\n/ai-evals/taggers\n/ai-evals/taggers/{id}\n/ai-observability/clusters\n/ai-observability/clusters/{runId}/{clusterId}\n/ai-observability/dashboard\n/ai-observability/errors\n/ai-observability/generations\n/ai-observability/playground\n/ai-observability/reviews\n/ai-observability/self-driving\n/ai-observability/sentiment\n/ai-observability/sessions\n/ai-observability/sessions/{id}\n/ai-observability/tools\n/ai-observability/traces\n/ai-observability/traces/{id}\n/ai-observability/users\n/ai/history\n/alerts\n/analytics\n/analytics/all\n/analytics/mine\n/analytics/product-analytics\n/analytics/spaces\n/application-observability\n/approvals/{id}\n/autoresearch\n/autoresearch/new\n/autoresearch/{id}\n/bi\n/bi/new\n/bi/{insightShortId}\n/billing/authorization_status\n/broadcasts\n/broadcasts/library/templates/{id}\n/broadcasts/new\n/broadcasts/{id}\n/business-knowledge\n/business-knowledge/playground\n/business-knowledge/settings\n/business-knowledge/{id}\n/canvas\n/canvases\n/canvases/new\n/canvases/{id}\n/cli/authorize\n/cli/live\n/code-review\n/code/canvas/{channelId}/{dashboardId}\n/code/channel/{channelId}\n/code/loop/{loopId}\n/code/task/{taskId}\n/cohorts\n/cohorts/{id}\n/cohorts/{id}/calculation-history\n/connect/vercel/link\n/coupons/{campaign}\n/create-organization\n/cross-project-dashboards\n/cross-project-dashboards/{id}\n/customer_analytics\n/customer_analytics/accounts\n/customer_analytics/accounts/by-external-id/{externalId}\n/customer_analytics/accounts/{accountId}\n/customer_analytics/announcements\n/customer_analytics/configuration\n/customer_analytics/dashboard\n/customer_analytics/feature-requests\n/customer_analytics/feed\n/customer_analytics/journeys\n/customer_analytics/journeys/new\n/customer_analytics/journeys/templates\n/customer_analytics/journeys/{id}/edit\n/customer_analytics/notes\n/customer_analytics/tasks\n/dashboard\n/dashboard/templates/{templateId}/copy-to-project\n/dashboard/{id}\n/dashboard/{id}/sharing\n/dashboard/{id}/subscriptions\n/dashboard/{id}/subscriptions/{subscriptionId}\n/dashboard/{id}/tiles/{tileId}\n/data-catalog\n/data-catalog/metrics/{name}\n/data-catalog/new-metric\n/data-management/actions\n/data-management/actions/new\n/data-management/actions/new/\n/data-management/actions/{id}\n/data-management/annotations\n/data-management/annotations/{id}\n/data-management/core-events\n/data-management/database\n/data-management/destinations\n/data-management/event-filtering\n/data-management/events\n/data-management/events/{id}\n/data-management/events/{id}/edit\n/data-management/history\n/data-management/ingestion-warnings\n/data-management/ingestion-warnings-v2\n/data-management/managed-viewsets\n/data-management/materialized-columns\n/data-management/properties\n/data-management/properties/{id}\n/data-management/properties/{id}/edit\n/data-management/revenue\n/data-management/schema\n/data-management/sources\n/data-management/sources/{id}/schemas\n/data-management/sources/{sourceId}/schemas/{schemaId}\n/data-management/transformations\n/data-management/variables\n/data-management/variables/{id}\n/data-management/variables/{id}/edit\n/data-management/warehouse-destinations\n/data-management/warehouse-properties\n/data-ops\n/data-warehouse/connect\n/data-warehouse/new-source\n/debug\n/debug/hog\n/debug/precompute\n/early_access_features\n/early_access_features/{id}\n/embedded/{token}\n/endpoints\n/endpoints/{name}\n/engineering-analytics/authors\n/engineering-analytics/authors/{handle}\n/engineering-analytics/deploys\n/engineering-analytics/overview\n/engineering-analytics/pull-requests\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/runs/{runId}\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/workflows/{workflowName}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}/ci-explorer\n/engineering-analytics/teams\n/engineering-analytics/teams/{ownerTeam}\n/engineering-analytics/tests\n/engineering-analytics/workflows\n/error-tracking\n/error-tracking/alerts/new/{templateId}\n/error-tracking/alerts/{id}\n/error-tracking/fingerprint/{fingerprint}\n/error-tracking/{id}\n/etl\n/events/{id}/{timestamp}\n/experiments\n/experiments/shared-metrics\n/experiments/shared-metrics/{id}\n/experiments/staff\n/experiments/{id}\n/exports\n/feature-flags\n/feature-flags/new\n/feature-flags/staff\n/feature-flags/staff/cohorts\n/feature-flags/templates\n/feature-flags/{id}\n/files\n/functions/new/{templateId}\n/functions/{id}\n/games/368hedgehogs\n/games/flappyhog\n/games/shipit\n/groups/{groupTypeIndex}\n/groups/{groupTypeIndex}/new\n/groups/{groupTypeIndex}/{groupKey}\n/health\n/health/alerts\n/health/pipeline-status\n/health/sdk-health\n/health/{category}\n/heatmaps\n/heatmaps/new\n/heatmaps/recording\n/heatmaps/{id}\n/home\n/identity-matching\n/inbox\n/inbox/reports/triage\n/inbox/scout-trials\n/inbox/scouts/findings\n/inbox/scouts/runs\n/inbox/scouts/scratchpad\n/inbox/scouts/{skillName}\n/inbox/{tab}/{reportId}\n/insights\n/insights/new\n/insights/quick-start\n/insights/{id}\n/insights/{id}/edit\n/insights/{id}/sharing\n/insights/{id}/subscriptions\n/insights/{id}/subscriptions/{subscriptionId}\n/insights/{insightShortId}/alerts\n/instance/async_migrations\n/instance/async_migrations/future\n/instance/async_migrations/settings\n/instance/dead_letter_queue\n/instance/kafka_inspector\n/instance/metrics\n/instance/settings\n/instance/staff_users\n/instance/status\n/integrations/stripe/confirm-install\n/integrations/vercel/link-error\n/integrations/{kind}/callback\n/integrations/{slug}\n/legal\n/legal/new/{type}\n/login\n/login/2fa\n/login/2fa_setup\n/logs\n/logs/alerts/{alertId}/notifications/{hogFunctionId}\n/logs/alerts/{id}\n/logs/drop-rules/new\n/logs/drop-rules/{id}\n/logs/retention-rules/new\n/logs/retention-rules/{id}\n/managed_migrations\n/managed_migrations/new\n/marketing\n/mcp-analytics\n/mcp-analytics/activity\n/mcp-analytics/dashboard\n/mcp-analytics/intent-clustering\n/mcp-analytics/missing-capabilities\n/mcp-analytics/notifications\n/mcp-analytics/sessions\n/mcp-analytics/tool-quality\n/mcp-analytics/tool-quality/{toolName}\n/mcp-registry\n/mcp-servers\n/mcp-servers/agent/{id}\n/mcp-servers/member/{id}\n/mcp-servers/server/{id}\n/mcp-servers/{tab}\n/metrics\n/metrics/dashboard-review\n/models\n/models/{id}\n/move-to-cloud\n/my-tickets\n/notebooks\n/notebooks/widgets/{widgetId}\n/notebooks/{shortId}\n/oauth/authorize\n/onboarding\n/onboarding/simple\n/organization-deactivated\n/organization-pending-deletion\n/organization/billing\n/organization/billing/overview\n/organization/billing/real-time-usage\n/organization/confirm-creation\n/organization/create-project\n/organization/legal\n/organization/startups\n/person/{id}\n/persons\n/persons/{uuid}\n/pipeline/batch-exports/new/{service}\n/pipeline/batch-exports/{id}\n/pipeline/new/\n/pipeline/plugins/{id}\n/platform-alerts\n/platform-alerts/{id}\n/preflight\n/product_tours\n/product_tours/{id}\n/project-pending-deletion\n/prompt-management/prompts\n/prompt-management/prompts/{name}\n/pulse\n/replay-vision\n/replay-vision/new/goal\n/replay-vision/observations/{observationId}\n/replay-vision/{id}/budget\n/replay-vision/{id}/configure\n/replay-vision/{id}/details\n/replay-vision/{id}/goal\n/replay-vision/{id}/overview\n/replay-vision/{id}/triggers\n/replay/file-playback\n/replay/home\n/replay/kiosk\n/replay/playlists/{id}\n/replay/settings\n/replay/{id}\n/reset\n/reset/{userUuid}/{token}\n/reset_2fa/{userUuid}/{token}\n/resource-transfer/{resourceKind}/{resourceId}\n/sessions/{id}\n/settings/environment-approvals\n/settings/organization-authentication/{feature}/{configId}\n/settings/project\n/settings/user-feature-previews\n/shared/{token}\n/shared_dashboard/{shareToken}\n/signup\n/signup/{id}\n/site/{url}\n/skills\n/skills/community\n/skills/{categoryTab}\n/skills/{name}\n/slack-task-context\n/spaces\n/spaces/new\n/spaces/{id}\n/spaces/{id}/canvases\n/spaces/{id}/new\n/spaces/{id}/settings\n/sql\n/stamphog\n/stamphog/digests\n/stamphog/install/callback\n/stamphog/runs\n/startups\n/streamlit-apps\n/streamlit-apps/new\n/streamlit-apps/{id}\n/streamlit-apps/{id}/edit\n/subscriptions\n/subscriptions/new\n/subscriptions/{id}\n/subscriptions/{id}/edit\n/support\n/support/settings\n/support/tickets\n/support/tickets/{ticketId}\n/surveys\n/surveys/form/new\n/surveys/guided/new\n/surveys/{id}\n/tasks\n/tasks/new\n/tasks/{taskId}\n/terminal\n/themes/custom-css\n/toolbar\n/tools\n/tracing\n/tracing/retention-rules/new\n/tracing/retention-rules/{id}\n/transactional\n/transactional/library/templates/{id}\n/transactional/new\n/unsubscribe\n/uptime-monitoring\n/verify_email\n/visual-review\n/visual-review/repos/{repoOwner}/{repoName}/flakiness\n/visual-review/repos/{repoOwner}/{repoName}/runs\n/visual-review/repos/{repoOwner}/{repoName}/runs/{runId}\n/visual-review/repos/{repoOwner}/{repoName}/snapshots\n/visual-review/repos/{repoOwner}/{repoName}/{runType}/snapshots/{identifier}\n/visual-review/runs/{runId}\n/visual-review/settings\n/web\n/web-scripts\n/web-scripts/new\n/web/agents\n/web/bots\n/web/content-autopilot\n/web/health\n/web/live\n/web/marketing\n/web/page-performance\n/web/page-reports\n/web/recap\n/web/session-attribution-explorer\n/web/web-vitals\n/welcome\n/wizard/runs\n/workflows\n/workflows/channels/email/{id}\n/workflows/library/messages/{id}\n/workflows/library/templates/new\n/workflows/library/templates/{id}\n/workflows/new/workflow\n/workflows/{id}/{tab}",
"type": "string"
}
},