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 messaging setup status tool for MCP agents (#118493)

Meikel Ratzb37f205c3f80
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 8b85297a6bc2..46e60fe15531 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -6406,6 +6406,10 @@ snapshots:
hash: v1.k794b7964.4cbfe20c626f0f7912dbd47b41a152c9c30f92d12a3f599476fb10043d7f7e70.9NI9FaMch59lt8xO3Xhp9ruHKLyDcvupNp20dZrR8_Y
mcp-apps-workflows--list--light:
hash: v1.k794b7964.05ea602d6d9345842a6335a7a5dfd2708b35e7e84582dedab2d4f75daab793c5.R8GtNbF9pB7JrXdEIBpk8XsgLhKJuKMA1UB9qr0Tzbs
+ mcp-apps-workflows--setup-status-done--light:
+ hash: v1.k794b7964.2ecc52194af0bc94be9841afc57128da763075064497948ecd81e2114695bc81.9CDthZ77iyEZATCkKdP_y8cU2nOu9KDWR_uKm-sBvBk
+ mcp-apps-workflows--setup-status-in-progress--light:
+ hash: v1.k794b7964.7533676e7b7719945434d7ce5ca31b986a2a494cc64643920771d453bb827856.E8hkjoO5HR-nJLQP713GkZugnSbXE46dzlhJLSg4MxM
metrics-group-by--default--dark:
hash: v1.k794b7964.ce83d5c6298b08ac62a7eeb1365881f3eaad9e77a2ffc762a8683bb5360cf49f.ZybY7nObSqgkgX4qZO0IbHSimFba2tRWMI3lKApT73o
metrics-group-by--default--light:
diff --git a/products/workflows/backend/facade/contracts.py b/products/workflows/backend/facade/contracts.py
index c078fae66c57..bc82e1f5947b 100644
--- a/products/workflows/backend/facade/contracts.py
+++ b/products/workflows/backend/facade/contracts.py
@@ -13,6 +13,7 @@ from products.workflows.backend.facade.enums import (
HogFlowScheduleStatus,
HogFlowTemplateExitCondition,
HogFlowTemplateScope,
+ SetupStepKey,
WorkflowProposalStatus,
)
@@ -810,3 +811,11 @@ class EmailDraft:
text: str
generated_by: EmailDraftOrigin
fallback_reason: EmailDraftFallbackReason | None = None
+
+
+@frozen
+class SetupStep:
+ """One messaging setup step and whether the project has done it."""
+
+ key: SetupStepKey
+ done: bool
diff --git a/products/workflows/backend/facade/enums.py b/products/workflows/backend/facade/enums.py
index eaa447ae190c..12ec8b8109a7 100644
--- a/products/workflows/backend/facade/enums.py
+++ b/products/workflows/backend/facade/enums.py
@@ -116,3 +116,13 @@ class EmailDraftFallbackReason(LabeledStrEnum):
TIMEOUT = "timeout", "The model took too long"
MODEL_ERROR = "model_error", "The model call failed"
INVALID_OUTPUT = "invalid_output", "The model returned an unusable draft"
+
+
+# pinned: step keys in the setup status API - renaming breaks agents that read them
+class SetupStepKey(LabeledStrEnum):
+ CHANNEL = "channel", "Channel"
+ DOMAIN = "domain", "Domain"
+ OPT_OUTS = "opt-outs", "Opt-outs"
+ SENDING_RULES = "sending-rules", "Sending rules"
+ EMAIL_TEMPLATE = "email-template", "Email template"
+ FIRST_WORKFLOW = "first-workflow", "First workflow"
diff --git a/products/workflows/backend/facade/setup_status.py b/products/workflows/backend/facade/setup_status.py
new file mode 100644
index 000000000000..613814057609
--- /dev/null
+++ b/products/workflows/backend/facade/setup_status.py
@@ -0,0 +1,5 @@
+"""Which messaging setup steps a project has done."""
+
+from products.workflows.backend.services.setup_status import email_sending_paused, get_setup_steps
+
+__all__ = ["email_sending_paused", "get_setup_steps"]
diff --git a/products/workflows/backend/presentation/views/workflow_setup.py b/products/workflows/backend/presentation/views/workflow_setup.py
new file mode 100644
index 000000000000..863806d0ef68
--- /dev/null
+++ b/products/workflows/backend/presentation/views/workflow_setup.py
@@ -0,0 +1,148 @@
+from typing import Any
+
+import posthoganalytics
+from drf_spectacular.utils import extend_schema
+from rest_framework import serializers, viewsets
+from rest_framework.decorators import action
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from posthog.api.routing import TeamAndOrgViewSetMixin
+from posthog.dataclasses import frozen
+from posthog.models import User
+from posthog.utils import absolute_uri
+
+from products.workflows.backend.facade.contracts import SetupStep
+from products.workflows.backend.facade.enums import SetupStepKey
+from products.workflows.backend.facade.setup_status import email_sending_paused, get_setup_steps
+from products.workflows.backend.presentation.views.workflow_data_suggestions import (
+ FEATURE_FLAG_KEY as DATA_SUGGESTIONS_FLAG_KEY,
+)
+
+# The steps an email can't send without. The rest make sending safer or faster but never block it.
+_REQUIRED_TO_SEND = (SetupStepKey.CHANNEL, SetupStepKey.DOMAIN)
+
+
+@frozen
+class _StepCopy:
+ title: str
+ next_step: str
+ path: str
+
+
+_STEP_COPY: dict[SetupStepKey, _StepCopy] = {
+ SetupStepKey.CHANNEL: _StepCopy(
+ title="Connect an email channel",
+ next_step="Add the address emails send from. The person adds it in the app, since it needs a domain they control.",
+ path="/workflows/onboarding?path=messaging&step=channel",
+ ),
+ SetupStepKey.DOMAIN: _StepCopy(
+ title="Verify your sending domain",
+ next_step="Add the DNS records shown in the app at the domain's DNS provider, then verify. Email sends only from a "
+ "verified domain.",
+ path="/workflows/onboarding?path=messaging&step=domain",
+ ),
+ SetupStepKey.OPT_OUTS: _StepCopy(
+ title="Add opt-out categories",
+ next_step="Let people unsubscribe from one kind of message, such as product updates, and keep the rest.",
+ path="/workflows/onboarding?path=messaging&step=opt-outs",
+ ),
+ SetupStepKey.SENDING_RULES: _StepCopy(
+ title="Set a frequency cap",
+ next_step="Limit how many marketing emails one person gets across all workflows. The recommended cap is 1 email "
+ "every 2 days.",
+ path="/settings/environment-workflows#workflows-frequency-cap",
+ ),
+ SetupStepKey.EMAIL_TEMPLATE: _StepCopy(
+ title="Design your first email",
+ next_step="Save a reusable email template in the library.",
+ path="/workflows/library",
+ ),
+ SetupStepKey.FIRST_WORKFLOW: _StepCopy(
+ title="Create your first workflow",
+ next_step="Build a workflow that sends email, SMS or push.",
+ path="/workflows/onboarding?path=messaging&step=journey",
+ ),
+}
+
+
+class WorkflowSetupStepSerializer(serializers.Serializer):
+ key = serializers.ChoiceField(
+ choices=SetupStepKey.choices,
+ help_text="Which setup step this is. The steps come in the order the setup wizard asks for them.",
+ )
+ done = serializers.BooleanField(help_text="Whether the project has done this step.")
+ title = serializers.CharField(help_text="The step's name, as the app shows it.")
+ next_step = serializers.CharField(help_text="What the person does to finish the step.")
+ app_url = serializers.CharField(help_text="Link to the place in the app where the person does this step.")
+
+
+class WorkflowSetupStatusSerializer(serializers.Serializer):
+ steps = WorkflowSetupStepSerializer(many=True, help_text="Every messaging setup step, in order.")
+ ready_to_send_email = serializers.BooleanField(
+ help_text="Whether an email workflow can send. Needs a connected email channel on a verified domain, and "
+ "email sending must not be paused for the project. SMS and push use their own channels, and automations "
+ "that only post to tools like Slack or call webhooks need none of these steps."
+ )
+ email_sending_paused = serializers.BooleanField(
+ help_text="Whether email sending is paused for the project, so no email sends even with a verified "
+ "domain. The person contacts PostHog support to resume it."
+ )
+ next_open_step = serializers.ChoiceField(
+ choices=SetupStepKey.choices,
+ allow_null=True,
+ help_text="The first step that is not done, or null when every step is done.",
+ )
+ data_suggestions_available = serializers.BooleanField(
+ help_text="Whether workflows-data-suggestions-list can suggest workflows from this project's events."
+ )
+
+
+class WorkflowSetupViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
+ """Whether a project is set up to send messages from workflows."""
+
+ scope_object = "hog_flow"
+ # The status reads the whole project, so access to a single workflow is not enough.
+ requires_resource_level_access = True
+ scope_object_read_actions = ["status"]
+
+ @extend_schema(operation_id="workflow_setup_status", responses={200: WorkflowSetupStatusSerializer})
+ @action(detail=False, methods=["get"])
+ def status(self, request: Request, **kwargs: Any) -> Response:
+ steps = get_setup_steps(self.team)
+ done = {step.key: step.done for step in steps}
+ paused = email_sending_paused(self.team)
+ return Response(
+ WorkflowSetupStatusSerializer(
+ {
+ "steps": [self._step(step) for step in steps],
+ "ready_to_send_email": all(done[key] for key in _REQUIRED_TO_SEND) and not paused,
+ "email_sending_paused": paused,
+ "next_open_step": next((step.key for step in steps if not step.done), None),
+ "data_suggestions_available": self._data_suggestions_available(request),
+ }
+ ).data
+ )
+
+ def _step(self, step: SetupStep) -> dict[str, Any]:
+ copy = _STEP_COPY[step.key]
+ return {
+ "key": step.key,
+ "done": step.done,
+ "title": copy.title,
+ "next_step": copy.next_step,
+ "app_url": absolute_uri(f"/project/{self.team.id}{copy.path}"),
+ }
+
+ def _data_suggestions_available(self, request: Request) -> bool:
+ user = request.user
+ if not isinstance(user, User) or not user.distinct_id:
+ return False
+ return bool(
+ posthoganalytics.feature_enabled(
+ DATA_SUGGESTIONS_FLAG_KEY,
+ user.distinct_id,
+ groups={"organization": str(self.organization.id)},
+ group_properties={"organization": {"id": str(self.organization.id)}},
+ )
+ )
diff --git a/products/workflows/backend/routes.py b/products/workflows/backend/routes.py
index 4cc248e72092..1de904dd6439 100644
--- a/products/workflows/backend/routes.py
+++ b/products/workflows/backend/routes.py
@@ -13,6 +13,7 @@ from products.workflows.backend.presentation.views import (
workflow_classifications,
workflow_data_suggestions,
workflow_scout_runs,
+ workflow_setup,
workflow_tasks,
workflow_vision_requests,
)
@@ -38,6 +39,9 @@ def register_routes(routers: RouterRegistry) -> None:
"project_workflow_data_suggestions",
["team_id"],
)
+ routers.projects.register(
+ r"workflow_setup", workflow_setup.WorkflowSetupViewSet, "project_workflow_setup", ["team_id"]
+ )
routers.projects.register(
r"workflow_scout_runs",
workflow_scout_runs.WorkflowScoutRunViewSet,
diff --git a/products/workflows/backend/services/setup_status.py b/products/workflows/backend/services/setup_status.py
new file mode 100644
index 000000000000..64200b08626e
--- /dev/null
+++ b/products/workflows/backend/services/setup_status.py
@@ -0,0 +1,46 @@
+"""Which messaging setup steps a project has done, in the order the setup wizard asks for them."""
+
+from posthog.models import Team
+from posthog.models.integration import Integration
+
+from products.messaging.backend.facade.api import list_email_templates
+from products.messaging.backend.facade.categories import list_categories
+from products.workflows.backend.facade.contracts import SetupStep
+from products.workflows.backend.facade.enums import SetupStepKey
+from products.workflows.backend.models import HogFlow
+from products.workflows.backend.models.team_workflows_config import TeamWorkflowsConfig
+from products.workflows.backend.services.data_suggestions.team_context import has_verified_email_sender
+from products.workflows.backend.services.hog_flow_reads import workflow_type_q
+
+
+def _frequency_cap_set(team: Team) -> bool:
+ # Read without get_or_create, so checking the status never writes a config row.
+ config = TeamWorkflowsConfig.objects.filter(team_id=team.id).first()
+ return (
+ config is not None
+ and config.marketing_frequency_cap_max_messages is not None
+ and config.marketing_frequency_cap_window_days is not None
+ )
+
+
+def email_sending_paused(team: Team) -> bool:
+ # The CDP email service refuses every send in either case, so a verified domain alone is not enough.
+ config = TeamWorkflowsConfig.objects.filter(team_id=team.id).first()
+ return config is not None and (
+ config.email_sending_suspended_at is not None or config.ses_tenant_sending_status == "DISABLED"
+ )
+
+
+def get_setup_steps(team: Team) -> tuple[SetupStep, ...]:
+ done = {
+ SetupStepKey.CHANNEL: Integration.objects.filter(team_id=team.id, kind="email").exists(),
+ SetupStepKey.DOMAIN: has_verified_email_sender(team),
+ SetupStepKey.OPT_OUTS: len(list_categories(team.id)) > 0,
+ SetupStepKey.SENDING_RULES: _frequency_cap_set(team),
+ SetupStepKey.EMAIL_TEMPLATE: len(list_email_templates(team.id, limit=1)) > 0,
+ SetupStepKey.FIRST_WORKFLOW: HogFlow.objects.filter(team_id=team.id)
+ .exclude(status=HogFlow.State.ARCHIVED)
+ .filter(workflow_type_q({"messaging"}))
+ .exists(),
+ }
+ return tuple(SetupStep(key=key, done=done[key]) for key in SetupStepKey)
diff --git a/products/workflows/backend/test/test_workflow_setup_status.py b/products/workflows/backend/test/test_workflow_setup_status.py
new file mode 100644
index 000000000000..9ed6fe33ccf3
--- /dev/null
+++ b/products/workflows/backend/test/test_workflow_setup_status.py
@@ -0,0 +1,117 @@
+from posthog.test.base import APIBaseTest
+from unittest.mock import patch
+
+from django.utils import timezone
+
+from parameterized import parameterized
+from rest_framework import status
+
+from posthog.models.integration import Integration
+
+from products.messaging.backend.facade.testing import create_message_category_for_test, create_message_template_for_test
+from products.workflows.backend.models import HogFlow
+from products.workflows.backend.models.team_workflows_config import TeamWorkflowsConfig
+
+
+class TestWorkflowSetupStatusAPI(APIBaseTest):
+ def setUp(self) -> None:
+ super().setUp()
+ flag = patch(
+ "products.workflows.backend.presentation.views.workflow_setup.posthoganalytics.feature_enabled",
+ return_value=False,
+ )
+ flag.start()
+ self.addCleanup(flag.stop)
+
+ def _status(self) -> dict:
+ response = self.client.get(f"/api/projects/{self.team.id}/workflow_setup/status/")
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ return response.json()
+
+ def _done(self, body: dict) -> dict[str, bool]:
+ return {step["key"]: step["done"] for step in body["steps"]}
+
+ def _add_email_channel(self, verified: bool) -> None:
+ Integration.objects.create(
+ team=self.team,
+ kind="email",
+ integration_id="[email protected]",
+ config={"email": "[email protected]", "verified": verified},
+ )
+
+ def _add_workflow(self, *, action_type: str, status: str = "draft", origin_product: str | None = None) -> None:
+ HogFlow.objects.create(
+ team=self.team,
+ name="Welcome",
+ status=status,
+ origin_product=origin_product,
+ trigger={"type": "event"},
+ edges=[],
+ actions=[{"id": "step", "type": action_type}],
+ )
+
+ def test_a_new_project_starts_at_the_channel(self) -> None:
+ body = self._status()
+
+ assert not any(self._done(body).values())
+ assert body["ready_to_send_email"] is False
+ assert body["next_open_step"] == "channel"
+ assert body["steps"][0]["app_url"].endswith(
+ f"/project/{self.team.id}/workflows/onboarding?path=messaging&step=channel"
+ )
+
+ def test_an_unverified_domain_cannot_send(self) -> None:
+ self._add_email_channel(verified=False)
+
+ body = self._status()
+
+ assert self._done(body)["channel"] is True
+ assert self._done(body)["domain"] is False
+ assert body["ready_to_send_email"] is False
+ assert body["next_open_step"] == "domain"
+
+ @parameterized.expand(
+ [
+ ("a staff suspension", {"email_sending_suspended_at": timezone.now()}),
+ ("a disabled SES tenant", {"ses_tenant_sending_status": "DISABLED"}),
+ ]
+ )
+ def test_paused_sending_is_not_ready(self, _name, paused_fields) -> None:
+ self._add_email_channel(verified=True)
+ TeamWorkflowsConfig.objects.create(team=self.team, **paused_fields)
+
+ body = self._status()
+
+ assert self._done(body)["domain"] is True
+ assert body["ready_to_send_email"] is False
+ assert body["email_sending_paused"] is True
+
+ def test_a_set_up_project_has_every_step_done(self) -> None:
+ self._add_email_channel(verified=True)
+ create_message_category_for_test(team_id=self.team.id, key="product-updates", name="Product updates")
+ TeamWorkflowsConfig.objects.create(
+ team=self.team, marketing_frequency_cap_max_messages=1, marketing_frequency_cap_window_days=2
+ )
+ create_message_template_for_test(
+ team_id=self.team.id, name="Welcome", content={"email": {"subject": "Hi", "html": "<p>Hi</p>"}}
+ )
+ self._add_workflow(action_type="function_email")
+
+ body = self._status()
+
+ assert all(self._done(body).values())
+ assert body["ready_to_send_email"] is True
+ assert body["next_open_step"] is None
+
+ @parameterized.expand(
+ [
+ ("an email draft", {"action_type": "function_email"}, True),
+ ("a Slack-only automation", {"action_type": "function"}, False),
+ ("an archived email workflow", {"action_type": "function_email", "status": "archived"}, False),
+ ("a broadcast", {"action_type": "function_email", "origin_product": "broadcasts"}, False),
+ ]
+ )
+ def test_first_workflow_counts_only_live_messaging_workflows(self, _name, workflow, expected) -> None:
+ self._add_workflow(**workflow)
+
+ assert self._done(self._status())["first-workflow"] is expected
diff --git a/products/workflows/frontend/generated/api.schemas.ts b/products/workflows/frontend/generated/api.schemas.ts
index 61e5674c192d..e804a74fd590 100644
--- a/products/workflows/frontend/generated/api.schemas.ts
+++ b/products/workflows/frontend/generated/api.schemas.ts
@@ -2453,6 +2453,65 @@ export interface PeopleImportApi {
dropped_too_large: number
}
+/**
+ * * `channel` - Channel
+ * * `domain` - Domain
+ * * `opt-outs` - Opt-outs
+ * * `sending-rules` - Sending rules
+ * * `email-template` - Email template
+ * * `first-workflow` - First workflow
+ */
+export type SetupStepKeyEnumApi = (typeof SetupStepKeyEnumApi)[keyof typeof SetupStepKeyEnumApi]
+
+export const SetupStepKeyEnumApi = {
+ Channel: 'channel',
+ Domain: 'domain',
+ OptOuts: 'opt-outs',
+ SendingRules: 'sending-rules',
+ EmailTemplate: 'email-template',
+ FirstWorkflow: 'first-workflow',
+} as const
+
+export interface WorkflowSetupStepApi {
+ /** Which setup step this is. The steps come in the order the setup wizard asks for them.
+ *
+ * * `channel` - Channel
+ * * `domain` - Domain
+ * * `opt-outs` - Opt-outs
+ * * `sending-rules` - Sending rules
+ * * `email-template` - Email template
+ * * `first-workflow` - First workflow */
+ key: SetupStepKeyEnumApi
+ /** Whether the project has done this step. */
+ done: boolean
+ /** The step's name, as the app shows it. */
+ title: string
+ /** What the person does to finish the step. */
+ next_step: string
+ /** Link to the place in the app where the person does this step. */
+ app_url: string
+}
+
+export interface WorkflowSetupStatusApi {
+ /** Every messaging setup step, in order. */
+ steps: WorkflowSetupStepApi[]
+ /** Whether an email workflow can send. Needs a connected email channel on a verified domain, and email sending must not be paused for the project. SMS and push use their own channels, and automations that only post to tools like Slack or call webhooks need none of these steps. */
+ ready_to_send_email: boolean
+ /** Whether email sending is paused for the project, so no email sends even with a verified domain. The person contacts PostHog support to resume it. */
+ email_sending_paused: boolean
+ /** The first step that is not done, or null when every step is done.
+ *
+ * * `channel` - Channel
+ * * `domain` - Domain
+ * * `opt-outs` - Opt-outs
+ * * `sending-rules` - Sending rules
+ * * `email-template` - Email template
+ * * `first-workflow` - First workflow */
+ next_open_step: SetupStepKeyEnumApi | null
+ /** Whether workflows-data-suggestions-list can suggest workflows from this project's events. */
+ data_suggestions_available: boolean
+}
+
export type HogFlowTemplatesListParams = {
/**
* Number of results to return per page.
diff --git a/products/workflows/frontend/generated/api.ts b/products/workflows/frontend/generated/api.ts
index cb379bad9085..2dd52c088eab 100644
--- a/products/workflows/frontend/generated/api.ts
+++ b/products/workflows/frontend/generated/api.ts
@@ -78,6 +78,7 @@ import type {
WorkflowProposalCreateApi,
WorkflowProposalOutcomeApi,
WorkflowProposalRejectRequestApi,
+ WorkflowSetupStatusApi,
WorkflowStatsRowApi,
} from './api.schemas'
@@ -1468,6 +1469,23 @@ export const workflowPeopleImportsCreate = async (
})
}
+export const getWorkflowSetupStatusUrl = (projectId: string) => {
+ return `/api/projects/${projectId}/workflow_setup/status/`
+}
+
+/**
+ * Whether a project is set up to send messages from workflows.
+ */
+export const workflowSetupStatus = async (
+ projectId: string,
+ options?: RequestInit
+): Promise<WorkflowSetupStatusApi> => {
+ return apiMutator<WorkflowSetupStatusApi>(getWorkflowSetupStatusUrl(projectId), {
+ ...options,
+ method: 'GET',
+ })
+}
+
export const getInternalHogFlowsAccountAudienceCreateUrl = (teamId: string) => {
return `/api/projects/${teamId}/internal/hog_flows/account_audience`
}
diff --git a/products/workflows/mcp/apps/WorkflowSetupStatusView.tsx b/products/workflows/mcp/apps/WorkflowSetupStatusView.tsx
new file mode 100644
index 000000000000..4832d7d6bb8c
--- /dev/null
+++ b/products/workflows/mcp/apps/WorkflowSetupStatusView.tsx
@@ -0,0 +1,91 @@
+import { CheckCircle2, Circle } from 'lucide-react'
+import { type ReactElement } from 'react'
+
+import { Badge, Button, Card, CardContent } from '@posthog/quill'
+
+export interface WorkflowSetupStep {
+ key: string
+ done: boolean
+ title: string
+ next_step: string
+ app_url: string
+}
+
+export interface WorkflowSetupStatusData {
+ steps: WorkflowSetupStep[]
+ ready_to_send_email: boolean
+ email_sending_paused?: boolean
+ next_open_step: string | null
+ data_suggestions_available: boolean
+}
+
+export interface WorkflowSetupStatusViewProps {
+ data: WorkflowSetupStatusData
+ /** The host's link opener. Hosts that sandbox the app without popups block a plain new-tab link. */
+ openLink?: (url: string) => void
+}
+
+export function WorkflowSetupStatusView({ data, openLink }: WorkflowSetupStatusViewProps): ReactElement {
+ const doneCount = data.steps.filter((step) => step.done).length
+
+ return (
+ <div className="p-4">
+ <Card>
+ <CardContent className="flex flex-col gap-4">
+ <div className="flex flex-wrap items-center justify-between gap-2">
+ <div className="flex flex-col">
+ <span className="font-semibold">Messaging setup</span>
+ <span className="text-sm text-muted-foreground">
+ {doneCount} of {data.steps.length} steps done
+ </span>
+ </div>
+ <Badge variant={data.ready_to_send_email ? 'success' : 'warning'}>
+ {data.ready_to_send_email
+ ? 'Ready to send email'
+ : data.email_sending_paused
+ ? 'Email sending is paused'
+ : 'Email cannot send yet'}
+ </Badge>
+ </div>
+ <ol className="m-0 flex list-none flex-col gap-3 p-0">
+ {data.steps.map((step) => (
+ <li key={step.key} className="flex items-start gap-3">
+ {step.done ? (
+ <CheckCircle2 className="mt-0.5 size-4 shrink-0 text-success" aria-label="Done" />
+ ) : (
+ <Circle
+ className="mt-0.5 size-4 shrink-0 text-muted-foreground"
+ aria-label="Open"
+ />
+ )}
+ <div className="flex min-w-0 flex-1 flex-col">
+ <span className={step.done ? 'text-muted-foreground' : 'font-medium'}>
+ {step.title}
+ </span>
+ {!step.done && (
+ <span className="text-sm text-muted-foreground">{step.next_step}</span>
+ )}
+ </div>
+ {!step.done && (
+ <Button
+ size="sm"
+ variant={step.key === data.next_open_step ? 'primary' : 'outline'}
+ render={<a href={step.app_url} target="_blank" rel="noreferrer" />}
+ onClick={(event) => {
+ if (openLink) {
+ event.preventDefault()
+ openLink(step.app_url)
+ }
+ }}
+ >
+ Open
+ </Button>
+ )}
+ </li>
+ ))}
+ </ol>
+ </CardContent>
+ </Card>
+ </div>
+ )
+}
diff --git a/products/workflows/mcp/apps/Workflows.stories.tsx b/products/workflows/mcp/apps/Workflows.stories.tsx
index dc2ef8c8b631..4198e0146a51 100644
--- a/products/workflows/mcp/apps/Workflows.stories.tsx
+++ b/products/workflows/mcp/apps/Workflows.stories.tsx
@@ -6,6 +6,9 @@ import {
WorkflowDataSuggestionsView,
type WorkflowDataSuggestionsData,
WorkflowListView,
+ WorkflowSetupStatusView,
+ type WorkflowSetupStatusData,
+ type WorkflowSetupStep,
type WorkflowData,
type WorkflowListData,
WorkflowView,
@@ -144,3 +147,78 @@ export const DataSuggestionsBuilt: Story = {
),
name: 'Data suggestions after a build',
}
+
+const setupStep = (key: string, done: boolean, title: string, nextStep: string, path: string): WorkflowSetupStep => ({
+ key,
+ done,
+ title,
+ next_step: nextStep,
+ app_url: `https://us.posthog.com/project/1${path}`,
+})
+
+const newProjectSetup: WorkflowSetupStatusData = {
+ steps: [
+ setupStep(
+ 'channel',
+ true,
+ 'Connect an email channel',
+ 'Add the address emails send from.',
+ '/workflows/onboarding?path=messaging&step=channel'
+ ),
+ setupStep(
+ 'domain',
+ false,
+ 'Verify your sending domain',
+ "Add the DNS records shown in the app at the domain's DNS provider, then verify.",
+ '/workflows/onboarding?path=messaging&step=domain'
+ ),
+ setupStep(
+ 'opt-outs',
+ false,
+ 'Add opt-out categories',
+ 'Let people unsubscribe from one kind of message, such as product updates, and keep the rest.',
+ '/workflows/onboarding?path=messaging&step=opt-outs'
+ ),
+ setupStep(
+ 'sending-rules',
+ false,
+ 'Set a frequency cap',
+ 'Limit how many marketing emails one person gets. The recommended cap is 1 email every 2 days.',
+ '/settings/environment-workflows#workflows-frequency-cap'
+ ),
+ setupStep(
+ 'email-template',
+ false,
+ 'Design your first email',
+ 'Save a reusable email template in the library.',
+ '/workflows/library'
+ ),
+ setupStep(
+ 'first-workflow',
+ false,
+ 'Create your first workflow',
+ 'Build a workflow that sends email, SMS or push.',
+ '/workflows/onboarding?path=messaging&step=journey'
+ ),
+ ],
+ ready_to_send_email: false,
+ next_open_step: 'domain',
+ data_suggestions_available: true,
+}
+
+export const SetupStatusInProgress: Story = {
+ render: () => <WorkflowSetupStatusView data={newProjectSetup} />,
+}
+
+export const SetupStatusDone: Story = {
+ render: () => (
+ <WorkflowSetupStatusView
+ data={{
+ ...newProjectSetup,
+ steps: newProjectSetup.steps.map((step) => ({ ...step, done: true })),
+ ready_to_send_email: true,
+ next_open_step: null,
+ }}
+ />
+ ),
+}
diff --git a/products/workflows/mcp/apps/index.ts b/products/workflows/mcp/apps/index.ts
index b7ff6c9661d2..b2442e114149 100644
--- a/products/workflows/mcp/apps/index.ts
+++ b/products/workflows/mcp/apps/index.ts
@@ -10,3 +10,9 @@ export {
type WorkflowDataSuggestionsViewProps,
} from './WorkflowDataSuggestionsView'
export { WorkflowDataSuggestionBuildView } from './WorkflowDataSuggestionBuildView'
+export {
+ WorkflowSetupStatusView,
+ type WorkflowSetupStatusData,
+ type WorkflowSetupStatusViewProps,
+ type WorkflowSetupStep,
+} from './WorkflowSetupStatusView'
diff --git a/products/workflows/mcp/tools.yaml b/products/workflows/mcp/tools.yaml
index 715aac0a1788..299e2eeaac80 100644
--- a/products/workflows/mcp/tools.yaml
+++ b/products/workflows/mcp/tools.yaml
@@ -12,6 +12,12 @@ ui_apps:
workflow-list:
type: list
detail_tool: workflows-get
+ workflow-setup-status:
+ type: detail
+ view_prop: data
+ app_name: PostHog Messaging Setup
+ description: The messaging setup checklist, with a link to finish each open step.
+ link_prop: openLink
workflow-data-suggestions:
type: custom
app_name: PostHog Workflow Suggestions
@@ -444,6 +450,20 @@ tools:
in-flight. A 409 means a draft is already open — publish or discard it, or pass overwrite=true to replace
it. Note what a rollback can't undo: runs that already moved on while the newer version was live keep their
positions.
+ workflows-setup-status:
+ operation: workflow_setup_status
+ enabled: true
+ title: Check messaging setup
+ description: >
+ Which messaging setup steps the project has done: email channel, verified sending domain, opt-out
+ categories, frequency cap, email template and first workflow. Call it first when a user asks to set up
+ workflows or messaging, or asks to build an email, SMS or push workflow in a project that may not send yet.
+ For each open step, tell the user what it needs and share its app_url, since channel and domain setup happen
+ in the app. An email workflow can be drafted before ready_to_send_email is true, but it cannot send until it
+ is. Automations that only post to Slack or call webhooks need none of these steps. When
+ data_suggestions_available is true, offer workflows-data-suggestions-list once setup is done.
+ ui_app: workflow-setup-status
+ feature_flag: workflows-mcp-onboarding
workflows-stats:
operation: hog_flows_metrics_retrieve
enabled: true
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index cf22125eb549..86250bc27434 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -15261,6 +15261,21 @@
"readOnlyHint": false
}
},
+ "workflows-setup-status": {
+ "description": "Which messaging setup steps the project has done: email channel, verified sending domain, opt-out categories, frequency cap, email template and first workflow. Call it first when a user asks to set up workflows or messaging, or asks to build an email, SMS or push workflow in a project that may not send yet. For each open step, tell the user what it needs and share its app_url, since channel and domain setup happen in the app. An email workflow can be drafted before ready_to_send_email is true, but it cannot send until it is. Automations that only post to Slack or call webhooks need none of these steps. When data_suggestions_available is true, offer workflows-data-suggestions-list once setup is done.",
+ "category": "Workflows",
+ "feature": "workflows",
+ "summary": "Check messaging setup",
+ "title": "Check messaging setup",
+ "required_scopes": ["hog_flow:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "workflows-mcp-onboarding"
+ },
"workflows-show-email-template": {
"description": "Render an email template as an inline preview for the user. Call after creating or updating a template, and whenever the user asks to see one. The response carries the final rendered html — read it before describing the result. For fetching a template to edit it, use workflows-get-email-template.",
"category": "Workflows",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 75beb7bbdf0a..96402ea30ce9 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -16006,6 +16006,21 @@
"readOnlyHint": false
}
},
+ "workflows-setup-status": {
+ "description": "Which messaging setup steps the project has done: email channel, verified sending domain, opt-out categories, frequency cap, email template and first workflow. Call it first when a user asks to set up workflows or messaging, or asks to build an email, SMS or push workflow in a project that may not send yet. For each open step, tell the user what it needs and share its app_url, since channel and domain setup happen in the app. An email workflow can be drafted before ready_to_send_email is true, but it cannot send until it is. Automations that only post to Slack or call webhooks need none of these steps. When data_suggestions_available is true, offer workflows-data-suggestions-list once setup is done.",
+ "category": "Workflows",
+ "feature": "workflows",
+ "summary": "Check messaging setup",
+ "title": "Check messaging setup",
+ "required_scopes": ["hog_flow:read"],
+ "annotations": {
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": true,
+ "readOnlyHint": true
+ },
+ "feature_flag": "workflows-mcp-onboarding"
+ },
"workflows-show-email-template": {
"description": "Render an email template as an inline preview for the user. Call after creating or updating a template, and whenever the user asks to see one. The response carries the final rendered html — read it before describing the result. For fetching a template to edit it, use workflows-get-email-template.",
"category": "Workflows",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index c9d002476ed8..c00bf77cd5e3 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -102299,6 +102299,26 @@ export namespace Schemas {
summary: string;
}
+ /**
+ * * `channel` - Channel
+ * * `domain` - Domain
+ * * `opt-outs` - Opt-outs
+ * * `sending-rules` - Sending rules
+ * * `email-template` - Email template
+ * * `first-workflow` - First workflow
+ */
+ export type SetupStepKeyEnum = typeof SetupStepKeyEnum[keyof typeof SetupStepKeyEnum];
+
+
+ export const SetupStepKeyEnum = {
+ Channel: 'channel',
+ Domain: 'domain',
+ OptOuts: 'opt-outs',
+ SendingRules: 'sending-rules',
+ EmailTemplate: 'email-template',
+ FirstWorkflow: 'first-workflow',
+ } as const;
+
export interface SharePassword {
readonly id: number;
readonly created_at: string;
@@ -116374,6 +116394,46 @@ export namespace Schemas {
estimated_cost_usd: number | null;
}
+ export interface WorkflowSetupStep {
+ /** Which setup step this is. The steps come in the order the setup wizard asks for them.
+ *
+ * * `channel` - Channel
+ * * `domain` - Domain
+ * * `opt-outs` - Opt-outs
+ * * `sending-rules` - Sending rules
+ * * `email-template` - Email template
+ * * `first-workflow` - First workflow */
+ key: SetupStepKeyEnum;
+ /** Whether the project has done this step. */
+ done: boolean;
+ /** The step's name, as the app shows it. */
+ title: string;
+ /** What the person does to finish the step. */
+ next_step: string;
+ /** Link to the place in the app where the person does this step. */
+ app_url: string;
+ }
+
+ export interface WorkflowSetupStatus {
+ /** Every messaging setup step, in order. */
+ steps: WorkflowSetupStep[];
+ /** Whether an email workflow can send. Needs a connected email channel on a verified domain, and email sending must not be paused for the project. SMS and push use their own channels, and automations that only post to tools like Slack or call webhooks need none of these steps. */
+ ready_to_send_email: boolean;
+ /** Whether email sending is paused for the project, so no email sends even with a verified domain. The person contacts PostHog support to resume it. */
+ email_sending_paused: boolean;
+ /** The first step that is not done, or null when every step is done.
+ *
+ * * `channel` - Channel
+ * * `domain` - Domain
+ * * `opt-outs` - Opt-outs
+ * * `sending-rules` - Sending rules
+ * * `email-template` - Email template
+ * * `first-workflow` - First workflow */
+ next_open_step: SetupStepKeyEnum | null;
+ /** Whether workflows-data-suggestions-list can suggest workflows from this project's events. */
+ data_suggestions_available: boolean;
+ }
+
export interface WorkflowStatsRow {
/** The workflow these counts are for. */
workflow_id: string;
diff --git a/services/mcp/src/generated/workflows/api.ts b/services/mcp/src/generated/workflows/api.ts
index 7238f543a335..96c210293a85 100644
--- a/services/mcp/src/generated/workflows/api.ts
+++ b/services/mcp/src/generated/workflows/api.ts
@@ -3,7 +3,7 @@
* MCP service uses these Zod schemas for generated tool handlers.
* To regenerate: hogli build:openapi
*
- * PostHog API - MCP 25 enabled ops
+ * PostHog API - MCP 26 enabled ops
* OpenAPI spec version: 1.0.0
*/
import * as zod from 'zod'
@@ -1352,3 +1352,14 @@ export const WorkflowDataSuggestionsGenerateBody = () => zod.object({
.default(workflowDataSuggestionsGenerateBodyRefreshDefault)
.describe('Make new suggestions even when the cached ones are still valid.'),
})
+
+/**
+ * Whether a project is set up to send messages from workflows.
+ */
+export const WorkflowSetupStatusParams = () => zod.object({
+ project_id: zod
+ .string()
+ .describe(
+ "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
+ ),
+})
diff --git a/services/mcp/src/resources/ui-apps.generated.ts b/services/mcp/src/resources/ui-apps.generated.ts
index eb92d047ffa8..24775a723193 100644
--- a/services/mcp/src/resources/ui-apps.generated.ts
+++ b/services/mcp/src/resources/ui-apps.generated.ts
@@ -32,6 +32,7 @@ export const VISUAL_REVIEW_SNAPSHOTS_RESOURCE_URI = 'ui://posthog/visual-review-
export const WORKFLOW_RESOURCE_URI = 'ui://posthog/workflow.html'
export const WORKFLOW_DATA_SUGGESTIONS_RESOURCE_URI = 'ui://posthog/workflow-data-suggestions.html'
export const WORKFLOW_LIST_RESOURCE_URI = 'ui://posthog/workflow-list.html'
+export const WORKFLOW_SETUP_STATUS_RESOURCE_URI = 'ui://posthog/workflow-setup-status.html'
export type UiAppKey =
| 'action'
@@ -66,6 +67,7 @@ export type UiAppKey =
| 'workflow'
| 'workflow-data-suggestions'
| 'workflow-list'
+ | 'workflow-setup-status'
export const URI_MAP: Record<UiAppKey, string> = {
action: ACTION_RESOURCE_URI,
@@ -100,6 +102,7 @@ export const URI_MAP: Record<UiAppKey, string> = {
workflow: WORKFLOW_RESOURCE_URI,
'workflow-data-suggestions': WORKFLOW_DATA_SUGGESTIONS_RESOURCE_URI,
'workflow-list': WORKFLOW_LIST_RESOURCE_URI,
+ 'workflow-setup-status': WORKFLOW_SETUP_STATUS_RESOURCE_URI,
}
/**
@@ -135,6 +138,7 @@ export const DISPATCHABLE_APP_KEYS: UiAppKey[] = [
'vision-observation-list',
'workflow',
'workflow-list',
+ 'workflow-setup-status',
]
export const UI_APPS: Array<{
@@ -340,4 +344,10 @@ export const UI_APPS: Array<{
description: 'Workflow List view',
appDir: 'generated/workflow-list',
},
+ {
+ name: 'PostHog Messaging Setup',
+ uri: WORKFLOW_SETUP_STATUS_RESOURCE_URI,
+ description: 'The messaging setup checklist, with a link to finish each open step.',
+ appDir: 'generated/workflow-setup-status',
+ },
]
diff --git a/services/mcp/src/tools/generated/workflows.ts b/services/mcp/src/tools/generated/workflows.ts
index ae9c2ba6add5..dd9693519866 100644
--- a/services/mcp/src/tools/generated/workflows.ts
+++ b/services/mcp/src/tools/generated/workflows.ts
@@ -618,6 +618,22 @@ const workflowsRestoreRevision = (): ToolBase<ReturnType<typeof WorkflowsRestore
},
})
+const WorkflowsSetupStatusSchema = () => z.object({})
+
+const workflowsSetupStatus = (): ToolBase<ReturnType<typeof WorkflowsSetupStatusSchema>, Schemas.WorkflowSetupStatus> =>
+ withUiApp('workflow-setup-status', {
+ name: 'workflows-setup-status',
+ schema: WorkflowsSetupStatusSchema(),
+ handler: async (context: Context, _params: z.infer<ReturnType<typeof WorkflowsSetupStatusSchema>>) => {
+ const projectId = await context.stateManager.getProjectId()
+ const result = await context.api.request<Schemas.WorkflowSetupStatus>({
+ method: 'GET',
+ path: `/api/projects/${encodeURIComponent(String(projectId))}/workflow_setup/status/`,
+ })
+ return result
+ },
+ })
+
const WorkflowsStatsSchema = () => {
const HogFlowsMetricsRetrieveParams = orvalSchemas.HogFlowsMetricsRetrieveParams()
const HogFlowsMetricsRetrieveQueryParams = orvalSchemas.HogFlowsMetricsRetrieveQueryParams()
@@ -858,6 +874,7 @@ export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
'workflows-patch-graph': workflowsPatchGraph,
'workflows-publish': workflowsPublish,
'workflows-restore-revision': workflowsRestoreRevision,
+ 'workflows-setup-status': workflowsSetupStatus,
'workflows-stats': workflowsStats,
'workflows-suggest': workflowsSuggest,
'workflows-test-run': workflowsTestRun,
diff --git a/services/mcp/src/ui-apps/apps/generated/workflow-setup-status.tsx b/services/mcp/src/ui-apps/apps/generated/workflow-setup-status.tsx
new file mode 100644
index 000000000000..1f5a4b4f08a5
--- /dev/null
+++ b/services/mcp/src/ui-apps/apps/generated/workflow-setup-status.tsx
@@ -0,0 +1,21 @@
+// AUTO-GENERATED by generate-ui-apps.ts — do not edit
+import '../../styles/tailwind.css'
+
+import { createRoot } from 'react-dom/client'
+
+import { type WorkflowSetupStatusData, WorkflowSetupStatusView } from 'products/workflows/mcp/apps'
+
+import { AppWrapper } from '../../components/AppWrapper'
+
+function WorkflowSetupStatusApp(): JSX.Element {
+ return (
+ <AppWrapper<WorkflowSetupStatusData> appName="PostHog Messaging Setup">
+ {({ data, openLink }) => <WorkflowSetupStatusView data={data!} openLink={openLink} />}
+ </AppWrapper>
+ )
+}
+
+const container = document.getElementById('root')
+if (container) {
+ createRoot(container).render(<WorkflowSetupStatusApp />)
+}
diff --git a/services/mcp/src/ui-apps/generated/render-dispatch.generated.tsx b/services/mcp/src/ui-apps/generated/render-dispatch.generated.tsx
index f15a975581b5..7bd805ad62df 100644
--- a/services/mcp/src/ui-apps/generated/render-dispatch.generated.tsx
+++ b/services/mcp/src/ui-apps/generated/render-dispatch.generated.tsx
@@ -50,10 +50,12 @@ import { TraceSpanListView, TraceSpanView, type TraceSpanData, type TraceSpanLis
import {
EmailTemplateView,
WorkflowListView,
+ WorkflowSetupStatusView,
WorkflowView,
type EmailTemplateData,
type WorkflowData,
type WorkflowListData,
+ type WorkflowSetupStatusData,
} from 'products/workflows/mcp/apps'
import type { UiAppKey } from '../../resources/ui-apps.generated'
@@ -446,4 +448,7 @@ export const RENDER_DISPATCH: Partial<Record<UiAppKey, (props: RenderDispatchPro
),
workflow: ({ data }) => <WorkflowView workflow={data as WorkflowData} />,
'workflow-list': ({ data, app }) => <WorkflowListContent data={data as WorkflowListData} app={app} />,
+ 'workflow-setup-status': ({ data, openLink }) => (
+ <WorkflowSetupStatusView data={data as WorkflowSetupStatusData} openLink={openLink} />
+ ),
}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-setup-status.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-setup-status.json
new file mode 100644
index 000000000000..7b7ea9186078
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-setup-status.json
@@ -0,0 +1,5 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {},
+ "type": "object"
+}
diff --git a/services/mcp/tests/unit/tool-filtering.test.ts b/services/mcp/tests/unit/tool-filtering.test.ts
index 8bcce8136ed8..0111bad32ae8 100644
--- a/services/mcp/tests/unit/tool-filtering.test.ts
+++ b/services/mcp/tests/unit/tool-filtering.test.ts
@@ -1137,10 +1137,11 @@ describe('Tool Filtering - Feature Flags', () => {
'marketing-analytics-setup-plan-mcp',
'subscription-source-summaries',
'workflows-data-suggestions',
+ 'workflows-mcp-onboarding',
])
)
expect(flags).toContain('ai-observability-offline-evaluations')
- expect(flags).toHaveLength(38)
+ expect(flags).toHaveLength(39)
})
it('keeps human and task context wiki tools on separate scopes', () => {
diff --git a/services/mcp/tests/unit/tool-schema-snapshots.test.ts b/services/mcp/tests/unit/tool-schema-snapshots.test.ts
index b0b0c0bda391..06cbdaeaa817 100644
--- a/services/mcp/tests/unit/tool-schema-snapshots.test.ts
+++ b/services/mcp/tests/unit/tool-schema-snapshots.test.ts
@@ -105,6 +105,7 @@ async function loadSnapshotTools(): Promise<Tool<ZodObjectAny>[]> {
'scouts-tool-access': true,
'subscription-source-summaries': true,
'workflows-data-suggestions': true,
+ 'workflows-mcp-onboarding': true,
}
return [...(await getToolsFromContext(createMockContext(), { featureFlags }))].sort((a, b) =>
a.name.localeCompare(b.name)