@sequenzy/mcp 0.0.161 → 0.0.163

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +1643 -0
  2. package/dist/index.js +4 -4
  3. package/dist/runtime.js +1 -1
  4. package/dist/server.js +4 -4
  5. package/package.json +1 -1
  6. package/server.json +2 -2
package/README.md ADDED
@@ -0,0 +1,1643 @@
1
+ # Sequenzy MCP Server
2
+
3
+ Official MCP server for [Sequenzy](https://sequenzy.com), the AI-powered email marketing platform.
4
+
5
+ Connect Sequenzy to Claude Desktop, Claude Code, Codex, Cursor, Windsurf, VS Code Copilot, OpenClaw, and other MCP clients so your AI assistant can manage email operations with structured tools instead of hand-written API calls.
6
+
7
+ ## What You Can Do
8
+
9
+ - Manage subscribers, tags, lists, and dynamic segments, including bulk tag reconciliation and synthetic event testing.
10
+ - Sync segments to Meta custom audiences for Facebook and Instagram retargeting.
11
+ - Manage products and attach digital delivery files for purchase automations.
12
+ - Upload hosted email images with alt text and reusable responsive crop settings.
13
+ - Draft, update, schedule, and inspect campaigns, including resolved audience previews, persisted conversion goals, and From, Reply-To, CC, and BCC identities.
14
+ - Render campaigns, sequence steps, and templates to their exact email-safe HTML without sending.
15
+ - Add one-click Poll and NPS survey blocks to emails and inspect campaign response summaries.
16
+ - Create and edit email sequences, including multi-list/tag triggers, entry-audience and property-filtered stop conditions, sending identity overrides, existing graph restructuring, and direct step test sends to internal reviewers.
17
+ - Cancel, pause, resume, duplicate, or delete campaigns and enroll contacts into sequences.
18
+ - Manage transactional email templates and send transactional emails to shared To, Cc, and Bcc recipient lists.
19
+ - Supply localized template variants or queue AI translation for enabled locales.
20
+ - Create, preview, edit, publish, unpublish, and delete landing pages.
21
+ - Create list-scoped saved signup forms with responsive stack, row, grid, and
22
+ single-image overlay block groups (including foreground gap controls), then
23
+ return client-safe static-site embeds.
24
+ - Create, target, publish, duplicate, and deploy saved signup popups with the
25
+ same recursive block layouts.
26
+ - Connect and verify custom domains for published landing pages.
27
+ - Manage team invitations, inbox conversations, and outbound webhook endpoints.
28
+ - Generate email copy, subject lines, and multi-step sequences.
29
+ - Inspect analytics, subscriber activity, deliverability health, company-level sending pauses, integrations, published event payload schemas, sending identities, tracking settings, and dashboard URLs.
30
+ - Inspect whether "Sent with Sequenzy" is visible for a workspace, why the owner subscription does or does not remove it, and open the canonical subscription page for an upgrade or renewal. Entitlement changes apply to future sends from existing live sequences without editing their blocks.
31
+ - Diagnose why sending is paused and restore eligible hard-bounce pauses after confirming list cleanup.
32
+ - Inspect exact-recipient bounce, complaint, and email-hygiene suppression, and clean up eligible stale bounces without exposing the shared SES suppression list.
33
+ - Configure company product info, account-wide sending identity defaults, rename individual sender and reply-to profiles, manage sender domains, and inspect integration examples for common frameworks.
34
+
35
+ Every published MCP tool includes explicit `readOnlyHint`, `destructiveHint`, and `openWorldHint` annotations so compatible clients can display accurate tool-use affordances. Tools also publish `outputSchema` definitions and return `structuredContent`, giving clients and models machine-readable result shapes for follow-up calls.
36
+
37
+ ## Quick Setup
38
+
39
+ The easiest setup path is the Sequenzy wizard:
40
+
41
+ ```bash
42
+ npx @sequenzy/setup
43
+ ```
44
+
45
+ The wizard opens the browser login flow, creates a personal API key, detects supported AI clients, and configures them automatically when possible.
46
+
47
+ ## Hosted Remote MCP
48
+
49
+ For clients that support Streamable HTTP MCP, use Sequenzy's hosted endpoint instead of running a local stdio process:
50
+
51
+ ```text
52
+ https://api.sequenzy.com/v1/mcp
53
+ ```
54
+
55
+ ChatGPT and the OpenAI plugin directory use the reviewed hosted surface:
56
+
57
+ ```text
58
+ https://api.sequenzy.com/v1/mcp/openai
59
+ ```
60
+
61
+ That surface shares the same implementation and keeps the standard tool set
62
+ except for six operations: `connect_integration`, `create_api_key`,
63
+ `create_webhook`, `list_webhook_deliveries`, `replay_webhook_delivery`, and
64
+ `rotate_sequence_inbound_webhook_secret`. Feedback stays available with a
65
+ reduced schema for generalized, explicitly requested product feedback.
66
+
67
+ Tool annotations disclose supported replacement and irreversible-delivery modes, including automation-triggering actions. Public content and provider changes are marked open-world; private draft creation and additive notes remain non-destructive. Feedback goes to the Sequenzy team through Telegram with the authenticated company name/ID and account email added for attribution, which clients must disclose before sending.
68
+
69
+ Remote clients should authenticate with the Sequenzy OAuth flow when supported. Local and automation clients can still use the stdio package below with `SEQUENZY_API_KEY`.
70
+
71
+ The hosted endpoint and the stdio package support MCP specification
72
+ `2026-07-28` while remaining compatible with 2025-era clients. Modern HTTP
73
+ clients use per-request discovery and method headers; existing clients keep
74
+ working through the same endpoint and package command.
75
+
76
+ Machine-readable discovery files:
77
+
78
+ - MCP server manifest: [`server.json`](server.json)
79
+ - Agent card: [`.well-known/agent-card.json`](https://github.com/Sequenzy/mcp/blob/main/.well-known/agent-card.json)
80
+ - Agent capability manifest: [`agent-capability.json`](https://github.com/Sequenzy/mcp/blob/main/agent-capability.json)
81
+ - OpenClaw skill metadata: [`openclaw/skill.json`](https://github.com/Sequenzy/mcp/blob/main/openclaw/skill.json)
82
+
83
+ ### Data and privacy
84
+
85
+ Sequenzy sends an MCP client only the data needed for the tool the user asks it
86
+ to run, within the selected workspace and the key or OAuth scopes granted to
87
+ that client. Depending on the requested tool, this can include workspace names
88
+ and IDs; subscriber contact, consent, audience, attribute, event, engagement,
89
+ reply, survey, and commerce data; campaign and automation content; delivery
90
+ analytics; and integration or webhook status. See the
91
+ [Sequenzy Privacy Policy](https://sequenzy.com/privacy) for the full categories,
92
+ purposes, recipients, retention periods, and user controls.
93
+
94
+ Do not use open-ended custom attributes, events, notes, forms, webhook samples,
95
+ email variables, or feedback to submit payment-card data, health or medical
96
+ data, government identifiers, biometric or genetic data, authentication
97
+ credentials, sensitive demographic data, or precise geolocation.
98
+
99
+ The OpenAI-reviewed route states and enforces those restrictions on relevant
100
+ open-ended inputs, including nested attribute paths such as `profile.ssn`,
101
+ coordinate pairs such as `lat`/`lng`, and labelled prose such as
102
+ `Religion: ...` or `GPS coordinates: ...`. It rejects a credential-bearing URL
103
+ in any argument, whether the credential sits in the userinfo, path, query, or
104
+ fragment, such as a form or popup `redirectUrl` with an access token or URL
105
+ signature. Restricted attribute selectors inside merge tags are rejected
106
+ without blocking ordinary authored copy about the same topic. On this surface,
107
+ `render_email` accepts sample data or a policy-checked inline `subscriber`, but
108
+ not `subscriberId`, so it cannot resolve uninspected stored custom attributes.
109
+ Its results remove restricted fields, raw API errors, debug payloads, internal
110
+ request/trace/session identifiers, unnecessary account or credential
111
+ identifiers, stored credential-bearing URLs, and inbound-webhook URLs. Standard
112
+ remote MCP and the local stdio package retain the complete contract for trusted
113
+ clients, including credential-based integration setup, one-time API-key and
114
+ webhook secrets, inbound-webhook URLs, and detailed API errors. Prefer the
115
+ dashboard or local CLI when secrets should stay outside an AI conversation.
116
+ `submit_feedback` runs only when the user explicitly asks; its OpenAI schema is
117
+ limited to a generalized message, category, and optional workflow context, and
118
+ the route rejects feedback text that contains an email address or resource ID.
119
+
120
+ What the reviewed surface guarantees is bounded. It recognizes restricted data
121
+ by shape: English field-name words such as `passport_id`, `user.ssn`, or
122
+ `api_secret` at any nesting depth, labelled prose such as `Diagnosis: ...`,
123
+ known credential shapes, decimal coordinate pairs, and credential-bearing URLs
124
+ inside any string, including HTML. It does not interpret unlabelled prose,
125
+ non-English field names, or values a client deliberately obfuscates; those
126
+ remain covered by the usage restriction above rather than by the filter.
127
+
128
+ ## Manual Setup
129
+
130
+ All stdio MCP clients use the same command:
131
+
132
+ - Command: `npx`
133
+ - Args: `-y @sequenzy/mcp`
134
+ - Required env: `SEQUENZY_API_KEY=seq_user_your_key_here`
135
+
136
+ Optional environment variables:
137
+
138
+ - `SEQUENZY_API_URL` - Sequenzy API base URL. Defaults to `https://api.sequenzy.com`.
139
+ - `SEQUENZY_APP_URL` - Sequenzy dashboard base URL used by app URL helpers. Defaults to `https://sequenzy.com`.
140
+
141
+ ### Claude Desktop
142
+
143
+ Add this to your Claude Desktop config:
144
+
145
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
146
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
147
+
148
+ ```json
149
+ {
150
+ "mcpServers": {
151
+ "sequenzy": {
152
+ "command": "npx",
153
+ "args": ["-y", "@sequenzy/mcp"],
154
+ "env": {
155
+ "SEQUENZY_API_KEY": "seq_user_your_key_here"
156
+ }
157
+ }
158
+ }
159
+ }
160
+ ```
161
+
162
+ Restart Claude Desktop after editing the config.
163
+
164
+ ### Claude Code
165
+
166
+ ```bash
167
+ claude mcp add --scope user --env=SEQUENZY_API_KEY=seq_user_your_key_here sequenzy -- npx -y @sequenzy/mcp
168
+ ```
169
+
170
+ On native Windows, wrap `npx` with `cmd /c`:
171
+
172
+ ```bash
173
+ claude mcp add --scope user --env=SEQUENZY_API_KEY=seq_user_your_key_here sequenzy -- cmd /c npx -y @sequenzy/mcp
174
+ ```
175
+
176
+ For a shared project config, use `.mcp.json`:
177
+
178
+ ```json
179
+ {
180
+ "mcpServers": {
181
+ "sequenzy": {
182
+ "command": "npx",
183
+ "args": ["-y", "@sequenzy/mcp"],
184
+ "env": {
185
+ "SEQUENZY_API_KEY": "seq_user_your_key_here"
186
+ }
187
+ }
188
+ }
189
+ }
190
+ ```
191
+
192
+ ### Codex
193
+
194
+ ```bash
195
+ codex mcp add sequenzy --env SEQUENZY_API_KEY=seq_user_your_key_here -- npx -y @sequenzy/mcp
196
+ codex mcp list
197
+ ```
198
+
199
+ Manual Codex config in `~/.codex/config.toml`:
200
+
201
+ ```toml
202
+ [mcp_servers.sequenzy]
203
+ command = "npx"
204
+ args = ["-y", "@sequenzy/mcp"]
205
+
206
+ [mcp_servers.sequenzy.env]
207
+ SEQUENZY_API_KEY = "seq_user_your_key_here"
208
+ ```
209
+
210
+ ### Cursor
211
+
212
+ Install **Sequenzy** from the Cursor Marketplace for a hosted connection with Sequenzy OAuth. The plugin connects to:
213
+
214
+ ```text
215
+ https://api.sequenzy.com/v1/mcp
216
+ ```
217
+
218
+ After installing, complete the browser sign-in flow. Cursor's agent can then use Sequenzy tools from chat, including when Grok is the selected model.
219
+
220
+ For a manual local stdio setup instead, add this to `~/.cursor/mcp.json`:
221
+
222
+ ```json
223
+ {
224
+ "mcpServers": {
225
+ "sequenzy": {
226
+ "command": "npx",
227
+ "args": ["-y", "@sequenzy/mcp"],
228
+ "env": {
229
+ "SEQUENZY_API_KEY": "seq_user_your_key_here"
230
+ }
231
+ }
232
+ }
233
+ }
234
+ ```
235
+
236
+ ### Windsurf
237
+
238
+ Use the same JSON shape as Cursor.
239
+
240
+ - macOS: `~/Library/Application Support/Windsurf/mcp.json`
241
+ - Windows: `%APPDATA%\Windsurf\mcp.json`
242
+
243
+ ### VS Code Copilot
244
+
245
+ VS Code uses a `servers` object:
246
+
247
+ ```json
248
+ {
249
+ "servers": {
250
+ "sequenzy": {
251
+ "type": "stdio",
252
+ "command": "npx",
253
+ "args": ["-y", "@sequenzy/mcp"],
254
+ "env": {
255
+ "SEQUENZY_API_KEY": "seq_user_your_key_here"
256
+ }
257
+ }
258
+ }
259
+ }
260
+ ```
261
+
262
+ ### Other MCP Clients
263
+
264
+ For OpenClaw, Hermes, and other MCP-compatible clients, point the client at `npx -y @sequenzy/mcp` and set `SEQUENZY_API_KEY`.
265
+
266
+ ## Getting an API Key
267
+
268
+ 1. Open [the Sequenzy dashboard](https://sequenzy.com/dashboard).
269
+ 2. Use the **MCP** setup flow to create a personal key, or open **Settings ->
270
+ API Keys** to create a company key.
271
+ 3. Choose a permission preset or the exact custom scopes the integration needs.
272
+ 4. Add the key to your MCP client config.
273
+
274
+ Personal keys start with `seq_user_`. You can revoke them any time in the dashboard.
275
+
276
+ Company keys can also be cleaned up without exposing secrets. Call
277
+ `list_api_keys` to compare the key ID, name, non-secret prefix, permissions,
278
+ last-use timestamp, and `isCurrent` marker, then pass the exact ID to
279
+ `revoke_api_key`. `delete_api_key` is a compatibility alias for the same
280
+ permanent operation. List and revoke responses never contain the plain key or
281
+ stored key hash.
282
+
283
+ ### Recover from missing API key permissions
284
+
285
+ If a tool reports a missing scope such as `campaigns:read` or
286
+ `templates:write`, call `get_account`. Its `apiKeyPermissions` field lists the
287
+ current key identity and type, scopes, common missing marketing read scopes, and
288
+ a direct `manageUrl`. The OpenAI-reviewed route returns the same permissions
289
+ without the user's account ID or the active key's identity. Personal keys open
290
+ Account API Keys; company keys open the selected workspace's API Keys settings.
291
+ If the key does not include
292
+ `account:read`, open the
293
+ [Sequenzy dashboard](https://sequenzy.com/dashboard) directly and choose the
294
+ matching API Keys page.
295
+
296
+ Permissions are editable in place, so open `manageUrl`. For a company key, use
297
+ `list_api_keys` and its `isCurrent` flag to identify the active key before
298
+ editing it, then retry the failed tool without replacing the credential or
299
+ restarting the client. An agent using a company key with `api_keys:manage` can
300
+ instead call `update_api_key`; personal keys must be edited on the account-level
301
+ page because that tool only manages company keys. Its `scopes` and `preset`
302
+ inputs replace the whole permission selection rather than merging, so preserve
303
+ every existing scope that is still needed. Hosted OAuth connections can
304
+ alternatively disconnect and reauthorize with broader permissions.
305
+
306
+ When the active key itself lacks `api_keys:manage`, call
307
+ `request_api_key_handoff` instead of retrying `update_api_key`. It requires
308
+ `account:read` and returns an owner-review URL with the requested key name,
309
+ permissions, and optional predecessor prefilled. It never creates or returns a
310
+ key; the workspace owner reviews the form, creates the replacement in the
311
+ browser, and copies it into the client. Pass `replaceApiKeyId: "current"` to
312
+ offer revocation of the active key after the replacement is created. If the
313
+ active key also lacks `account:read`, use the dashboard directly.
314
+
315
+ The default **Safer agent access** preset includes `lists:write` and
316
+ `tags:write`, so agents can create and update list and tag definitions, and it
317
+ includes `subscribers:tag` for applying tags to existing contacts. It also
318
+ includes `ab_tests:read`, `ab_tests:write`, and `sequences:write`, so agents can
319
+ audit and edit sequence A/B variant copy, including cart and browse abandonment
320
+ messages. It does not include `subscribers:write`, so it cannot add contacts to
321
+ lists or remove them from lists. Deleting a list or tag still requires the
322
+ matching `lists:delete` or `tags:delete` permission.
323
+
324
+ The AI drafting preset includes `subscribers:write`, so drafting agents can
325
+ build a list as well as create it. Imports that apply `listIds` also need
326
+ `lists:write`; sequence enrollment or double-opt-in delivery additionally needs
327
+ `automations:trigger`.
328
+
329
+ ## Tools
330
+
331
+ The standard surface currently exposes 243 MCP tools. The OpenAI-reviewed
332
+ surface exposes 237; only the six operations listed above are omitted.
333
+
334
+ Tools reject arguments they do not declare instead of silently ignoring them.
335
+ Errors name the unsupported fields, list the supported arguments, and provide
336
+ focused guidance for common mistakes such as invented subscriber filters or
337
+ sort options.
338
+
339
+ ### Account, Companies, Setup
340
+
341
+ | Tool | Description |
342
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
343
+ | `get_account` | Get account info, available companies, current key permissions, and the API Keys management URL. |
344
+ | `select_company` | Set the active company for future tool calls. |
345
+ | `get_app_urls` | Build dashboard URLs for campaigns, landing pages, sequences, emails, settings, subscription management, domains, and sent email details. `settingsTab: "billing"` resolves to Account -> Subscription. |
346
+ | `create_company` | Create a new company or brand. |
347
+ | `get_company` | Read company details, product info, brand context, localization, reply-tracking settings, current From/Reply-To defaults, and the effective read-only `emailBranding` entitlement with plan/status reason and subscription URL; STO is explicitly identified as campaign-only. |
348
+ | `update_company` | Edit product info, brand context, email theme, reply tracking, and account-wide From/Reply-To profile defaults or names. |
349
+ | `get_sync_rules` | Read the company's event-to-tag rules and whether it uses the inherited platform preset. |
350
+ | `update_sync_rules` | Replace all sync rules; pass `[]` to disable them or `null` to opt into the SaaS/ecommerce platform preset. |
351
+ | `get_shopify_automation_settings` | Read browse-abandonment, cart-abandonment, and price-drop settings for the connected Shopify store. |
352
+ | `update_shopify_automation_settings` | Partially update Shopify automation settings or reset an individual section to its platform defaults. |
353
+ | `create_api_key` | Create a company API key and return its one-time secret on standard MCP; omitted from the OpenAI-reviewed route. |
354
+ | `request_api_key_handoff` | Prepare an owner-reviewed create/rotation URL when the active key cannot manage API keys itself. |
355
+ | `list_api_keys` | List company API keys as non-secret metadata for safe identification and cleanup. |
356
+ | `update_api_key` | Rename a company API key or replace its permission preset or scopes without changing the key value. |
357
+ | `revoke_api_key` | Permanently revoke an exact company API key by ID after checking it with `list_api_keys`. |
358
+ | `delete_api_key` | Compatibility alias for `revoke_api_key`. |
359
+ | `list_websites` | List sending domains with stored aggregate, SPF, DKIM, and MAIL FROM status. |
360
+ | `add_sending_domain` | Add a sending domain and return its cohort-specific DNS setup records. |
361
+ | `add_website` | Compatibility alias for `add_sending_domain`. |
362
+ | `check_website` | Read a sending domain's stored SPF, DKIM, MAIL FROM, and aggregate verification details. |
363
+ | `verify_sending_domain` | Run a fresh sending-domain DNS/provider verification and return current status and diagnostics. |
364
+ | `list_integrations` | List connected integrations with connection and sync health, without returning credentials. |
365
+ | `get_sending_status` | Diagnose active, paused, or suspended sending, including enforcement denominators, review gates, and remediation steps. |
366
+ | `resume_sending` | Restore an eligible hard-bounce pause after explicitly confirming the list has been sanitized. |
367
+ | `get_tracking_settings` | Read account-wide and Transactional API open/click defaults, unsubscribe, attribution, UTM, click-domain, reply-tracking, and double-opt-in settings. |
368
+ | `update_tracking_settings` | Update account-wide and Transactional API tracking defaults, attribution, UTM, and account-wide double opt-in. |
369
+ | `get_integration_guide` | Get framework-specific integration examples. |
370
+ | `get_integration` | Inspect one connected integration, its event wiring, list targeting, recent activity, and recommendations. |
371
+ | `list_integration_capabilities` | Compare provider capabilities whether or not they are connected. |
372
+ | `connect_integration` | Connect supported API-key or webhook-secret providers on standard MCP; omitted from the OpenAI-reviewed route. |
373
+ | `get_event_schema` | Inspect published event payload examples, property paths, types, and merge tags by provider. |
374
+ | `list_integration_activity` | Read the retained integration-specific webhook and sync activity log. |
375
+ | `set_integration_sync_enabled` | Enable or disable bulk imports and backfills while leaving live webhooks connected. |
376
+ | `set_integration_list_targeting` | Choose which lists contacts created by a supported integration join on future provider writes. |
377
+ | `sync_integration` | Queue payment revenue, Supabase users, or a PostHog/Segment event-history import using the saved integration configuration. |
378
+ | `get_integration_pixel` | Read Shopify's live pixel/configuration state and distinguish confirmed dark events from an unknown read. |
379
+ | `activate_integration_pixel` | Install or repoint Shopify's storefront pixel; idempotent when it is already current. |
380
+ | `list_web_tracking_keys` | List publishable website-tracking keys, origin restrictions, usage state, and install snippets. |
381
+ | `get_web_tracking_key` | Get one website-tracking key with its exact install snippet and ingest endpoint. |
382
+ | `create_web_tracking_key` | Create a publishable tracking key for a non-Shopify storefront or website. |
383
+ | `update_web_tracking_key` | Rename, restrict, revoke, or re-enable a website-tracking key. |
384
+ | `delete_web_tracking_key` | Permanently delete a website-tracking key after its snippet has been removed. |
385
+ | `list_sender_profiles` | List sender and reply-to profiles, defaults, and sending-domain readiness. |
386
+ | `update_sender_profile` | Rename one sender or reply-to profile without changing the account defaults. |
387
+ | `delete_sender_profile` | Permanently delete an unused sender profile, with guards for live sending surfaces and the last remaining sender. |
388
+ | `get_notification_preferences` | Read the current user's per-company account notification settings and supported modes, including the Monday weekly report. |
389
+ | `update_notification_preferences` | Update the current user's account notification delivery modes, including weekly-report opt-out, without affecting teammates. |
390
+ | `render_email` | Render final email-safe HTML and diagnose unresolved merge tags, including typos hidden by defaults. The OpenAI-reviewed route accepts sample data or a policy-checked inline subscriber, not a stored subscriber ID. |
391
+
392
+ `get_sending_status` keeps the Postgres-backed pause state, review gates, and
393
+ remediation available when sender-health analytics are temporarily unavailable;
394
+ in that degraded case `senderHealth` is `null`.
395
+
396
+ `render_email` returns `unresolvedMergeTags` so callers can distinguish an
397
+ unknown name from a recognized tag that is merely blank for the previewed
398
+ contact. Unknown names are reported even when a `default` filter supplied text:
399
+ for example, `{{ subscriber.frstName | default: "there" }}` renders a plausible
400
+ greeting for every contact while bypassing stored first names. A recognized
401
+ name that is blank for one contact is not reported when its default is used.
402
+ The OpenAI-reviewed route rejects restricted custom-attribute selectors inside
403
+ merge tags. It also omits the `subscriberId` argument; use a policy-checked
404
+ inline `subscriber`, or omit subscriber data for a sample preview.
405
+
406
+ To render a sequence step whose `nodeType` is `action_ab_test`, pass the
407
+ step's `sequenceId` and `nodeId` together with a `variantId` from
408
+ `get_sequence.sequence.emails[].abTest.variants`. These steps have no email of
409
+ their own, so the variant is required; reading and rendering their competing
410
+ copy also requires the `ab_tests:read` scope.
411
+
412
+ For Supabase, `sync_integration` reuses the project, schema, table, list
413
+ selection, and consent mappings saved in the dashboard. It cannot target an
414
+ arbitrary table. Run it after installing the live database trigger to import
415
+ users who existed before the trigger was installed, then poll `get_integration`
416
+ and `list_integration_activity` for progress and row-level outcomes.
417
+
418
+ `set_integration_sync_enabled` controls bulk imports and backfills only; it
419
+ does not stop a provider's live webhook from creating contacts. Use
420
+ `set_integration_list_targeting` to choose their future list memberships:
421
+ `null` follows workspace defaults, `[]` joins no list, and a populated array
422
+ targets those lists. The change is not retroactive and never removes existing
423
+ memberships. It also does not stop default `any_contact` sequences, which
424
+ enroll list-less contacts; explicit `any_list` and specific-list sequences
425
+ require a matching membership. Pair list targeting with
426
+ `pause_sequence_enrollments` when those default enrollments must stop too.
427
+ Supabase, Stripe, Shopify, Wix, and Webflow support this control.
428
+
429
+ For PostHog, `sync_integration` restarts the event-history import from the
430
+ beginning with the stored personal API key. Imported events are deduplicated, so
431
+ retrying a failed import does not create duplicates.
432
+
433
+ For Segment, `connect_integration` on standard MCP can optionally import recent
434
+ event history from Unify after the live webhook is connected. The import walks
435
+ existing contacts through the Profile API, covers the API's most recent 14 days,
436
+ skips contacts without a matching profile, and safely deduplicates retries and
437
+ live webhook overlap. New connections skip automatic page/screen calls unless
438
+ those names are explicitly allowlisted. Segment webhook secrets must be 16-153
439
+ UTF-8 bytes. On the OpenAI-reviewed route, which omits `connect_integration`,
440
+ connect Segment in the dashboard or local CLI instead. Use `sync_integration`
441
+ to retry with the saved credentials.
442
+
443
+ For Attio, `connect_integration` on standard MCP accepts a workspace access
444
+ token without a webhook secret, with optional `settings.listMap` as a map of
445
+ Sequenzy list IDs to Attio people-list UUIDs or API slugs, plus
446
+ `syncCompanyFromDomain` to control company matching from non-free-mail domains.
447
+ On the OpenAI-reviewed route, connect Attio in the dashboard or local CLI, then
448
+ use `update_attio_settings` for the same settings. The integration is
449
+ outbound-only:
450
+ new joins to mapped Sequenzy lists upsert the person and add them to the Attio
451
+ list; list removals do not remove records from Attio.
452
+
453
+ Call `get_event_schema` before writing an `{{event.*}}` merge tag or an event
454
+ property filter. Omit `eventName` to list documented built-in events; provide
455
+ an event name to receive provider-specific example payloads and property paths,
456
+ and optionally filter by `provider`. Custom event names remain valid even when
457
+ the result reports `documented: false`; that only means no reference sample is
458
+ published. Use integration activity or sequence enrollments for actual delivery
459
+ data because this tool returns static reference data.
460
+
461
+ For a new sending domain, call `add_sending_domain`, publish the DNS records in
462
+ the returned `website.dnsRecords`, wait for DNS propagation, and then call
463
+ `verify_sending_domain`. Publish every returned record instead of assuming a
464
+ fixed provider or record count: unified domains include required DMARC, while
465
+ legacy domains can return Amazon SES MAIL FROM and inbound-reply records. If
466
+ verification is attempted before creation, the error points back to
467
+ `add_sending_domain` with the requested domain.
468
+
469
+ For Shopify, call `get_integration_pixel` before relying on product views,
470
+ cart activity, or browse-abandonment triggers. The result is read live from
471
+ Shopify because merchants can remove the pixel independently. If
472
+ `pixel.healthy` is false, `dependentEvents` names the triggers that cannot
473
+ arrive; call `activate_integration_pixel` to install or repoint the pixel.
474
+ Activation is idempotent, and events begin on the next storefront visit rather
475
+ than being backfilled.
476
+
477
+ For custom, headless, ticketing, or SaaS websites, use
478
+ `list_web_tracking_keys` before relying on product-view or cart triggers. Create
479
+ a key with an explicit origin allowlist, install the returned `installSnippet`,
480
+ then have the customer's authenticated backend mint a short-lived proof through
481
+ `POST /api/v1/web-tracking-identities` and call
482
+ `sequenzy.identify(email, identityToken)` at sign-in or checkout. A publishable
483
+ key alone only records anonymous activity and cannot trigger subscriber
484
+ automation. The returned snippet installs synchronous method stubs before its
485
+ async loader, so identity and event calls made during page bootstrap are queued
486
+ until the SDK is ready. Prefer revoking a key with `update_web_tracking_key`
487
+ before permanently deleting it.
488
+
489
+ New companies start with no sync rules. The inherited preset remains available
490
+ for SaaS/ecommerce companies by passing `null` to `update_sync_rules`; services
491
+ and consulting companies should normally keep `[]` or define explicit rules.
492
+
493
+ Use `list_sender_profiles` to find the profile ID, then call
494
+ `update_sender_profile` to change only its display name. Pass `type: "reply"`
495
+ for a reply-to profile; sender is the default. The address, sending domain, and
496
+ account-wide default From/Reply-To selections remain unchanged. Renaming
497
+ requires the `companies:manage` scope.
498
+
499
+ Use `delete_sender_profile` to permanently remove an obsolete From identity.
500
+ It refuses the last sender and any profile used by a live campaign, active
501
+ sequence (including a step override), or transactional email. Eligible drafts
502
+ and account defaults move to the returned `fallbackSenderProfileId`; review it
503
+ before sending. Reply-to profiles are not supported by this delete tool.
504
+
505
+ Shopify cart abandonment is enabled by default. It fires
506
+ `ecommerce.cart_abandoned` after one hour of cart inactivity, with a 24-hour
507
+ per-subscriber cooldown. Use `update_shopify_automation_settings` to change the
508
+ `cartAbandonment.enabled`, `delayHours`, or `cooldownHours` fields; pass
509
+ `cartAbandonment: null` to restore those defaults without changing browse
510
+ abandonment or price-drop settings. Timing values must be positive;
511
+ `delayHours` is capped at 168 and `cooldownHours` at 720.
512
+
513
+ ### Subscribers
514
+
515
+ | Tool | Description |
516
+ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
517
+ | `add_subscriber` | Add one subscriber; status is creation-only, so use `update_subscriber` for an existing contact. |
518
+ | `create_subscriber_import` | Queue up to 5,000 full CRM records with an optional retry-safe `idempotencyKey`; enabled email-hygiene checks continue separately after ingestion. |
519
+ | `get_subscriber_import` | Read progress, row outcome counts, and failure summaries for a queued import. |
520
+ | `update_subscriber` | Update native profile and phone fields, SMS consent, attributes, tags, or global status. |
521
+ | `remove_subscriber` | Unsubscribe while preserving suppression history, or permanently delete only with `hardDelete: true`. |
522
+ | `get_subscriber` | Fetch subscriber details by email or external ID. |
523
+ | `search_subscribers` | Search by query, tags, list, status, segment, or one custom attribute, with automatic or resumable pagination. |
524
+ | `trigger_subscriber_event` | Emit one custom event exactly as an integration would, applying sync rules and matching sequence triggers. |
525
+ | `trigger_subscriber_events` | Emit several ordered custom events for one subscriber. |
526
+ | `import_subscriber_events` | Import up to 25 source-identified events across contacts; silent history requires every row for a contact to be over an hour old. |
527
+ | `bulk_add_subscriber_tags` | Add tags to up to 500 existing subscribers; requires `subscribers:tag` and may also require `tags:write`. |
528
+ | `bulk_remove_subscriber_tags` | Remove tags from up to 500 existing subscribers; requires `subscribers:tag` or `subscribers:write`. |
529
+
530
+ Use `create_subscriber_import` for CRM onboarding instead of looping over
531
+ `add_subscriber`. One call accepts 5,000 full records and returns an asynchronous
532
+ import ID; poll it with `get_subscriber_import`. A `completed` import can still
533
+ contain row failures, so inspect `failedCount` and `failedReasons`. Every
534
+ excluded row is accounted for: `skippedReasons` sums to `skippedCount`, and
535
+ `failedReasons` sums to `failedCount`. Report any shortfall with the import ID
536
+ instead of guessing which rows were omitted. When email hygiene is enabled,
537
+ deliverability checks continue separately after ingestion and results appear
538
+ in List health; import status does not wait for or include those verdicts.
539
+ Invalid verdicts are suppressed from later sends. Use `optInMode: "confirmed"`
540
+ only when consent was already verified.
541
+
542
+ For `import_subscriber_events`, email is required when a row may create a new
543
+ contact; `externalId` can stand alone only for an existing contact. Supply a
544
+ stable `eventId` on every row. Retrying reuses the original receipt and
545
+ idempotently re-attempts downstream recovery. Historical classification is per
546
+ contact: if any row for a contact is recent, that contact's whole group uses
547
+ the live side-effect path.
548
+
549
+ For compliance suppression, call `update_subscriber` with
550
+ `status: "unsubscribed"` (or use `remove_subscriber` without `hardDelete`). Do
551
+ not retry `add_subscriber` with a different status: status on that tool applies
552
+ only when the contact is first created, and a mismatched skipped result is
553
+ reported as an error.
554
+
555
+ When `add_subscriber` omits `listIds`, a contact created by the call follows
556
+ the workspace default lists while an existing contact keeps its current list
557
+ memberships. Pass list IDs explicitly when an existing contact should join
558
+ specific lists; pass `[]` to target no lists.
559
+
560
+ `update_subscriber.phone` writes the native phone field shown on the contact,
561
+ not a custom attribute. Pass `smsConsent: true` only after verifying express
562
+ written consent, or `false` to opt the contact out. Changing the phone without
563
+ `smsConsent` resets SMS consent because consent belongs to the old number.
564
+
565
+ `add_subscriber`, `update_subscriber`, and `create_subscriber_import` accept an
566
+ IANA `timezone` such as `America/New_York`. The value is stored on the native
567
+ contact profile and enables recipient-local campaign delivery. Pass an empty
568
+ timezone to `update_subscriber` to clear it; invalid import-row values are
569
+ ignored without rejecting the rest of the import.
570
+
571
+ ### Products & Digital Delivery
572
+
573
+ | Tool | Description |
574
+ | --------------------- | ------------------------------------------------------------------------------------- |
575
+ | `list_products` | List synced products from Stripe, Shopify, WooCommerce, manual, or Commerce API data. |
576
+ | `upsert_products` | Create or update up to 100 Commerce API products keyed by your product ID. |
577
+ | `delete_product` | Delete a product previously pushed through the Commerce API. |
578
+ | `attach_product_file` | Attach a hosted or locally uploaded delivery file to a product. |
579
+ | `remove_product_file` | Remove an attached product delivery file. |
580
+ | `sync_products` | Queue a Stripe product catalog sync, optionally selecting an integration by ID. |
581
+
582
+ After a product delivery file is attached, matching purchase events include `download.url` and `download.name`, so purchase-triggered emails can use merge tags like `{{event.download.url}}`.
583
+
584
+ For Stripe products, `list_products` returns every active price as a variant, with the Stripe price ID in `variantId`. Use that ID to target an exact price in a purchase sequence even when it is not the product's default price.
585
+
586
+ ### Image Assets
587
+
588
+ | Tool | Description |
589
+ | -------------------- | -------------------------------------------------------------------------------------------- |
590
+ | `upload_image_asset` | Upload an email image and return its hosted media record plus a ready-to-insert image block. |
591
+
592
+ The tool accepts PNG, JPEG, GIF, and WebP images up to 5MB. Local stdio clients
593
+ can pass `filePath`. Hosted/remote clients that can access attachment bytes can
594
+ pass `imageBase64` with `filename`. Provide `altText` for accessibility, then
595
+ use `displayWidthPercent`, `cropHeight`, `objectFit` (`cover` or `contain`), and
596
+ `align` to standardize screenshot presentation. The returned `imageBlock` can
597
+ be copied directly into the block array accepted by campaign, sequence,
598
+ template, and transactional-email tools.
599
+
600
+ Authenticated image bytes are always uploaded to the origin configured by
601
+ `SEQUENZY_API_URL`, even if a reverse proxy returns an equivalent upload URL
602
+ under another host. API credentials are never forwarded to that alternate
603
+ origin.
604
+
605
+ ```json
606
+ {
607
+ "filePath": "/Users/me/Desktop/product-results.png",
608
+ "altText": "Product results dashboard",
609
+ "displayWidthPercent": 100,
610
+ "cropHeight": 320,
611
+ "objectFit": "cover",
612
+ "align": "center"
613
+ }
614
+ ```
615
+
616
+ ### Lists, Tags, Segments
617
+
618
+ | Tool | Description |
619
+ | ------------------------------ | ----------------------------------------------------------- |
620
+ | `list_tags` | List all tags. |
621
+ | `create_tag` | Create a tag definition with an optional color. |
622
+ | `update_tag` | Update a tag color. |
623
+ | `delete_tag` | Delete a tag and remove it from subscribers. |
624
+ | `list_lists` | List subscriber lists. |
625
+ | `create_list` | Create a subscriber list. |
626
+ | `update_list` | Rename or describe a subscriber list. |
627
+ | `delete_list` | Delete a subscriber list. |
628
+ | `add_subscribers_to_list` | Add up to 500 subscribers to a list from an email array. |
629
+ | `remove_subscribers_from_list` | Remove up to 500 subscribers from a list. |
630
+ | `list_segments` | List saved segments and counts. |
631
+ | `create_segment` | Create nested or same-element array-filtered segments. |
632
+ | `update_segment` | Update segment name, filters, root group, or join operator. |
633
+ | `delete_segment` | Delete a segment (requires `segments:delete`). |
634
+ | `get_segment_count` | Preview the active subscriber count for a segment. |
635
+
636
+ For subscriber exports, `search_subscribers` accepts `listId`, exact `listName`,
637
+ or `list` (ID first, then exact name). It also accepts `attribute` plus
638
+ `attributeValue`, with `attributeOperator` for `contains`, numeric comparisons,
639
+ or `is_not_empty`; the combined `"attributeName:value"` form remains supported.
640
+ Filters combine with AND; use a saved segment for OR logic, nested groups,
641
+ exclusions, engagement, or event conditions. If `limit` is omitted, the tool
642
+ fetches every matching page automatically. For chunked reads, pass `limit` and
643
+ follow `pagination.nextCursor` (or `pagination.nextOffset`) while `hasMore` is
644
+ true. `offset` and `page` are supported below 1,000,000 skipped matches; use the
645
+ cursor for deeper audiences.
646
+
647
+ For bulk list population, use `add_subscribers_to_list`; the backing API endpoint is `POST /api/v1/lists/{listId}/subscribers` with no `/bulk` suffix:
648
+
649
+ ```json
650
+ {
651
+ "emails": ["ada@example.com", "grace@example.com"],
652
+ "duplicateStrategy": "skip",
653
+ "enrollInSequences": false,
654
+ "optInMode": "default"
655
+ }
656
+ ```
657
+
658
+ Send at most 500 emails per request. Standard API rate limits still apply: 100 requests per minute per API key and 20 requests per second burst. For CSV-driven CLI imports, accepted email headers include `email`, `e-mail`, `email address`, and `mail`; if no recognized header exists, the CLI reads the first column.
659
+
660
+ Segment filters support attributes, events, saved segment membership, engagement events, Stripe product purchase rules, and commerce product purchase rules. Use `filterJoinOperator: "or"` for match-any segments, or pass a v2 `root` group for nested logic.
661
+
662
+ For array-of-object attributes, use wildcard paths such as
663
+ `history_events[].eventvenue_id:2103`. When an AND group also filters
664
+ `history_events[].showing_date`, both conditions must match one shared
665
+ `history_events[]` element; values from unrelated history entries are not
666
+ combined. Deleting a segment requires `segments:delete`; `segments:write` is
667
+ not sufficient.
668
+
669
+ Each segment filter field validates its own operators:
670
+
671
+ - `status`, `segment`: `is`, `is_not`
672
+ - `tag`: `contains`, `not_contains`, `is_empty`, `is_not_empty`
673
+ - `email`: `contains`, `not_contains`
674
+ - `emailProvider`, `list`: `is`, `is_not`, `is_empty`, `is_not_empty`
675
+ - `firstName`, `lastName`: `contains`, `not_contains`, `is_empty`, `is_not_empty`
676
+ - `added`: `less_than`, `more_than`
677
+ - `attribute`: `is`, `is_not`, `is_empty`, `is_not_empty`, `gte`, `lte`, `gt`, `lt`, `contains`, `not_contains`
678
+ - `event`, email engagement fields: `is`, `is_not`, `at_least`, `less_than_count`
679
+ - `emailBounced`: also supports `is_temporary_bounce`, `is_permanent_bounce`
680
+ - `stripeProduct`: `is`, `is_not`, `at_least`, `less_than_count`
681
+ - `stripeCurrentProduct`, `stripeTrialProduct`: `is`, `is_not`, `gte`, `lte`, `gt`, `lt`
682
+ - `commerceProduct`: `is`, `is_not`, `at_least`, `less_than_count`
683
+
684
+ Stripe product filter examples:
685
+
686
+ ```json
687
+ { "field": "stripeProduct", "operator": "is", "value": "prod_pro" }
688
+ { "field": "stripeProduct", "operator": "is_not", "value": "prod_pro" }
689
+ { "field": "stripeProduct", "operator": "at_least", "value": "prod_pro:3" }
690
+ { "field": "stripeProduct", "operator": "less_than_count", "value": "prod_pro:3" }
691
+ ```
692
+
693
+ Commerce product filters match products purchased through commerce orders. Values can be `provider:productId` for provider-scoped IDs (`shopify`, `woocommerce`, or `api`), a bare product ID to match any provider, or `provider:productId:count` for threshold operators:
694
+
695
+ ```json
696
+ { "field": "commerceProduct", "operator": "is", "value": "api:starter-kit" }
697
+ { "field": "commerceProduct", "operator": "at_least", "value": "shopify:42:2" }
698
+ ```
699
+
700
+ Engagement fields such as `emailSent`, `emailDelivered`, `emailOpened`, `emailClicked`, `emailBounced`, and `emailComplained` accept rolling windows like `7d`, `30d`, `90d`, `180d`, or `all`. Presence operators can scope by delivery policy with `marketing:<timeRange>` (marketing-policy campaign, automation, and Send API traffic) or `transactional:<timeRange>` (transactional-policy sends); policy scopes require a send-time policy snapshot, so ambiguous older automation and Send API events remain available only through unscoped filters. `emailBounced` also supports scoped values with `is_temporary_bounce` and `is_permanent_bounce`. With `at_least` and `less_than_count`, use `count:timeRange`, such as `10:30d` or `10:all`. Presence operators can instead use a campaign scope like `campaign:cmp_123`; campaign and email-type scopes cannot be combined with count operators.
701
+
702
+ ### Audience Syncs (Meta Ads)
703
+
704
+ | Tool | Description |
705
+ | ---------------------- | -------------------------------------------------------------------- |
706
+ | `list_audience_syncs` | List segment-to-audience syncs with schedule and last sync status. |
707
+ | `list_ad_accounts` | List the Meta ad accounts available for syncing. |
708
+ | `create_audience_sync` | Push a segment to a Meta custom audience on a schedule. |
709
+ | `update_audience_sync` | Change sync frequency (`hourly`, `daily`, `weekly`) or pause/resume. |
710
+ | `delete_audience_sync` | Remove a sync mapping; the Meta audience itself is kept. |
711
+ | `sync_audience_now` | Trigger an immediate upload outside the regular schedule. |
712
+
713
+ Requires the Meta Ads integration to be connected in the Sequenzy dashboard (Settings -> Integrations). `create_audience_sync` accepts an existing segment (`segmentId`) or a ready-made template (`predefinedSegmentId`, for example `zero-ltv`, `no-purchase-1y`, `recent-buyers`, `high-spenders-ecom`, `non-buyers`, `engaged`) - the template segment is created automatically on first use, and the first upload runs immediately.
714
+
715
+ Audiences are add-only: subscribers who later leave the segment stay in the Meta audience. Meta requires 100+ matched people before an audience can be used for ad delivery.
716
+
717
+ ### Templates
718
+
719
+ | Tool | Description |
720
+ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
721
+ | `list_templates` | List templates with localization status, label and `isTemplate` filtering, and pagination. |
722
+ | `get_template` | Read template details, content, and localized variants. |
723
+ | `create_template` | Create templates from a prompt, HTML, or Sequenzy blocks; use `isTemplate: true` to save a reusable master design. |
724
+ | `update_template` | Update template metadata, inbox preview text, labels, HTML, or blocks; mark or unmark a master with `isTemplate`. |
725
+ | `set_template_localization` | Create or replace a caller-supplied localized variant. |
726
+ | `sync_template_localizations` | Queue AI translation for selected or all enabled non-primary locales. |
727
+ | `delete_template` | Delete a template. |
728
+
729
+ `list_templates` returns 50 email bodies newest first by default and accepts a
730
+ `limit` up to 100. Advance `offset` by `pagination.count` while
731
+ `pagination.hasMore` is true; `pagination.total` reports the full matching
732
+ count, including campaign and transactional-email bodies.
733
+
734
+ Set `isTemplate: true` on `list_templates` to return only saved master designs,
735
+ or `false` to return ordinary email bodies. Marked masters are offered as
736
+ starting points for dashboard sequence steps and campaigns; starting from one creates
737
+ an independent copy so edits leave the master intact.
738
+
739
+ Standalone/sequence source-design copying and AI rewriting within a selected layout are currently
740
+ dashboard-only. This release intentionally keeps those workflows in interactive
741
+ authoring, where users can review the source, translations, and any fallback copy
742
+ before saving a sequence step. REST, CLI, and MCP expose no equivalent standalone/sequence source-design
743
+ operation. `create_template` with `prompt` generates new content without preserving
744
+ an existing layout; supplied HTML or blocks create a new body without automatically
745
+ copying localized variants. See the [interface availability documentation](https://docs.sequenzy.com/concepts/email-templates#availability-across-interfaces).
746
+
747
+ Campaign copies already work through REST `POST /api/v1/campaigns` and MCP
748
+ `create_campaign` with `templateId`; it cannot be combined with `prompt` for an AI rewrite.
749
+
750
+ For net-new content requested in natural language, pass `prompt` so Sequenzy
751
+ generates branded native blocks server-side. Use `blocks` only for finished
752
+ caller-supplied Sequenzy content, and use `html` only when preserving supplied
753
+ or explicitly requested markup. `prompt`, `blocks`, and `html` are mutually
754
+ exclusive; `style` and `tone` are valid only with `prompt`.
755
+
756
+ Use `set_template_localization` when translated copy comes from your own
757
+ localization workflow. It requires an enabled non-primary `locale`, a localized
758
+ `subject`, and exactly one of `html` or `blocks`. Use
759
+ `sync_template_localizations` to ask Sequenzy to translate selected locales;
760
+ omit `locales` to sync every enabled non-primary locale. Explicit sync works
761
+ even when automatic on-save localization is disabled.
762
+
763
+ ### Reusable Email Components
764
+
765
+ | Tool | Description |
766
+ | ----------------------------- | ------------------------------------------------------------------------------ |
767
+ | `list_email_components` | List saved sections and footers, optionally limited to pinned defaults. |
768
+ | `get_email_component` | Read one component's blocks, metadata, version, and default-slot state. |
769
+ | `get_default_email_component` | Read the component currently pinned to a default slot such as `footer`. |
770
+ | `set_default_email_component` | Create or replace the company default footer used by newly built block emails. |
771
+ | `create_email_component` | Save a reusable section or footer from a block list. |
772
+ | `update_email_component` | Update component metadata or replace its blocks and increment its version. |
773
+ | `delete_email_component` | Delete a component without changing emails that already copied its blocks. |
774
+
775
+ Components are copied into emails when those emails are built, so later edits
776
+ affect newly built emails rather than rewriting existing content. The default
777
+ footer keeps its unsubscribe link enabled, while transactional rendering hides
778
+ that link. Raw HTML emails keep their own markup and do not receive block
779
+ components; their send-time unsubscribe handling remains unchanged.
780
+
781
+ ### A/B Tests
782
+
783
+ | Tool | Description |
784
+ | ------------------------ | ------------------------------------------------------------------------------ |
785
+ | `list_ab_tests` | List A/B tests and variants, optionally scoped by sequence. |
786
+ | `get_ab_test` | Get effective settings, variants, localization status, and sequence-step copy. |
787
+ | `get_ab_test_stats` | Get aggregate and per-variant stats. |
788
+ | `restart_ab_test` | Restart a stopped or completed A/B test. |
789
+ | `select_ab_test_winner` | Select a campaign test winner and queue remaining delivery. |
790
+ | `update_ab_test` | Update campaign or sequence winner-selection settings. |
791
+ | `update_ab_test_variant` | Update campaign draft or sequence variant copy. |
792
+ | `create_ab_test` | Create a campaign test or convert a sequence email step. |
793
+ | `add_ab_test_variant` | Add a variant to an existing A/B test. |
794
+ | `delete_ab_test_variant` | Delete a draft A/B test variant. |
795
+ | `delete_ab_test` | Delete an A/B test. |
796
+
797
+ Use `get_sequence.sequence.emails[].abTest.variants` to discover sequence variant IDs, subjects, preview text, and block counts; call `get_ab_test` to audit every variant's full `blocks`, effective `settings`, localization status, or stats. Campaign settings use `testPercentage`, `testDurationMinutes`, and `winnerCriteria`; sequence settings use `testType`, `winnerThreshold`, and `winnerCriteria`. The legacy sequence values `testPercentage: 100` and `testDurationMinutes: 0` are compatibility sentinels, not runtime settings. `select_ab_test_winner` applies only to a campaign test that is currently testing and immediately queues the winning variant for the remaining audience. `update_ab_test` changes the appropriate settings model and requires `confirmLiveChange: true` when sequence settings affect an active or already-used test. Variant updates accept either `html` or `blocks`, not both.
798
+
799
+ `create_ab_test` accepts exactly one of `campaignId` or `automationNodeId`; the latter requires one to four extra variants and converts a sequence email node into `action_ab_test`. The conversion moves the step's subject, preview text, and blocks onto independent variant emails. Get the test and variant IDs from `get_sequence`, read every variant's copy with `get_ab_test`, and edit each one with `update_ab_test_variant`; `update_sequence_node` and `update_template` cannot edit variant copy, and a change intended for the whole step must be repeated for every variant. If `update_ab_test_variant` is not in the MCP tool list, enable it on the Sequenzy connector rather than writing through another email tool. The full workflow requires `ab_tests:read`, `ab_tests:write`, and `sequences:write`, all included in **Safer agent access**. With only `sequences:read`, `get_sequence` keeps the A/B step and control copy visible but redacts test-record fields and returns an empty variant list. An explicit sequence `winnerCriteria` overrides the `testType` default, so content variants can still be judged by opens. Pass `confirmLiveChange: true` when converting a node in an active sequence. Together with control A, an A/B test supports at most five variants. Sequence variants receive independent email templates and can be edited after creation; once the sequence is active or the test has activity, `update_ab_test_variant` requires `confirmLiveChange: true`. Variants can only be added or removed while the test is a draft, and live-sequence changes also require confirmation because they immediately change the rotation.
800
+
801
+ ### Campaigns
802
+
803
+ | Tool | Description |
804
+ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
805
+ | `list_campaigns` | List paginated campaigns by status or label, including reviewer feedback and delivery-pacing fields for account-wide STO audits. |
806
+ | `get_campaign` | Get details, stats, reviewer feedback, and recorded delivery pacing for a campaign. |
807
+ | `get_campaign_audience` | Resolve saved targeting, missing references, a plain-language summary, and live recipient count. |
808
+ | `list_campaign_goals` | List the conversion goals persisted for one email campaign (SMS is unsupported). |
809
+ | `create_campaign_goal` | Add an event, subscriber-attribute, or tag-applied email-campaign conversion goal. |
810
+ | `update_campaign_goal` | Update a persisted email-campaign conversion goal. |
811
+ | `delete_campaign_goal` | Delete a persisted email-campaign conversion goal. |
812
+ | `list_email_sends` | Search recent delivery history with resource IDs and URLs, optionally scoped to one sequence step. Successful live-test sends are omitted. |
813
+ | `get_email_send` | Inspect a queued, test, sent, suppressed, or failed delivery by durable email-send ID. |
814
+ | `list_recipient_suppressions` | List associated suppressed recipients, including protected global invalid addresses and complaints. |
815
+ | `get_recipient_suppression` | Check local bounce, complaint, email-hygiene, and regional SES suppression for one exact recipient. |
816
+ | `remove_recipient_suppression` | Remove a workspace soft-bounce escalation while preserving global, hard-bounce, and complaint protections. |
817
+ | `create_campaign` | Create a campaign with content, data, and optional From/Reply-To identity overrides. |
818
+ | `update_campaign` | Update a draft campaign, including content, data, identities, audience, and persisted STO configuration. |
819
+ | `schedule_campaign` | Schedule or reschedule a campaign, optionally overriding STO and its 1-24 hour delivery window. |
820
+ | `send_test_email` | Send a test email to one address. |
821
+ | `render_email` | Render exact email-safe HTML and report unresolved tags, including typos hidden by defaults. |
822
+ | `cancel_campaign` | Cancel a scheduled or sending campaign. |
823
+ | `pause_campaign` | Pause a sending campaign. |
824
+ | `resume_campaign` | Resume a paused campaign, optionally spreading delivery over time. |
825
+ | `delete_campaign` | Delete a campaign. |
826
+ | `duplicate_campaign` | Duplicate a campaign into a new draft. |
827
+ | `resend_campaign_to_non_openers` | Create a draft resend for the original audience members who did not open a sent campaign. |
828
+
829
+ Prompt-created campaigns are generated and persisted in one API request and
830
+ remain drafts. Use `templateId`, `blocks`, or `html` only when copying or
831
+ preserving existing content rather than asking the agent to author it. Omit all
832
+ content fields to create an empty draft for later editing.
833
+
834
+ Campaign goals credit recipients who were actually sent that campaign within
835
+ the configured attribution window; an open or click remains the stronger
836
+ last-touch signal when one exists. Event goals require `triggerEventName`,
837
+ subscriber-attribute goals require `attributePath`, and tag-applied goals
838
+ require `triggerTagName`. The campaign attribution window defaults to 168
839
+ hours when omitted.
840
+
841
+ To deliver at the same wall-clock time in every recipient's own timezone, call
842
+ `schedule_campaign` with `sendInRecipientTimezone: true` and an IANA
843
+ `scheduledTimezone` that identifies the wall clock represented by
844
+ `scheduledAt`. Contacts without a stored timezone receive the campaign at the
845
+ `scheduledAt` instant. This mode cannot be combined with recurring or spread
846
+ delivery.
847
+
848
+ Send Time Optimization is configured per campaign, not at the company or
849
+ sequence level. Audit it across campaigns with `list_campaigns`, or inspect one
850
+ campaign with `get_campaign`. Set `sendTimeOptimization` and
851
+ `sendTimeWindowHours` (1-24, default 12) on a draft with `update_campaign`, or
852
+ override them while scheduling with `schedule_campaign`. `spreadOverHours`
853
+ takes precedence and disables STO, as does recipient-timezone delivery.
854
+ Sequences instead use `sendingWindow`, a shared allowed-hours/days gate rather
855
+ than per-recipient predicted send times.
856
+
857
+ For campaign- and sequence-level identities, `fromEmail` plus `fromName`
858
+ selects the sender identity with that display name on the mailbox, creating it
859
+ when needed without renaming other same-address identities. A Reply-To address
860
+ instead has one company-wide saved name: when `replyToName` differs from that
861
+ name, the saved name is kept and the successful response includes recovery
862
+ guidance in `warnings`.
863
+
864
+ `send_email` and `send_test_email` return a durable `emailSendId`. Use
865
+ `list_email_sends` to discover recent IDs by subject/title, recipient, delivery
866
+ status, type, bounce type, or source; pass an ID to `get_email_send` to inspect
867
+ `status`, `errorMessage`, the stored body, and delivery events. Delivery-list
868
+ rows are retained for 14 days. Successful live-test and other test sends are
869
+ omitted so they do not bury real deliveries. Replies to those test sends show
870
+ in `list_conversations` only when inbound reply capture is enabled. Queue jobs
871
+ are internal execution details and
872
+ are not exposed through the MCP contract. Every returned delivery has a direct
873
+ dashboard `url`. Use `list_recipient_suppressions` to distinguish protected
874
+ global invalid-recipient, protected company hard-bounce, and complaint rows from removable company soft-bounce
875
+ escalations, and use `get_recipient_suppression` for the exact regional status.
876
+ `remove_recipient_suppression` removes only the company escalation; global and
877
+ Amazon SES account-level suppressions, complaints, unsubscribes, and email-hygiene
878
+ protections remain intact. A local hygiene result uses the `bounced` reason with
879
+ `email_hygiene` as its source without changing the subscriber's consent status.
880
+
881
+ Agents should pass a caller-owned `idempotencyKey` to `send_email` before the
882
+ first attempt and reuse it for every retry of that same logical email. Sequenzy
883
+ returns the original `emailSendId` for 14 days instead of creating another
884
+ delivery. Reusing the key with different send arguments is rejected, so do not
885
+ generate a fresh key inside a retry loop.
886
+
887
+ Email blocks may use conditional display rules or `conditional-group` branches.
888
+ Conditions support render-time variables and subscriber attributes plus live
889
+ subscriber data such as segment/list membership, tags, events, engagement,
890
+ subscription/SMS status, and Stripe or commerce purchases. Live-data
891
+ conditions use the same field values and operators as segment filters;
892
+ recipients without a stored subscriber match use the OTHERWISE branch.
893
+
894
+ Core block shapes are `{ "type": "heading", "content": "Title", "level": 1
895
+ }`, `{ "type": "text", "content": "<p>Copy</p>" }`, `{ "type": "button",
896
+ "text": "Book a call", "url": "https://example.com", "variant": "primary" }
897
+ `, and `{ "type": "image", "src": "https://...", "alt": "Description",
898
+ "width": 100, "widthType": "percent" }`. Buttons also accept `content` as an
899
+ alias for `text` and default to the `primary` variant. Image `widthType` accepts
900
+ `percent` or `px`.
901
+
902
+ YouTube video blocks accept an optional custom cover: `{ "type": "video",
903
+ "videoUrl": "https://www.youtube.com/watch?v=...", "thumbnailUrl":
904
+ "https://cdn.example.com/cover.jpg", "alt": "Watch the product tour" }`.
905
+ Replacing blocks without `thumbnailUrl` restores YouTube's own still while
906
+ keeping `videoUrl` as the click destination.
907
+
908
+ Raw `html` is stored as one opaque block. It preserves supplied markup but does
909
+ not add a company logo, native branded sections, or theme-driven block design.
910
+ Use `prompt` for a new branded draft or `blocks` for editor-native design; MCP
911
+ authoring results include a warning when raw HTML is used.
912
+
913
+ Use `update_company` with `fromEmail` and/or `replyTo` to set account-wide
914
+ defaults. `fromEmail` must use a configured, verified sending domain; `replyTo`
915
+ may be any valid mailbox. `create_campaign`, `update_campaign`,
916
+ `create_sequence`, and `update_sequence` accept the same direct-address fields
917
+ for resource-specific overrides and create the backing profile when needed.
918
+ Send `fromName` or `replyToName` alone to rename the existing default profile
919
+ without changing its address. When an address has multiple display names, use
920
+ `senderProfileId` or `replyProfileId` from `list_sender_profiles` to select the
921
+ exact profile to make default and rename.
922
+
923
+ `update_company` also manages the company's default email theme through
924
+ `emailTheme` (`presetId`, `colors`, `typography`, `layout`). Theme updates are
925
+ partial - omitted fields keep their current value (or the preset default) and
926
+ numeric values are clamped to supported ranges. Pass `emailTheme: null` to
927
+ reset the company to the platform default theme. Layout settings can control
928
+ the shared `baseRadius` and a separate `buttonRadius`. Within `colors`,
929
+ `background` paints the outer canvas, `content` paints the inner content card,
930
+ and `surface` paints nested cards or tinted tiles. Omitting `content` preserves
931
+ its current value; when no content color is stored, the card follows
932
+ `background`.
933
+
934
+ Reply tracking is available on the same company tools. Use
935
+ `replyTrackingEnabled`, `replyTrackingDomainMode` (`sequenzy` or `custom`), and
936
+ `forwardReplies` with `update_company`. Company reads also return the current
937
+ read-only `replyRetentionDays` value.
938
+
939
+ Polls and NPS surveys are native email blocks, so they work anywhere an email
940
+ tool accepts `blocks`, including campaigns, templates, A/B variants,
941
+ transactional templates, and sequence email steps. Transactional poll sends
942
+ must resolve to exactly one effective recipient after suppression filtering and
943
+ recipient deduplication, and that recipient must already exist as a subscriber;
944
+ otherwise Sequenzy rejects the send because the answer link cannot be safely
945
+ attributed. Use an answer-button poll:
946
+
947
+ ```json
948
+ {
949
+ "type": "poll",
950
+ "variant": "options",
951
+ "question": "What did you think of this email?",
952
+ "options": [
953
+ { "label": "Loved it", "value": "loved" },
954
+ { "label": "Not for me", "value": "not_for_me" }
955
+ ],
956
+ "attributeKey": "email_feedback"
957
+ }
958
+ ```
959
+
960
+ For NPS, use `"variant": "nps"`, an empty `options` array, and an attribute
961
+ such as `nps_score`. The scale is always 0-10; optional `npsLowLabel` and
962
+ `npsHighLabel` customize its captions. Each answer updates the subscriber
963
+ attribute and fires `poll.answered` for automations and outbound webhooks.
964
+
965
+ Set `"allowMultiple": true` on a text-only options poll to open a hosted page
966
+ where recipients can check several answers and save the whole selection at
967
+ once. The subscriber attribute stores the selected-value list, so attribute
968
+ segments should use `contains`. Multi-select polls cannot use option images or
969
+ configurations whose encoded signed links exceed the delivery-safe size limit.
970
+ Campaign poll summaries set `allowMultiple: true`, use respondent count for
971
+ `totalResponses`, and can report answer percentages that add up past 100%.
972
+
973
+ Poll blocks also support brand-specific styling. `accentColor` recolors every
974
+ appearance, including `"brutal"`; `optionRadius` sets answer-button corners in
975
+ pixels (`0` is square), independently of the container's
976
+ `styles.borderRadius`; and `questionColor` recolors only the question.
977
+ `fontFamily` applies to the poll. Use the `optionFontSize`,
978
+ `optionFontWeight`, `optionLetterSpacing`, and `optionTextTransform` fields for
979
+ answers, or the matching `question*` fields for the question. Sizes and
980
+ spacing are pixels, weights range from 100 to 900, and text transforms are
981
+ `"none"` or `"uppercase"`.
982
+
983
+ ### Saved Forms
984
+
985
+ | Tool | Description |
986
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
987
+ | `list_forms` | List saved forms with their server-managed audience settings, content blocks, and public action URLs. |
988
+ | `create_form` | Create and publish a saved form with standard email/name fields, audience settings, theme, and success behavior. |
989
+ | `update_form` | Update a saved form, including its complete ordered block array and typed custom fields. |
990
+ | `get_form_embed` | Return the public action URL, hosted JavaScript, minimal native form, and fetch example for a saved form. |
991
+
992
+ For Astro, Hugo, Jekyll, Cloudflare Pages, Netlify, GitHub Pages, or any other
993
+ static site, call `list_forms`, use `create_form` if a suitable form does not
994
+ exist, then call `get_form_embed`. The returned opaque `formId` is the public
995
+ capability: lists, tags, duplicate behavior, and success handling remain
996
+ server-side, so the deployed browser code never contains a Sequenzy API key.
997
+ Generated native and standalone markup includes "Powered by Sequenzy" for free
998
+ workspaces; paid workspaces receive unbranded markup. The API resolves that
999
+ entitlement server-side, so callers should use the returned snippet unchanged.
1000
+ When updating a form, omitted fields remain unchanged and theme fields merge
1001
+ into the current theme. Pass an empty `tagIds` array to clear tags or an empty
1002
+ `redirectUrl` to restore confirmation-message behavior. The `blocks` field is
1003
+ a complete replacement, so read the current content with `list_forms` first
1004
+ and retain exactly one required email field and one submit button. Add custom
1005
+ inputs as `form-field` blocks with a supported `fieldType`; select, radio, and
1006
+ checkbox fields require options, while hidden defaults are enforced server-side.
1007
+
1008
+ ### Saved Popups
1009
+
1010
+ | Tool | Description |
1011
+ | ----------------- | ------------------------------------------------------------------------------------------------- |
1012
+ | `list_popups` | List saved popups with status and engagement stats, optionally including full content. |
1013
+ | `get_popup` | Get one popup's blocks, trigger, targeting, schedule, frequency, theme, and published embed code. |
1014
+ | `create_popup` | Create a popup from a starting template, published by default, and return its deployment script. |
1015
+ | `update_popup` | Partially update popup copy, audience, behavior, theme, blocks, or publication status. |
1016
+ | `get_popup_embed` | Return secret-free HTML, React/Next.js, WordPress, and Shopify embed snippets. |
1017
+ | `duplicate_popup` | Copy a popup into a draft with independent engagement counters. |
1018
+ | `delete_popup` | Permanently delete a popup and its engagement counters. |
1019
+
1020
+ Popup deployment uses one public script tag; API keys, audience settings,
1021
+ triggering, targeting, scheduling, and frequency rules remain server-side.
1022
+ Popups capture into every list by default unless `listIds` is provided. When
1023
+ updating blocks, read the popup first and send the complete replacement array,
1024
+ retaining exactly one required email field and one submit button. Setting
1025
+ `status` to `draft` stops a popup without invalidating its existing embed code.
1026
+
1027
+ ### Landing Pages
1028
+
1029
+ | Tool | Description |
1030
+ | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
1031
+ | `list_landing_pages` | List landing pages with status, metrics, content, and URLs. |
1032
+ | `get_landing_page` | Get landing page details, builder content, metrics, and published URLs. |
1033
+ | `render_landing_page` | Return a signed 24-hour visitor preview without publishing, counting views, or collecting signups. |
1034
+ | `create_landing_page` | Create a draft landing page from default template content or JSON. |
1035
+ | `update_landing_page` | Edit a landing page name, slug, or full editor-compatible content. |
1036
+ | `publish_landing_page` | Publish a landing page, optionally saving edits first. |
1037
+ | `unpublish_landing_page` | Return a landing page to draft status, optionally saving edits first. |
1038
+ | `duplicate_landing_page` | Duplicate a landing page into a new draft with a unique slug. |
1039
+ | `delete_landing_page` | Delete an unpublished landing page. |
1040
+ | `connect_landing_page_domain` | Connect a custom landing page domain and return DNS setup details. |
1041
+ | `update_landing_page_domain_settings` | Replace or verify landing page custom domain settings. |
1042
+
1043
+ Landing page content uses Sequenzy's editor-compatible JSON schema with
1044
+ `version`, `template`, `seo`, `theme`, and `blocks`. SEO settings include
1045
+ `faviconUrl` and `hideFromSearchEngines`; hidden pages publish a `noindex`
1046
+ directive. Use `render_landing_page` to review the current visitor-facing page
1047
+ before publishing. Its signed `previewUrl` expires after 24 hours, is unlisted,
1048
+ is not indexed, and does not increment page views; forms remain visible but do
1049
+ not collect contacts. Blocks render in slot order:
1050
+ `top`, `hero`, `form`, `body`, then
1051
+ `footer`; use `top` for a full-width announcement or banner above the hero.
1052
+ Button and pricing CTA URLs accept external HTTPS destinations or in-page
1053
+ anchors such as `#form`, `#section-<sectionId>`, `#block-<blockId>`, and
1054
+ `#top`. Set `theme.sectionAnimation` to `none`, `fade`, `slide-up`, or
1055
+ `zoom-in`, with `theme.sectionAnimationSpeed` set to `slow`, `normal`, or
1056
+ `fast`, to control published scroll reveals. Custom landing page subdomains
1057
+ require a CNAME record pointing to `pages.sequenzydns.com`; root domains use an
1058
+ A record pointing to `76.76.21.21`, and their `www` host redirects to the root
1059
+ when its CNAME points to `pages.sequenzydns.com`. Call
1060
+ `update_landing_page_domain_settings` with `verify: true` after DNS changes
1061
+ propagate.
1062
+
1063
+ ### Sequences
1064
+
1065
+ | Tool | Description |
1066
+ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
1067
+ | `list_sequences` | List sequences with dashboard status, search, label, limit, and offset filters. |
1068
+ | `get_sequence` | Get sequence details, A/B variant IDs and block counts with `ab_tests:read`, nodes, edges, linked copy, and the sequence sending window. |
1069
+ | `list_sequence_enrollments` | List contact enrollments with pagination and accurate list/tag/event/time-based entry attribution. Live sequence tests do not create enrollments. |
1070
+ | `send_sequence_test_email` | Send one saved action_email step to 1-10 reviewers; A/B steps are inspected per variant. |
1071
+ | `create_sequence` | Create a blank dashboard draft or an AI-generated/explicit-step sequence. |
1072
+ | `update_sequence` | Update identity, settings, enrollment, existing steps, branch logic, or insert linear steps. |
1073
+ | `update_sequence_node` | Type-aware patch of one existing sequence node. |
1074
+ | `update_sequence_nodes` | Atomically patch multiple existing sequence nodes. |
1075
+ | `insert_sequence_step` | Insert any typed dashboard step, including AI generation, outbound webhooks, waits, and wired branches. |
1076
+ | `edit_sequence_graph` | Move, reconnect, delete, or duplicate graph nodes; reports recipients moved or completed. |
1077
+ | `simulate_sequence` | Dry-run current matches, activation readiness, and an optional contact's branch path without enrolling or sending. |
1078
+ | `enable_sequence` | Activate a sequence. |
1079
+ | `disable_sequence` | Freeze a sequence, blocking new enrollments and holding current recipients. |
1080
+ | `duplicate_sequence` | Create an independent draft copy of the graph, emails, and sequence A/B tests. |
1081
+ | `archive_sequence` | Move a sequence into the dashboard archive and stop new enrollments. |
1082
+ | `unarchive_sequence` | Restore an archived sequence as a disabled draft. |
1083
+ | `list_sequence_goals` | List the event, subscriber-attribute, and tag-applied conversion goals persisted for a sequence. |
1084
+ | `create_sequence_goal` | Add an event, subscriber-attribute, or tag-applied conversion goal. |
1085
+ | `update_sequence_goal` | Update a persisted sequence conversion goal. |
1086
+ | `delete_sequence_goal` | Delete a persisted sequence conversion goal. |
1087
+ | `get_sequence_inbound_webhook` | Read the inbound URL, setup state, sample, and mapping on standard MCP; the OpenAI route removes the credential-bearing URL. |
1088
+ | `configure_sequence_inbound_webhook` | Configure the endpoint, field mapping, and sample; the OpenAI route removes the credential-bearing URL from its result. |
1089
+ | `rotate_sequence_inbound_webhook_secret` | Rotate an inbound sequence endpoint's secret and return its replacement URL on standard MCP; omitted from the OpenAI-reviewed route. |
1090
+ | `pause_sequence_enrollments` | Stop new enrollments for an active sequence while current recipients continue. |
1091
+ | `resume_sequence_enrollments` | Reopen new enrollments for an active sequence without changing current recipients. |
1092
+ | `enroll_subscribers_in_sequence` | Enroll up to 500 subscribers by email, subscriber ID, or both, with retry-safe idempotency. |
1093
+ | `cancel_sequence_enrollments` | Stop active or waiting enrollments by subscriber or entry-event field values. |
1094
+ | `realign_sequence_enrollments` | Preview or queue moving live waits earlier to their sending-window opening. |
1095
+ | `get_sequence_enrollment_realignment` | Poll an applied realignment job and read its completed result or continuation cursor. |
1096
+ | `delete_sequence` | Delete a sequence. |
1097
+
1098
+ Sequence creation supports:
1099
+
1100
+ - Name-only creation for a blank, disabled trigger-to-completion draft matching the dashboard.
1101
+ - Dashboard metadata and delivery settings: `description`, `labels`, `userCancellable`, sequence BCC, and From/Reply-To identity.
1102
+ - `trigger: "contact_added"` with `listId`, several `listIds`, or `listScope`:
1103
+ `any_contact` (the default) enrolls every added contact, including contacts
1104
+ that join no list, while `any_list` waits for an actual list membership.
1105
+ - `trigger: "tag_added"` with `tagName` or several `tagNames`; any configured
1106
+ tag enrolls the contact.
1107
+ - `trigger: "segment_entered"` plus `segmentId` for saved-segment entry automations.
1108
+ - `trigger: "event_received"` plus `{{event.*}}` merge tags in subjects or body content.
1109
+ - `trigger: "inbound_webhook"` plus integration metadata for dashboard-compatible webhook entry nodes.
1110
+ - `trigger: "inactivity"` plus `eventName`, `inactiveDays`, and optional `inactivityBaseline` (`sequence_created_at` or `subscriber_created_at`).
1111
+ - `goal` for AI-generated email content.
1112
+ - `emailStyle: "visual"` or `"plain"` to choose the presentation of goal-based AI-generated emails; when omitted, the company's saved preference is used.
1113
+ - Explicit `steps` with Sequenzy `blocks`.
1114
+ - Explicit `steps` with HTML, which Sequenzy converts into editable blocks.
1115
+ - Explicit Update Subscriber steps that copy trigger-event properties into
1116
+ profile fields or typed custom attributes.
1117
+ - Fixed waits via `delay` / `delayMs`, dynamic date-field waits via `waitUntil`, or calendar gates via `waitUntilWeekday`. A weekday gate such as `{ "day": "sunday", "startTime": "09:00", "endTime": "12:00", "timezone": "America/Los_Angeles" }` holds the flow until the next matching window. Place it immediately before an email to keep that send inside the window; any intervening step can shift delivery outside it. Queue recovery rechecks the window before releasing a delayed contact.
1118
+ - Dynamic Stripe or Shopify discount action steps. A `create_discount` step creates a fresh provider code when each subscriber reaches it; later emails can use merge tags like `{{discount.code}}`, `{{discount.percentOff}}`, and `{{discount.expiresAt}}`.
1119
+ - `enrollmentMode: "matching_field"` and a scalar `enrollmentFieldPath` for product-, variant-, order-, or subscription-specific event automations. Array traversal with `[]` belongs in `propertyFilters`, not the enrollment key.
1120
+
1121
+ For a custom event trigger, the successful `create_sequence` result includes
1122
+ `eventTrackingCode` and a structured `eventTracking` object. The object contains
1123
+ the event endpoint, identity and payload contract, any property path required by
1124
+ `matching_field` enrollment, normalized trigger `propertyFilters`, an example
1125
+ payload, `examplePayloadMatchesFilters`, the direct event API docs URL, and
1126
+ ready-to-use arguments for `get_integration_guide`. If the match status is
1127
+ false, adapt the example using `examplePayloadNote` and the payload contract.
1128
+ Add this event feed and verify its required properties before enabling the draft
1129
+ sequence.
1130
+
1131
+ `list_sequence_enrollments` returns `enteredVia` for each row. List and segment
1132
+ sources keep their stable ID in `value` and resolve a display `name`; tag and
1133
+ event sources retain their names in `value`. Time-based triggers report
1134
+ `inactivity` or `frequency` rather than being misidentified as ordinary
1135
+ received-event enrollments. Live sequence tests do not create enrollments;
1136
+ they send isolated test emails and record activity on the sequence test run
1137
+ instead.
1138
+
1139
+ For a confirmed manual enrollment batch, generate `idempotencyKey` once and
1140
+ reuse that exact key only with identical ordered targets and `targetNodeId`.
1141
+ Receipts last 14 days. A retry returns the original `enrolled`, `skipped`,
1142
+ `notFound`, `targetNodeId`, and `scheduledFor` values with
1143
+ `idempotentReplay: true`; it does not create tokens or queue the batch again.
1144
+
1145
+ Example dynamic Shopify discount step:
1146
+
1147
+ ```json
1148
+ {
1149
+ "type": "create_discount",
1150
+ "discount": {
1151
+ "provider": "shopify",
1152
+ "discountType": "percent",
1153
+ "percentOff": 20,
1154
+ "duration": "once",
1155
+ "appliesToAllPlans": true,
1156
+ "maxRedemptions": 1,
1157
+ "codePrefix": "WINBACK"
1158
+ }
1159
+ }
1160
+ ```
1161
+
1162
+ Example Update Subscriber step:
1163
+
1164
+ ```json
1165
+ {
1166
+ "type": "update_subscriber",
1167
+ "nodeType": "action_update_attributes",
1168
+ "config": {
1169
+ "firstName": "{{event.firstName}}",
1170
+ "customAttributeUpdates": [
1171
+ { "name": "plan", "value": "{{event.plan}}", "valueType": "text" },
1172
+ { "name": "mrr", "value": "{{event.amount}}", "valueType": "number" },
1173
+ { "name": "active", "value": "{{event.active}}", "valueType": "boolean" }
1174
+ ]
1175
+ }
1176
+ }
1177
+ ```
1178
+
1179
+ Number and boolean values must be literals or one standalone merge tag. Use
1180
+ `update_sequence.subscriberUpdateSteps` with an `action_update_attributes`
1181
+ node ID from `get_sequence` to replace an existing step's config.
1182
+
1183
+ Sequence updates support `insertSteps` for adding new linear steps after a `nodeId` returned by `get_sequence`. Omit `afterNodeId` only when appending to a sequence with exactly one linear tail. `insertSteps` supports addable steps that do not require companion records, such as email, delay, tag/list actions, attribute updates, discounts, conditions, wait-for-event steps, outbound webhooks, and AI steps. An `action_ai` step requires a merge-tag `prompt`, unique `resultKey`, and one or more `outputFields`; later steps read generated or fallback text with `{{ai.KEY.field}}`. Combined output-field limits must fit the step's 2000-token response budget. Use `includeTags`, `includeEventProperties`, or `includeAttributes` to opt specific contact context into generation, and `onError` (`continue`, `exit`, or `fail`) to choose failure behavior. Use `branch` for multi-path if/else branches; provide either `branch` or `insertSteps`, not both. Branch conditions support tag presence and absence checks with `has_tag` and `does_not_have_tag`, plus lists, saved segments, events, clicked links, and field comparisons. Each branch path may provide new `steps`, an existing `targetNodeId`, or both; the fallback uses `elseSteps` and/or `elseTargetNodeId`. A target can be the completion node returned by `get_sequence`, so one atomic request can route replies to completion and Else to an existing follow-up. The `emails` and `steps` arrays edit ordinary `action_email` steps by `nodeId`, `emailId`, or array order. `get_sequence.sequence.emails` also includes `action_ab_test` entries; with `ab_tests:read`, each `abTest.variants[]` entry contains the variant ID, subject, preview text, and block count. Call `get_ab_test` for full variant bodies before auditing or rewriting copy. A positional update landing on one is rejected, and its copy must be changed per variant with `update_ab_test_variant`; do not retry through `update_template` or `update_sequence_node`. Use `insertSteps` to create new steps and include a step-level `delay`, `delayMs`, `waitUntil`, or `waitUntilWeekday` when the inserted email needs a timer. `waitUntil` accepts a date field from the trigger event plus optional `offset`, `direction` (`before` or `after`), and `missingAction` (`continue` or `exit`). `waitUntilWeekday` accepts `day` or `days`, `startTime`, optional `endTime` (default `24:00`), and an IANA `timezone`; contacts already inside the window continue immediately. For active sequences, pass `confirmStructuralChange: true` with `insertSteps` or `branch` only after confirming the live-flow impact.
1184
+
1185
+ `insert_sequence_step` exposes every companion-record-free dashboard step directly: email, SMS, delay, discount, subscriber update, tag/list action, outbound webhook, AI generation, condition, wait, and branch. Set `type: "ai"` with `prompt`, `resultKey`, and `outputFields` to generate per-contact text for later `{{ai.KEY.field}}` merge tags. Outbound webhooks accept `url`, `method` (`POST` or `GET`), and string-valued `headers`. Email steps support transactional mode, per-step identity, and CC/BCC delivery settings. For a wait gate, set
1186
+ `type: "logic_wait_for_event"` with `eventName`, optional `timeoutDays` (1-365),
1187
+ and `timeoutAction` (`continue` or `exit`). For a branch, set
1188
+ `type: "logic_branch"`, provide typed `branches`, and wire their targets:
1189
+
1190
+ ```json
1191
+ {
1192
+ "sequenceId": "seq_123",
1193
+ "type": "logic_branch",
1194
+ "afterNodeId": "node_email_1",
1195
+ "branches": [
1196
+ {
1197
+ "id": "replied",
1198
+ "conditionType": "event_received",
1199
+ "eventName": "email.replied",
1200
+ "activityScope": "this_sequence",
1201
+ "targetNodeId": "node_complete"
1202
+ }
1203
+ ],
1204
+ "elseTargetNodeId": "node_email_2"
1205
+ }
1206
+ ```
1207
+
1208
+ Each linked email returned by `get_sequence` includes its effective
1209
+ `emailPreset` (`branded` or `minimal`), matching **Style > Format** in the
1210
+ dashboard. Set `emailPreset` on an `emails`/`steps` item, or in an
1211
+ `action_email` node's `changes`, to change only that linked email without
1212
+ changing the company theme. This applies the same format transformation as the
1213
+ dashboard to native Sequenzy blocks, including emails that contain supported
1214
+ custom HTML blocks. Emails stored entirely as one standalone raw HTML block
1215
+ return `null` for `emailPreset` and do not support format changes.
1216
+ `emailPreset` cannot be combined with `html` or `htmlContent` because those
1217
+ fields replace the entire email with standalone raw HTML.
1218
+
1219
+ For sequence position, prefer `structuralStepNumber` on linked emails and the
1220
+ top level of email nodes. It is derived from the current graph and matches the
1221
+ step badge shown in the dashboard. Parallel branch emails intentionally share
1222
+ the same structural depth, and an unequal branch merge continues from the
1223
+ longer incoming path. The older `stepNumber` field in linked emails and node
1224
+ configs remains a stored ordinal for backward compatibility and may be stale
1225
+ after graph edits.
1226
+
1227
+ Each linked email also returns its stored `emailTheme` override, or `null` when
1228
+ it follows the company theme. Set `emailTheme` on an `emails`/`steps` item or in
1229
+ an `action_email` node's `changes` to restyle only that step. Theme updates are
1230
+ partial patches, so `changes: { "emailTheme": { "colors": {
1231
+ "background": "#f3f4f6", "content": "#ffffff" } } }` gives that email a gray
1232
+ outer canvas and white content card while retaining its other colors,
1233
+ typography, and layout. Omitting either color preserves its current value. Pass
1234
+ `emailTheme: null` to drop the override and follow the company theme again. Use
1235
+ `update_company` only when the account-wide default should change.
1236
+
1237
+ Use `update_sequence_node` for a focused in-place edit, or
1238
+ `update_sequence_nodes` when several node patches must commit atomically. Call
1239
+ `get_sequence` first: every item in `sequence.nodes` includes the node `id`,
1240
+ `nodeType`, current `config`, `updatedAt`, and `updateHints` with editable and
1241
+ managed fields plus the exact concurrency token to return. Pass that token as
1242
+ `expectedUpdatedAt` to reject stale writes. The tools support every stored node
1243
+ type, including delays, email/SMS content, actions, conditions, webhooks,
1244
+ branch configuration without topology changes, and triggers. To change a
1245
+ 5-minute delay to 7 days, send `changes: { "delay": { "days": 7 } }` for its
1246
+ `logic_delay` node. To make several founder-style notes Minimal, patch their
1247
+ `action_email` nodes with `changes: { "emailPreset": "minimal" }`. Node-type
1248
+ conversion and edge/path changes belong in `edit_sequence_graph`. Active
1249
+ sequences require `confirmLiveChange: true` after the user confirms the impact;
1250
+ recipients already waiting retain their existing scheduled timestamp.
1251
+
1252
+ Existing and newly inserted email steps can set their own From identity with
1253
+ `senderProfileId` or `fromEmail` plus optional `fromName`, and their Reply-To
1254
+ identity with `replyProfileId` or `replyTo` plus optional `replyToName`. A
1255
+ `fromName` on its own changes only that step's visible sender name. A step-level
1256
+ `replyToName` similarly overrides the visible Reply-To name for that step
1257
+ without renaming the company-wide reply profile. New email steps without
1258
+ explicit identity fields inherit the effective identity of the nearest
1259
+ sequence email. After a branch merge, only identity fields shared by every
1260
+ incoming path are inherited; conflicting fields use the sequence or company
1261
+ defaults.
1262
+
1263
+ Use `edit_sequence_graph` with the latest `graphRevision` from `get_sequence` to restructure an existing sequence atomically. It can move a node before or after another node, reuse the normalized `sequence.edges` array for explicit reconnection or multi-node reordering, delete a node, or deep-copy a node. A/B test duplication creates independent test, variant, email, and localization records with reset statistics. Moving a node before the shared node below a branch reconnects every converging branch path through that node. Deleting a node immediately moves parked recipients to its unique surviving successor, or completes them when no successor remains; inspect `sequence.migratedRecipientCount` and `sequence.completedRecipientCount` in the result. Deletion is refused when parked recipients would have multiple surviving continuations. Stale revisions, invalid branch lanes, cycles, and unreachable nodes are also rejected. Active sequences require `confirmStructuralChange: true`.
1264
+
1265
+ Run `cancel_sequence_enrollments` with `dryRun: true` before applying bulk cancellation.
1266
+
1267
+ Run `realign_sequence_enrollments` after changing a live sequence's sending
1268
+ window when existing email-bound waits should move earlier to the new opening.
1269
+ It defaults to `dryRun: true`. Passing `dryRun: false` queues a background job
1270
+ and returns `jobId`; poll it with `get_sequence_enrollment_realignment`. When a
1271
+ completed result has `hasMore: true`, queue the next bounded apply with its
1272
+ `nextCursor`. Applied realignment changes live delivery times and should only be
1273
+ used after the user confirms the preview.
1274
+
1275
+ ### Email Blocks
1276
+
1277
+ | Tool | Description |
1278
+ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
1279
+ | `get_email_block_schema` | List every email block type or inspect one type's required fields, enum values, item shapes, and example. |
1280
+
1281
+ Call `get_email_block_schema` before hand-authoring a block type you have not
1282
+ used before. Omit `blockType` to list every type, pass a type such as `list` or
1283
+ `steps` for its complete reference, or pass `creatableOnly: true` to hide types
1284
+ managed by the editor. Persisted `group` blocks are structural editor content:
1285
+ they recursively wrap child blocks in Stack, Row, Grid, or single-image Overlay
1286
+ layouts, but AI generation and `creatableOnly` intentionally omit them. Request
1287
+ `blockType: "group"` to inspect their fields when reading or updating existing
1288
+ grouped content. Lists are their own block type rather than a `text`
1289
+ variant: `list` items use `content`, while `steps` items use `title` and an
1290
+ optional `description`.
1291
+
1292
+ Tools that accept `blocks` persist per-block visual styling under a block's `styles` object:
1293
+
1294
+ ```json
1295
+ {
1296
+ "type": "card",
1297
+ "title": "Your update",
1298
+ "content": "Everything is ready.",
1299
+ "variant": "default",
1300
+ "styles": {
1301
+ "backgroundColor": "#f8fafc",
1302
+ "backgroundOpacity": 85,
1303
+ "borderColor": "#cbd5e1",
1304
+ "borderWidth": 1,
1305
+ "borderRadius": 12
1306
+ }
1307
+ }
1308
+ ```
1309
+
1310
+ For compatibility with older agent prompts, top-level style keys such as `backgroundColor`, `backgroundOpacity`, `borderColor`, `borderWidth`, and `borderRadius` are also accepted and saved under `styles`.
1311
+
1312
+ ### Transactional Email
1313
+
1314
+ | Tool | Description |
1315
+ | ---------------------------- | ------------------------------------------------------------------------------------------ |
1316
+ | `list_transactional_emails` | Search/filter templates and sort by delivery metrics; returns subjects and dashboard URLs. |
1317
+ | `get_transactional_email` | Read a transactional email by ID or slug. |
1318
+ | `create_transactional_email` | Create a transactional template from a prompt, HTML, or blocks. |
1319
+ | `update_transactional_email` | Update transactional metadata or body content. |
1320
+ | `send_email` | Send one email by template or HTML to shared To, Cc, and Bcc recipients. |
1321
+
1322
+ Prompt-created transactional templates are generated server-side and default
1323
+ to disabled for review. Explicit HTML or block templates retain the
1324
+ compatibility default of enabled; pass `enabled` explicitly to override either
1325
+ default.
1326
+
1327
+ For a direct send, pass `to`, `subject`, and `html`; the MCP server maps `html`
1328
+ to the transactional API's `body` field. For a saved transactional email, pass
1329
+ its API slug through the compatibility-named `templateId` field instead.
1330
+ For transactional sends, `to`, `cc`, and `bcc` each accept one address or an
1331
+ array of up to 50. The API sends one email with a shared recipient list and
1332
+ removes cross-field duplicates in `to`, then `cc`, then `bcc` priority order.
1333
+ Marketing sends still require exactly one accepted `to` address and do not
1334
+ support additional recipients.
1335
+ `send_email` variables support nested arrays for repeat blocks, such as
1336
+ `{ "event": { "items": [...] } }`. When the recipient matches a stored
1337
+ subscriber by external ID or email, saved first and last names fill omitted name
1338
+ variables automatically. Explicit values, including blanks, take precedence.
1339
+ The optional `attachments` array accepts up to 10 files / 7MB total. Each item
1340
+ needs `filename` and exactly one of Base64 `content` or a public HTTP(S) `path`.
1341
+ Set `contentId` to embed a CID image referenced from the HTML and optionally set
1342
+ `contentType` to override MIME detection.
1343
+ When `trackingSettings` is omitted, the company's Transactional API tracking
1344
+ defaults apply. Use `trackingSettings.clickTracking: false` or
1345
+ `trackingSettings.openTracking: false` to disable link rewriting or the open
1346
+ pixel for one send. These per-send options only opt out; they cannot enable
1347
+ tracking disabled by an account-wide or Transactional API default. Use
1348
+ `get_tracking_settings` and `update_tracking_settings` to inspect or change
1349
+ those defaults.
1350
+
1351
+ For agent and workflow retries, include a stable `idempotencyKey` (up to 255
1352
+ characters) in `send_email`. Use one key per logical email and send the same
1353
+ arguments when retrying; the key remains valid for 14 days.
1354
+
1355
+ ### Analytics
1356
+
1357
+ | Tool | Description |
1358
+ | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
1359
+ | `get_stats` | Get overview stats for `7d`, `30d`, or `90d`; filter by structural email type. |
1360
+ | `get_transactional_stats` | Get all-time or time-scoped metrics for one saved transactional email by ID or slug. |
1361
+ | `get_campaign_stats` | Get campaign performance, reply metrics, attached conversion goals, and Poll/NPS summaries. |
1362
+ | `list_poll_responses` | List each respondent's latest Poll/NPS answer per block, with identity and response time. |
1363
+ | `get_sequence_stats` | Get aggregate and per-step sequence performance plus live active/waiting enrollment counts by current node. |
1364
+ | `list_email_metrics` | Compare campaign and sequence-step funnels, replies, conversions, and revenue, including cross-sequence steps. |
1365
+ | `list_campaign_events` | List paginated raw email events for a campaign. |
1366
+ | `list_sequence_events` | List paginated raw events for a sequence, optionally scoped to one email step. |
1367
+ | `get_subscriber_activity` | Get subscriber email stats, activity, and enrollments. |
1368
+
1369
+ Campaign and sequence event filters accept `transport_failure` alongside
1370
+ delivery, bounce, complaint, engagement, unsubscribe, and delay events.
1371
+ Transport failures describe MTA infrastructure or egress-path exhaustion; they
1372
+ do not classify a valid recipient address as bounced.
1373
+
1374
+ Analytics tools exclude detected bot, scanner, link-preview, and tracked asset opens/clicks by default. Pass `includeMachineEngagement: true` to `get_stats`, `get_campaign_stats`, `get_sequence_stats`, `get_ab_test_stats`, `get_subscriber`, or `get_subscriber_activity` when you need raw engagement diagnostics; included open/click activity rows expose `machine`, `engagementQuality`, and `classificationReasons` fields where the API returns event-level activity.
1375
+
1376
+ `get_sequence_stats.enrollmentCounts` is a live point-in-time snapshot of
1377
+ active and waiting enrollment runs grouped by current node. It counts
1378
+ enrollment tokens rather than necessarily distinct subscribers, and it is not
1379
+ limited by historical `period`, `start`, or `end` filters.
1380
+
1381
+ Use `list_email_metrics` for comparisons across campaigns or sequence steps.
1382
+ Pass `step` with optional `sequenceId` values to total the same step across
1383
+ sequences; use the returned `automationNodeId` with `list_sequence_events` or
1384
+ `list_email_sends` to inspect recipients. `campaignId` cannot be combined with
1385
+ `sequenceId` or `step`. Explicit campaign and sequence scopes retain configured
1386
+ emails with zero activity so weak performers are not silently omitted.
1387
+
1388
+ Pass `emailType: "transactional"` to `get_stats` for Send API and
1389
+ transactional SMTP delivery, open, click, and reply rates. This includes direct
1390
+ and saved-template sends. Use the `emailSendId` returned by `send_email` with
1391
+ `get_email_send` when you need one delivery's status and event timeline.
1392
+ Use `get_transactional_stats` when you need aggregate rates for one saved
1393
+ transactional email. Its response includes top clicked links, complaints,
1394
+ replies, latest permanent/transient bounce classifications, and separate human
1395
+ and machine open/click counts. Direct-content sends do not have a stable
1396
+ template ID and remain available through account transactional stats plus
1397
+ delivery search.
1398
+
1399
+ When a campaign collects Poll or NPS answers, `get_campaign_stats` includes a
1400
+ top-level `polls` array. Each subscriber counts once per poll block using their
1401
+ latest answer. NPS summaries include the score, average, and
1402
+ promoter/passive/detractor counts. These are lifetime response summaries even
1403
+ when engagement metrics use a time filter.
1404
+
1405
+ Use `list_poll_responses` to read who answered what and when. It returns each
1406
+ subscriber's latest answer per poll block, newest first, including the email,
1407
+ stored value, attribute key, and response time. Pass `blockId` to scope one
1408
+ poll; for a sequence email step, pass its automation node ID as `campaignId`.
1409
+ Do not reconstruct this history by scanning subscriber attributes: an
1410
+ attribute has no response timestamp and may have been overwritten by a later
1411
+ email that reused the same key.
1412
+
1413
+ To list the exact historical respondents behind a count, call `create_segment`
1414
+ with field `pollResponse`, operator `is`, and a JSON value scoped to the
1415
+ campaign and the summary's `blockId`:
1416
+
1417
+ ```json
1418
+ {
1419
+ "v": 1,
1420
+ "campaignId": "camp_123",
1421
+ "blockId": "poll_1",
1422
+ "match": { "kind": "answer", "value": "loved" }
1423
+ }
1424
+ ```
1425
+
1426
+ For NPS, use a match such as
1427
+ `{"kind":"npsBucket","bucket":"detractors"}`; valid buckets are
1428
+ `promoters`, `passives`, and `detractors`. The summary's `attributeKey` stores
1429
+ the subscriber's current/latest response and may be overwritten by a later poll
1430
+ that reuses the key, so it is not an exact historical drill-down.
1431
+
1432
+ ### Team, Inbox, Webhooks
1433
+
1434
+ | Tool | Description |
1435
+ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
1436
+ | `list_team_members` | List team members and pending invitations. |
1437
+ | `invite_team_member` | Invite a teammate as admin or viewer, with optional billing access. |
1438
+ | `cancel_team_invitation` | Cancel a pending team invitation. |
1439
+ | `list_conversations` | List subscriber reply conversations with status and unread filters. |
1440
+ | `get_conversation` | Read a conversation and its message history. |
1441
+ | `reply_to_conversation` | Queue an outbound reply or add an internal note. |
1442
+ | `update_conversation_status` | Open or close a conversation. |
1443
+ | `mark_conversation_read` | Mark all messages in a conversation as read. |
1444
+ | `list_webhooks` | List outbound webhook endpoints. |
1445
+ | `create_webhook` | Create an endpoint and return its one-time signing secret on standard MCP; omitted from the OpenAI-reviewed route. |
1446
+ | `update_webhook` | Update webhook name, URL, events, or status. |
1447
+ | `delete_webhook` | Permanently delete a webhook endpoint and delivery history. |
1448
+ | `test_webhook` | Send a test event to a webhook endpoint. |
1449
+ | `list_webhook_deliveries` | List recent delivery attempts for a webhook. |
1450
+ | `replay_webhook_delivery` | Replay a webhook delivery. |
1451
+
1452
+ Per-list consent changes are available as opt-in outbound events:
1453
+ `subscriber.list_subscribed` and `subscriber.list_unsubscribed`. Their payloads
1454
+ identify the subscriber and list, report `action` as `added` or `removed`, and
1455
+ include the change `source` (for example `preferences_page`, `dashboard`,
1456
+ `api`, or `automation`).
1457
+
1458
+ Use the `email.failed` event for terminal delivery failures such as exhausted
1459
+ MTA transport paths. Recipient bounces continue to use `email.bounced`.
1460
+
1461
+ Use the explicit-only `campaign.sent` event when a workflow needs one terminal
1462
+ notification after an email or SMS campaign settles, including a valid
1463
+ zero-recipient send. It is not added when `create_webhook` omits `events` on
1464
+ standard MCP; on the OpenAI-reviewed route, add it in the dashboard when
1465
+ creating or editing the webhook.
1466
+
1467
+ ### AI Generation
1468
+
1469
+ | Tool | Description |
1470
+ | ------------------------ | ----------------------------------------------------------- |
1471
+ | `generate_email` | Generate branded email blocks from a prompt. |
1472
+ | `generate_sequence` | Deprecated alias that persists a goal-based sequence draft. |
1473
+ | `generate_subject_lines` | Generate A/B subject line variants. |
1474
+
1475
+ Generated email content includes the company's logo and footer by default.
1476
+ `generate_email` accepts `applyBranding: false` for raw content blocks and
1477
+ `emailType: "transactional"` for a footer without an unsubscribe link.
1478
+ Prompt-based campaigns inherit the company's configured email font. Generated
1479
+ content is returned as draft content for review. Use `create_sequence` to
1480
+ generate and persist a disabled sequence draft that appears in
1481
+ `list_sequences`; the deprecated `generate_sequence` alias does the same.
1482
+
1483
+ ### SMS
1484
+
1485
+ | Tool | Description |
1486
+ | ------------------------- | ------------------------------------------------------------------------------------------- |
1487
+ | `generate_sms` | Generate SMS copy from a prompt. |
1488
+ | `get_sms_settings` | Read SMS add-on readiness, credits, defaults, and provisioned numbers. |
1489
+ | `get_sms_usage` | Compare sends, delivery outcomes, charged credits, last activity, and test sends by number. |
1490
+ | `update_sms_number_label` | Update a number's label or per-number brand-prefix override. |
1491
+ | `release_sms_number` | Permanently return a number to the carrier and free its workspace slot. |
1492
+ | `send_test_sms` | Send a test message, optionally choosing a provisioned sender with `fromNumberId`. |
1493
+
1494
+ `release_sms_number` is irreversible. Campaign or sequence steps pinned to a
1495
+ released number will skip their SMS sends until they are repointed to an active
1496
+ number. `get_sms_usage` reports production totals separately from `testSends`.
1497
+ When `send_test_sms` omits `fromNumberId`, it uses the same oldest-active-number
1498
+ default as production sends. Test sends are real, credit-charged messages that
1499
+ bypass quiet hours and are limited to 100 per company in a rolling 24-hour
1500
+ window.
1501
+
1502
+ ### Product Feedback
1503
+
1504
+ Use `submit_feedback` only when the user explicitly asks the assistant to send
1505
+ feedback to the Sequenzy team. Standard MCP can include the structured
1506
+ reproduction fields `userIntent`, `toolCalls`, `expected`, `actual`, and
1507
+ `resourceIds` when needed for that report. The OpenAI-reviewed route accepts
1508
+ only the message, category, and optional generalized workflow context. Do not
1509
+ include unrelated subscriber data, email content, raw API payloads, debug data,
1510
+ or secrets.
1511
+
1512
+ ## Resources
1513
+
1514
+ The server also exposes read-only MCP resources.
1515
+
1516
+ | Resource | Description |
1517
+ | -------------------------------- | ---------------------------------------------- |
1518
+ | `sequenzy://dashboard` | Live overview stats for the last 7 days. |
1519
+ | `sequenzy://company` | Current company and localization settings. |
1520
+ | `sequenzy://campaigns/recent` | Last 10 campaigns with status and basic stats. |
1521
+ | `sequenzy://subscribers/recent` | Most recently added subscribers. |
1522
+ | `sequenzy://subscribers/engaged` | Most active or engaged subscribers. |
1523
+ | `sequenzy://sequences` | All sequences with status. |
1524
+ | `sequenzy://templates` | Templates with localization status. |
1525
+ | `sequenzy://segments` | Saved segments with subscriber counts. |
1526
+ | `sequenzy://tags` | Tags with usage counts. |
1527
+ | `sequenzy://health` | Deliverability metrics and health status. |
1528
+ | `sequenzy://email-blocks` | Field reference for every email block type. |
1529
+ | `sequenzy://app-routes` | Dashboard route templates and settings tabs. |
1530
+
1531
+ ## Example Prompts
1532
+
1533
+ ```text
1534
+ Add john@example.com with tags "vip" and "developer", then put them on the beta list.
1535
+ ```
1536
+
1537
+ ```text
1538
+ Create a 4-email churn prevention sequence for users whose subscription expires soon. Leave it in draft mode.
1539
+ ```
1540
+
1541
+ ```text
1542
+ Create a segment for subscribers who bought Stripe product prod_pro at least 3 times.
1543
+ ```
1544
+
1545
+ ```text
1546
+ Draft a campaign about our new analytics dashboard, target the Pro users segment, and send a test to me.
1547
+ ```
1548
+
1549
+ ```text
1550
+ How did the last campaign perform compared with the one before it?
1551
+ ```
1552
+
1553
+ ## Security
1554
+
1555
+ - Use personal API keys, not shared team secrets.
1556
+ - Keys only access companies your Sequenzy user can access.
1557
+ - Revoke keys from Settings -> API Keys when access is no longer needed.
1558
+ - Keep client approval prompts enabled for sends, scheduling, deletes, and bulk changes.
1559
+ - Prefer draft workflows for campaigns and sequences, then review in Sequenzy before launch.
1560
+
1561
+ ## Troubleshooting
1562
+
1563
+ ### `SEQUENZY_API_KEY environment variable is required`
1564
+
1565
+ Set `SEQUENZY_API_KEY` in the MCP client config, or run:
1566
+
1567
+ ```bash
1568
+ npx @sequenzy/setup
1569
+ ```
1570
+
1571
+ ### Invalid API Key
1572
+
1573
+ Create a new personal key in Settings -> API Keys, update your MCP config, and restart the client.
1574
+
1575
+ ### Missing API Key Scope
1576
+
1577
+ Call `get_account` and inspect `apiKeyPermissions`. Local connections should
1578
+ open `apiKeyPermissions.manageUrl`, add the missing scope to the loaded key, and
1579
+ retry without restarting. `update_api_key` can perform this only for company
1580
+ keys that already hold `api_keys:manage`; edit personal keys on the account-level
1581
+ API Keys page. Hosted OAuth connections can alternatively disconnect and
1582
+ reauthorize with broader permissions. The tool error includes the exact scope or
1583
+ scopes required.
1584
+
1585
+ ### Duplicate Resources
1586
+
1587
+ If a tool call would create a duplicate segment name or sending domain, the server returns a stable `code`, an agent-friendly `description`, a concrete `resolution`, and a `docsUrl`. For segments, call `list_segments` and reuse the existing segment ID or choose a different name. For websites, call `list_websites`; if the domain is not listed for the selected company, it belongs to another company or account and must be removed, reassigned, or replaced with a different sending domain.
1588
+
1589
+ ### Tools Do Not Appear
1590
+
1591
+ - Confirm `npx` is available in the environment the client uses.
1592
+ - Restart the MCP client after editing config.
1593
+ - Check that the config is in the correct client-specific location.
1594
+
1595
+ ### Network or API URL Issues
1596
+
1597
+ The server uses `https://api.sequenzy.com` by default. If you override it, verify `SEQUENZY_API_URL` points at a reachable Sequenzy API base URL.
1598
+
1599
+ ## Development
1600
+
1601
+ ```bash
1602
+ bun install
1603
+ bun test
1604
+ bun run type-check
1605
+ bun run build
1606
+ ```
1607
+
1608
+ MCP tool schemas must remain compatible with strict clients:
1609
+
1610
+ - Tool `inputSchema` roots must be plain `type: "object"` schemas.
1611
+ - Do not publish `anyOf` anywhere in tool schemas.
1612
+ - Do not put `oneOf`, `allOf`, `enum`, or `not` at the root of a tool schema.
1613
+ - Enforce conditional requirements in handlers and cover them with tests.
1614
+
1615
+ This standalone repository mirrors the MCP package maintained in the Sequenzy monorepo. Release automation updates it after successful API deployment and package publication. Maintain source, tests and this README in the monorepo `packages/mcp/` directory.
1616
+
1617
+ ## License
1618
+
1619
+ MIT
1620
+
1621
+ ## Agent-native discovery
1622
+
1623
+ Sequenzy publishes machine-readable manifests for agent networks and A2A-style discovery:
1624
+
1625
+ - Remote MCP endpoint: `https://api.sequenzy.com/v1/mcp`
1626
+ - Agent capability manifest: [`agent-capability.json`](https://github.com/Sequenzy/mcp/blob/main/agent-capability.json)
1627
+ - A2A-style agent card: [`.well-known/agent-card.json`](https://github.com/Sequenzy/mcp/blob/main/.well-known/agent-card.json)
1628
+ - OpenClaw/Moltbot skill metadata: [`openclaw/skill.json`](https://github.com/Sequenzy/mcp/blob/main/openclaw/skill.json)
1629
+ - OpenClaw/Moltbot operating guide: [`openclaw/SKILL.md`](https://github.com/Sequenzy/mcp/blob/main/openclaw/SKILL.md)
1630
+
1631
+ These files describe Sequenzy as an authorized email automation capability for agents. They explicitly exclude scraping, spam, and unsolicited cold outreach use cases.
1632
+
1633
+ ## Workspace roles
1634
+
1635
+ Account-key access combines key scopes with your current workspace role. `get_account` reports blocked scopes in `apiKeyPermissions.roleRestrictedScopes`; `canSendLive` means at least one permitted delivery workflow is available, not that every send tool is allowed.
1636
+
1637
+ You can invite a `marketer` to manage subscribers, marketing campaigns and sequences without granting access to transactional mail, workspace settings, team or billing. Marketers choose existing sender/reply profiles. Transactional-backed campaign, A/B and sequence sources remain protected through previews, sharing, analytics and send history. Marketers and restricted members cannot receive billing access.
1638
+
1639
+ ### Saved AI email styles
1640
+
1641
+ Use `get_email_ai_style` to inspect the company's saved appearance and `revisionId`. `save_email_ai_style` captures an existing email by its underlying `emailId`; pass `expectedStyleId: null` only for an initial save, or the reviewed revision when replacing. Optional `canvas` captures an unsaved editor snapshot containing `blocks`, `theme`, `fontFamily`, and `emailPreset`. Saving also detects layout habits (for example dotted dividers around every button) and keeps all of them unless `layoutRuleIds` lists the rule IDs to keep (`[]` keeps none); optional `notes` (500 characters max) adds design guidance. Review `style.layout.rules` in the response. `clear_email_ai_style` requires the current nonempty revision.
1642
+
1643
+ Reads require `emails:read`; saves/clears require `emails:write` and the current workspace role. Marketers cannot capture transactional source emails. A 409 conflict requires reading and reviewing the new state before retrying. These tools never edit or send the source email. Generation across all surfaces uses the saved default unless explicit styling or a plain-text choice takes precedence.