Managing Subscriptions

1---
2name: managing-subscriptions
3description: 'Manage PostHog subscriptions — scheduled email, Slack, or webhook deliveries of insight or dashboard snapshots, optionally with an AI-written summary attached to each delivery. Use when the user wants to subscribe to an insight or dashboard, get an AI summary attached to those deliveries, check existing subscriptions, change delivery frequency, add or remove recipients, or stop receiving updates.'
4---
5 
6# Managing subscriptions
7 
8This skill guides you through managing PostHog subscriptions.
9Subscriptions deliver scheduled snapshots of insights or dashboards via email, Slack, or webhook.
10 
11## When to use this skill
12 
13Use this skill when the user:
14 
15- Wants to "track", "follow", "subscribe to", or "get updates" about an insight or dashboard
16- Asks for "daily updates", "weekly reports", or "send me this every morning"
17- Wants an **AI-written summary** attached to each delivery of an insight or dashboard (see step 6)
18- Wants to know what subscriptions they have
19- Asks to stop, pause, or unsubscribe from something
20- Wants to change who receives an update or how often
21 
22## Subscriptions vs alerts
23 
24Subscriptions and alerts serve different purposes:
25 
26- **Subscriptions** deliver a snapshot on a fixed schedule (daily, weekly, etc.) regardless of the data
27- **Alerts** fire only when a condition is met (threshold crossed, anomaly detected)
28 
29If the user says "notify me when this drops below 100", use alerts.
30If the user says "send me this every morning", use subscriptions.
31 
32## Workflow
33 
34### Listing existing subscriptions
35 
36Before creating a new subscription, check if one already exists.
37 
38Use `subscriptions-list` with optional filters:
39 
40- Filter by insight: pass the `insight` query parameter with the insight ID
41- Filter by dashboard: pass the `dashboard` query parameter with the dashboard ID
42- Filter by channel: pass `target_type` as `email`, `slack`, or `webhook`
43 
44### Creating a subscription
45 
46#### Step 1: Ask the user how they want to receive it
47 
48**Always ask the user whether they want email or Slack delivery** before creating a subscription.
49Do not assume a channel — ask explicitly:
50 
51> Would you like to receive this via **email** or **Slack**?
52 
53If the user says Slack, you must verify the integration is available (see step 2).
54If the user doesn't have a preference, suggest email as the simplest option.
55 
56#### Step 2: Verify channel availability
57 
58**Email** requires no setup — it works out of the box. You just need the user's email address.
59Get it from the user context or from `org-members-list`.
60 
61**Slack** requires a connected Slack integration. Before creating a Slack subscription:
62 
631. Call `integrations-list` and look for an integration where `kind` is `"slack"`
642. If a Slack integration exists, note its `id` — you'll need it as `integration_id`
653. If **no Slack integration exists**, tell the user:
66   > Slack isn't connected to this project yet. You can set it up in
67   > [Project settings > Integrations](/settings/integrations).
68   > In the meantime, would you like to receive this via email instead?
69 
70Slack setup requires an OAuth flow in the browser — it cannot be done via MCP.
71 
72**Webhook** requires the user to provide a URL. Verify it looks like a valid URL before submitting.
73 
74#### Step 3: Identify the target
75 
76Get the insight ID or dashboard ID. If the user provides a URL like `/project/2/insights/pKxzopBG`,
77fetch the insight first with `insight-get` to get the numeric ID.
78 
79#### Step 4: Determine delivery settings from the user's request
80 
81| User says                               | Parameters                                                                |
82| --------------------------------------- | ------------------------------------------------------------------------- |
83| "every day" / "daily" / "every morning" | `frequency: "daily"`                                                      |
84| "every week" / "weekly"                 | `frequency: "weekly"`                                                     |
85| "every Monday"                          | `frequency: "weekly"`, `byweekday: ["monday"]`                            |
86| "every month" / "monthly"               | `frequency: "monthly"`                                                    |
87| "twice a week"                          | `frequency: "weekly"`, `interval: 1`, `byweekday: ["monday", "thursday"]` |
88 
89#### Step 5: Create with `subscriptions-create`
90 
91For an insight subscription via email:
92 
93```json
94{
95  "insight": 12345,
96  "target_type": "email",
97  "target_value": "user@example.com",
98  "frequency": "daily",
99  "start_date": "2025-01-01T09:00:00Z"
100}
101```
102 
103For a dashboard subscription (requires selecting which insights to include, max 6):
104 
105```json
106{
107  "dashboard": 67,
108  "dashboard_export_insights": [101, 102, 103],
109  "target_type": "email",
110  "target_value": "user@example.com",
111  "frequency": "weekly",
112  "byweekday": ["monday"],
113  "start_date": "2025-01-01T09:00:00Z"
114}
115```
116 
117For Slack delivery, include the `integration_id` from step 2:
118 
119```json
120{
121  "insight": 12345,
122  "target_type": "slack",
123  "target_value": "#general",
124  "integration_id": 789,
125  "frequency": "daily",
126  "start_date": "2025-01-01T09:00:00Z"
127}
128```
129 
130#### Step 6 (optional): Attach an AI summary
131 
132For **insight and dashboard** subscriptions you can attach an AI-written summary to every
133delivery — a short narrative that calls out what changed, outliers, and notable insights
134alongside the snapshot. Set it at create time (or toggle later via `subscriptions-partial-update`):
135 
136- `summary_enabled: true` — turns on the per-delivery AI summary
137- `summary_prompt_guide: "..."` — optional steer, e.g. "focus on sign-up conversion and any new drop-off points"
138 
139```json
140{
141  "dashboard": 67,
142  "dashboard_export_insights": [101, 102, 103],
143  "target_type": "email",
144  "target_value": "user@example.com",
145  "frequency": "weekly",
146  "byweekday": ["monday"],
147  "start_date": "2025-01-01T09:00:00Z",
148  "summary_enabled": true,
149  "summary_prompt_guide": "Call out outliers and new insights since last week"
150}
151```
152 
153Enabling a summary requires the organization to have **approved AI data processing**
154(`Org settings → Data → AI data processing`) and to be within its active-summary cap and AI
155credit budget; otherwise the create/update is rejected. `summary_enabled` does not apply to
156prompt subscriptions — those are AI-generated by definition (see `creating-ai-subscription`).
157 
158### Updating a subscription
159 
160Use `subscriptions-partial-update` with the subscription ID. Common updates:
161 
162- **Change frequency**: `{"frequency": "weekly", "byweekday": ["monday"]}`
163- **Add recipients**: Update `target_value` with the full comma-separated list
164- **Change channel**: Update `target_type` and `target_value` together
165- **Toggle the AI summary** (insight/dashboard subs): `{"summary_enabled": true, "summary_prompt_guide": "..."}` — same AI-data-processing and budget gates as step 6
166 
167### Deactivating a subscription
168 
169Subscriptions are soft-deleted. Use `subscriptions-partial-update`:
170 
171```json
172{
173  "id": 456,
174  "deleted": true
175}
176```
177 
178## Defaults
179 
180When the user doesn't specify details:
181 
182- **Frequency**: `"daily"`
183- **Channel**: email to the current user
184- **Start date**: now (ISO 8601)
185- **Title**: auto-generated from the insight/dashboard name if not specified
186 
187## Error handling
188 
189- **Duplicate check**: If a subscription already exists for the same insight/dashboard and channel, inform the user and offer to update it rather than creating a duplicate
190- **Slack not connected**: If a Slack subscription is requested but no Slack integration exists, explain that Slack must be connected in [Project settings > Integrations](/settings/integrations) first, then offer email as an alternative. Do not attempt to create the subscription — it will fail with a validation error
191- **Slack integration wrong team**: The Slack integration must belong to the same PostHog team. If `integrations-list` returns Slack integrations but creation still fails, the integration may be misconfigured
192- **Dashboard insights**: Dashboard subscriptions require at least 1 and at most 6 insights selected via `dashboard_export_insights`. If the user doesn't specify which insights, fetch the dashboard with `dashboard-get` and select the first 6 insights from its tiles
193