Sequenzy MCP Server
Official MCP server for Sequenzy, the AI-powered email marketing platform.
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.
What You Can Do
- Manage subscribers, tags, lists, and dynamic segments, including bulk tag reconciliation and synthetic event testing.
- Sync segments to Meta custom audiences for Facebook and Instagram retargeting.
- Manage products and attach digital delivery files for purchase automations.
- Upload hosted email images with alt text and reusable responsive crop settings.
- Draft, update, schedule, and inspect campaigns, including resolved audience previews, persisted conversion goals, and From, Reply-To, CC, and BCC identities.
- Render campaigns, sequence steps, and templates to their exact email-safe HTML without sending.
- Add one-click Poll and NPS survey blocks to emails and inspect campaign response summaries.
- 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.
- Cancel, pause, resume, duplicate, or delete campaigns and enroll contacts into sequences.
- Manage transactional email templates and send transactional emails to shared To, Cc, and Bcc recipient lists.
- Supply localized template variants or queue AI translation for enabled locales.
- Create, preview, edit, publish, unpublish, and delete landing pages.
- Create list-scoped saved signup forms with responsive stack, row, grid, and single-image overlay block groups (including foreground gap controls), then return client-safe static-site embeds.
- Create, target, publish, duplicate, and deploy saved signup popups with the same recursive block layouts.
- Connect and verify custom domains for published landing pages.
- Manage team invitations, inbox conversations, and outbound webhook endpoints.
- Generate email copy, subject lines, and multi-step sequences.
- Inspect analytics, subscriber activity, deliverability health, company-level sending pauses, integrations, published event payload schemas, sending identities, tracking settings, and dashboard URLs.
- 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.
- Diagnose why sending is paused and restore eligible hard-bounce pauses after confirming list cleanup.
- Inspect exact-recipient bounce, complaint, and email-hygiene suppression, and clean up eligible stale bounces without exposing the shared SES suppression list.
- 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.
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.
Quick Setup
The easiest setup path is the Sequenzy wizard:
npx @sequenzy/setup
The wizard opens the browser login flow, creates a personal API key, detects supported AI clients, and configures them automatically when possible.
Hosted Remote MCP
For clients that support Streamable HTTP MCP, use Sequenzy's hosted endpoint instead of running a local stdio process:
https://api.sequenzy.com/v1/mcp
ChatGPT and the OpenAI plugin directory use the reviewed hosted surface:
https://api.sequenzy.com/v1/mcp/openai
That surface shares the same implementation and keeps the standard tool set
except for six operations: connect_integration, create_api_key,
create_webhook, list_webhook_deliveries, replay_webhook_delivery, and
rotate_sequence_inbound_webhook_secret. Feedback stays available with a
reduced schema for generalized, explicitly requested product feedback.
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.
The hosted endpoint and the stdio package support MCP specification
2026-07-28 while remaining compatible with 2025-era clients. Modern HTTP
clients use per-request discovery and method headers; existing clients keep
working through the same endpoint and package command.
Machine-readable discovery files:
- MCP server manifest:
server.json - Agent card:
.well-known/agent-card.json - Agent capability manifest:
agent-capability.json - OpenClaw skill metadata:
openclaw/skill.json
Data and privacy
Sequenzy sends an MCP client only the data needed for the tool the user asks it to run, within the selected workspace and the key or OAuth scopes granted to that client. Depending on the requested tool, this can include workspace names and IDs; subscriber contact, consent, audience, attribute, event, engagement, reply, survey, and commerce data; campaign and automation content; delivery analytics; and integration or webhook status. See the Sequenzy Privacy Policy for the full categories, purposes, recipients, retention periods, and user controls.
Do not use open-ended custom attributes, events, notes, forms, webhook samples, email variables, or feedback to submit payment-card data, health or medical data, government identifiers, biometric or genetic data, authentication credentials, sensitive demographic data, or precise geolocation.
The OpenAI-reviewed route states and enforces those restrictions on relevant
open-ended inputs, including nested attribute paths such as profile.ssn,
coordinate pairs such as lat/lng, and labelled prose such as
Religion: ... or GPS coordinates: .... It rejects a credential-bearing URL
in any argument, whether the credential sits in the userinfo, path, query, or
fragment, such as a form or popup redirectUrl with an access token or URL
signature. Restricted attribute selectors inside merge tags are rejected
without blocking ordinary authored copy about the same topic. On this surface,
render_email accepts sample data or a policy-checked inline subscriber, but
not subscriberId, so it cannot resolve uninspected stored custom attributes.
Its results remove restricted fields, raw API errors, debug payloads, internal
request/trace/session identifiers, unnecessary account or credential
identifiers, stored credential-bearing URLs, and inbound-webhook URLs. Standard
remote MCP and the local stdio package retain the complete contract for trusted
clients, including credential-based integration setup, one-time API-key and
webhook secrets, inbound-webhook URLs, and detailed API errors. Prefer the
dashboard or local CLI when secrets should stay outside an AI conversation.
submit_feedback runs only when the user explicitly asks; its OpenAI schema is
limited to a generalized message, category, and optional workflow context, and
the route rejects feedback text that contains an email address or resource ID.
What the reviewed surface guarantees is bounded. It recognizes restricted data
by shape: English field-name words such as passport_id, user.ssn, or
api_secret at any nesting depth, labelled prose such as Diagnosis: ...,
known credential shapes, decimal coordinate pairs, and credential-bearing URLs
inside any string, including HTML. It does not interpret unlabelled prose,
non-English field names, or values a client deliberately obfuscates; those
remain covered by the usage restriction above rather than by the filter.
Manual Setup
All stdio MCP clients use the same command:
- Command:
npx - Args:
-y @sequenzy/mcp - Required env:
SEQUENZY_API_KEY=seq_user_your_key_here
Optional environment variables:
SEQUENZY_API_URL- Sequenzy API base URL. Defaults tohttps://api.sequenzy.com.SEQUENZY_APP_URL- Sequenzy dashboard base URL used by app URL helpers. Defaults tohttps://sequenzy.com.
Claude Desktop
Add this to your Claude Desktop config:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"sequenzy": {
"command": "npx",
"args": ["-y", "@sequenzy/mcp"],
"env": {
"SEQUENZY_API_KEY": "seq_user_your_key_here"
}
}
}
}
Restart Claude Desktop after editing the config.
Claude Code
claude mcp add --scope user --env=SEQUENZY_API_KEY=seq_user_your_key_here sequenzy -- npx -y @sequenzy/mcp
On native Windows, wrap npx with cmd /c:
claude mcp add --scope user --env=SEQUENZY_API_KEY=seq_user_your_key_here sequenzy -- cmd /c npx -y @sequenzy/mcp
For a shared project config, use .mcp.json:
{
"mcpServers": {
"sequenzy": {
"command": "npx",
"args": ["-y", "@sequenzy/mcp"],
"env": {
"SEQUENZY_API_KEY": "seq_user_your_key_here"
}
}
}
}
Codex
codex mcp add sequenzy --env SEQUENZY_API_KEY=seq_user_your_key_here -- npx -y @sequenzy/mcp
codex mcp list
Manual Codex config in ~/.codex/config.toml:
[mcp_servers.sequenzy]
command = "npx"
args = ["-y", "@sequenzy/mcp"]
[mcp_servers.sequenzy.env]
SEQUENZY_API_KEY = "seq_user_your_key_here"
Cursor
Install Sequenzy from the Cursor Marketplace for a hosted connection with Sequenzy OAuth. The plugin connects to:
https://api.sequenzy.com/v1/mcp
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.
For a manual local stdio setup instead, add this to ~/.cursor/mcp.json:
{
"mcpServers": {
"sequenzy": {
"command": "npx",
"args": ["-y", "@sequenzy/mcp"],
"env": {
"SEQUENZY_API_KEY": "seq_user_your_key_here"
}
}
}
}
Windsurf
Use the same JSON shape as Cursor.
- macOS:
~/Library/Application Support/Windsurf/mcp.json - Windows:
%APPDATA%\Windsurf\mcp.json
VS Code Copilot
VS Code uses a servers object:
{
"servers": {
"sequenzy": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@sequenzy/mcp"],
"env": {
"SEQUENZY_API_KEY": "seq_user_your_key_here"
}
}
}
}
Other MCP Clients
For OpenClaw, Hermes, and other MCP-compatible clients, point the client at npx -y @sequenzy/mcp and set SEQUENZY_API_KEY.
Getting an API Key
- Open the Sequenzy dashboard.
- Use the MCP setup flow to create a personal key, or open Settings -> API Keys to create a company key.
- Choose a permission preset or the exact custom scopes the integration needs.
- Add the key to your MCP client config.
Personal keys start with seq_user_. You can revoke them any time in the dashboard.
Company keys can also be cleaned up without exposing secrets. Call
list_api_keys to compare the key ID, name, non-secret prefix, permissions,
last-use timestamp, and isCurrent marker, then pass the exact ID to
revoke_api_key. delete_api_key is a compatibility alias for the same
permanent operation. List and revoke responses never contain the plain key or
stored key hash.
Recover from missing API key permissions
If a tool reports a missing scope such as campaigns:read or
templates:write, call get_account. Its apiKeyPermissions field lists the
current key identity and type, scopes, common missing marketing read scopes, and
a direct manageUrl. The OpenAI-reviewed route returns the same permissions
without the user's account ID or the active key's identity. Personal keys open
Account API Keys; company keys open the selected workspace's API Keys settings.
If the key does not include
account:read, open the
Sequenzy dashboard directly and choose the
matching API Keys page.
Permissions are editable in place, so open manageUrl. For a company key, use
list_api_keys and its isCurrent flag to identify the active key before
editing it, then retry the failed tool without replacing the credential or
restarting the client. An agent using a company key with api_keys:manage can
instead call update_api_key; personal keys must be edited on the account-level
page because that tool only manages company keys. Its scopes and preset
inputs replace the whole permission selection rather than merging, so preserve
every existing scope that is still needed. Hosted OAuth connections can
alternatively disconnect and reauthorize with broader permissions.
When the active key itself lacks api_keys:manage, call
request_api_key_handoff instead of retrying update_api_key. It requires
account:read and returns an owner-review URL with the requested key name,
permissions, and optional predecessor prefilled. It never creates or returns a
key; the workspace owner reviews the form, creates the replacement in the
browser, and copies it into the client. Pass replaceApiKeyId: "current" to
offer revocation of the active key after the replacement is created. If the
active key also lacks account:read, use the dashboard directly.
The default Safer agent access preset includes lists:write and
tags:write, so agents can create and update list and tag definitions, and it
includes subscribers:tag for applying tags to existing contacts. It also
includes ab_tests:read, ab_tests:write, and sequences:write, so agents can
audit and edit sequence A/B variant copy, including cart and browse abandonment
messages. It does not include subscribers:write, so it cannot add contacts to
lists or remove them from lists. Deleting a list or tag still requires the
matching lists:delete or tags:delete permission.
The AI drafting preset includes subscribers:write, so drafting agents can
build a list as well as create it. Imports that apply listIds also need
lists:write; sequence enrollment or double-opt-in delivery additionally needs
automations:trigger.
Tools
The standard surface currently exposes 243 MCP tools. The OpenAI-reviewed surface exposes 237; only the six operations listed above are omitted.
Tools reject arguments they do not declare instead of silently ignoring them. Errors name the unsupported fields, list the supported arguments, and provide focused guidance for common mistakes such as invented subscriber filters or sort options.
Account, Companies, Setup
get_sending_status keeps the Postgres-backed pause state, review gates, and
remediation available when sender-health analytics are temporarily unavailable;
in that degraded case senderHealth is null.
render_email returns unresolvedMergeTags so callers can distinguish an
unknown name from a recognized tag that is merely blank for the previewed
contact. Unknown names are reported even when a default filter supplied text:
for example, {{ subscriber.frstName | default: "there" }} renders a plausible
greeting for every contact while bypassing stored first names. A recognized
name that is blank for one contact is not reported when its default is used.
The OpenAI-reviewed route rejects restricted custom-attribute selectors inside
merge tags. It also omits the subscriberId argument; use a policy-checked
inline subscriber, or omit subscriber data for a sample preview.
To render a sequence step whose nodeType is action_ab_test, pass the
step's sequenceId and nodeId together with a variantId from
get_sequence.sequence.emails[].abTest.variants. These steps have no email of
their own, so the variant is required; reading and rendering their competing
copy also requires the ab_tests:read scope.
For Supabase, sync_integration reuses the project, schema, table, list
selection, and consent mappings saved in the dashboard. It cannot target an
arbitrary table. Run it after installing the live database trigger to import
users who existed before the trigger was installed, then poll get_integration
and list_integration_activity for progress and row-level outcomes.
set_integration_sync_enabled controls bulk imports and backfills only; it
does not stop a provider's live webhook from creating contacts. Use
set_integration_list_targeting to choose their future list memberships:
null follows workspace defaults, [] joins no list, and a populated array
targets those lists. The change is not retroactive and never removes existing
memberships. It also does not stop default any_contact sequences, which
enroll list-less contacts; explicit any_list and specific-list sequences
require a matching membership. Pair list targeting with
pause_sequence_enrollments when those default enrollments must stop too.
Supabase, Stripe, Shopify, Wix, and Webflow support this control.
For PostHog, sync_integration restarts the event-history import from the
beginning with the stored personal API key. Imported events are deduplicated, so
retrying a failed import does not create duplicates.
For Segment, connect_integration on standard MCP can optionally import recent
event history from Unify after the live webhook is connected. The import walks
existing contacts through the Profile API, covers the API's most recent 14 days,
skips contacts without a matching profile, and safely deduplicates retries and
live webhook overlap. New connections skip automatic page/screen calls unless
those names are explicitly allowlisted. Segment webhook secrets must be 16-153
UTF-8 bytes. On the OpenAI-reviewed route, which omits connect_integration,
connect Segment in the dashboard or local CLI instead. Use sync_integration
to retry with the saved credentials.
For Lemon Squeezy, pass provider: "lemon_squeezy", an API key, and the
numeric store ID as providerAccountId. Omit webhookSecret for the default
managed setup; the response reports webhookProvisioning and testMode.
Provide a 16-40 character signing secret only for manual webhook setup, using
the returned webhookUrl. Credentials are never returned.
For Attio, connect_integration on standard MCP accepts a workspace access
token without a webhook secret, with optional settings.listMap as a map of
Sequenzy list IDs to Attio people-list UUIDs or API slugs, plus
syncCompanyFromDomain to control company matching from non-free-mail domains.
On the OpenAI-reviewed route, connect Attio in the dashboard or local CLI, then
use update_attio_settings for the same settings. The integration is
outbound-only:
new joins to mapped Sequenzy lists upsert the person and add them to the Attio
list; list removals do not remove records from Attio.
Call get_event_schema before writing an {{event.*}} merge tag or an event
property filter. Omit eventName to list documented built-in events; provide
an event name to receive provider-specific example payloads and property paths,
and optionally filter by provider. Custom event names remain valid even when
the result reports documented: false; that only means no reference sample is
published. Use integration activity or sequence enrollments for actual delivery
data because this tool returns static reference data.
For a new sending domain, call add_sending_domain, publish the DNS records in
the returned website.dnsRecords, wait for DNS propagation, and then call
verify_sending_domain. Publish every returned record instead of assuming a
fixed provider or record count: unified domains include required DMARC, while
legacy domains can return Amazon SES MAIL FROM and inbound-reply records. If
verification is attempted before creation, the error points back to
add_sending_domain with the requested domain.
For Shopify, call get_integration_pixel before relying on product views,
cart activity, or browse-abandonment triggers. The result is read live from
Shopify because merchants can remove the pixel independently. If
pixel.healthy is false, dependentEvents names the triggers that cannot
arrive; call activate_integration_pixel to install or repoint the pixel.
Activation is idempotent, and events begin on the next storefront visit rather
than being backfilled.
For custom, headless, ticketing, or SaaS websites, use
list_web_tracking_keys before relying on product-view or cart triggers. Create
a key with an explicit origin allowlist, install the returned installSnippet,
then have the customer's authenticated backend mint a short-lived proof through
POST /api/v1/web-tracking-identities and call
sequenzy.identify(email, identityToken) at sign-in or checkout. A publishable
key alone only records anonymous activity and cannot trigger subscriber
automation. The returned snippet installs synchronous method stubs before its
async loader, so identity and event calls made during page bootstrap are queued
until the SDK is ready. Prefer revoking a key with update_web_tracking_key
before permanently deleting it.
New companies start with no sync rules. The inherited preset remains available
for SaaS/ecommerce companies by passing null to update_sync_rules; services
and consulting companies should normally keep [] or define explicit rules.
Use list_sender_profiles to find the profile ID, then call
update_sender_profile to change only its display name. Pass type: "reply"
for a reply-to profile; sender is the default. The address, sending domain, and
account-wide default From/Reply-To selections remain unchanged. Renaming
requires the companies:manage scope.
Use delete_sender_profile to permanently remove an obsolete From identity.
It refuses the last sender and any profile used by a live campaign, active
sequence (including a step override), or transactional email. Eligible drafts
and account defaults move to the returned fallbackSenderProfileId; review it
before sending. Reply-to profiles are not supported by this delete tool.
Shopify cart abandonment is enabled by default. It fires
ecommerce.cart_abandoned after one hour of cart inactivity, with a 24-hour
per-subscriber cooldown. Use update_shopify_automation_settings to change the
cartAbandonment.enabled, delayHours, or cooldownHours fields; pass
cartAbandonment: null to restore those defaults without changing browse
abandonment or price-drop settings. Timing values must be positive;
delayHours is capped at 168 and cooldownHours at 720.
Subscribers
Use create_subscriber_import for CRM onboarding instead of looping over
add_subscriber. One call accepts 5,000 full records and returns an asynchronous
import ID; poll it with get_subscriber_import. A completed import can still
contain row failures, so inspect failedCount and failedReasons. Every
excluded row is accounted for: skippedReasons sums to skippedCount, and
failedReasons sums to failedCount. Report any shortfall with the import ID
instead of guessing which rows were omitted. When email hygiene is enabled,
deliverability checks continue separately after ingestion and results appear
in List health; import status does not wait for or include those verdicts.
Invalid verdicts are suppressed from later sends. Use optInMode: "confirmed"
only when consent was already verified.
For import_subscriber_events, email is required when a row may create a new
contact; externalId can stand alone only for an existing contact. Supply a
stable eventId on every row. Retrying reuses the original receipt and
idempotently re-attempts downstream recovery. Historical classification is per
contact: if any row for a contact is recent, that contact's whole group uses
the live side-effect path.
For compliance suppression, call update_subscriber with
status: "unsubscribed" (or use remove_subscriber without hardDelete). Do
not retry add_subscriber with a different status: status on that tool applies
only when the contact is first created, and a mismatched skipped result is
reported as an error.
When add_subscriber omits listIds, a contact created by the call follows
the workspace default lists while an existing contact keeps its current list
memberships. Pass list IDs explicitly when an existing contact should join
specific lists; pass [] to target no lists.
update_subscriber.phone writes the native phone field shown on the contact,
not a custom attribute. Pass smsConsent: true only after verifying express
written consent, or false to opt the contact out. Changing the phone without
smsConsent resets SMS consent because consent belongs to the old number.
add_subscriber, update_subscriber, and create_subscriber_import accept an
IANA timezone such as America/New_York. The value is stored on the native
contact profile and enables recipient-local campaign delivery. Pass an empty
timezone to update_subscriber to clear it; invalid import-row values are
ignored without rejecting the rest of the import.
Products & Digital Delivery
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}}.
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.
Image Assets
The tool accepts PNG, JPEG, GIF, and WebP images up to 5MB. Local stdio clients
can pass filePath. Hosted/remote clients that can access attachment bytes can
pass imageBase64 with filename. Provide altText for accessibility, then
use displayWidthPercent, cropHeight, objectFit (cover or contain), and
align to standardize screenshot presentation. The returned imageBlock can
be copied directly into the block array accepted by campaign, sequence,
template, and transactional-email tools.
Authenticated image bytes are always uploaded to the origin configured by
SEQUENZY_API_URL, even if a reverse proxy returns an equivalent upload URL
under another host. API credentials are never forwarded to that alternate
origin.
{
"filePath": "/Users/me/Desktop/product-results.png",
"altText": "Product results dashboard",
"displayWidthPercent": 100,
"cropHeight": 320,
"objectFit": "cover",
"align": "center"
}
Lists, Tags, Segments
For subscriber exports, search_subscribers accepts listId, exact listName,
or list (ID first, then exact name). It also accepts attribute plus
attributeValue, with attributeOperator for contains, numeric comparisons,
or is_not_empty; the combined "attributeName:value" form remains supported.
Filters combine with AND; use a saved segment for OR logic, nested groups,
exclusions, engagement, or event conditions. If limit is omitted, the tool
fetches every matching page automatically. For chunked reads, pass limit and
follow pagination.nextCursor (or pagination.nextOffset) while hasMore is
true. offset and page are supported below 1,000,000 skipped matches; use the
cursor for deeper audiences.
For bulk list population, use add_subscribers_to_list; the backing API endpoint is POST /api/v1/lists/{listId}/subscribers with no /bulk suffix:
{
"emails": ["[email protected]", "[email protected]"],
"duplicateStrategy": "skip",
"enrollInSequences": false,
"optInMode": "default"
}
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.
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.
For array-of-object attributes, use wildcard paths such as
history_events[].eventvenue_id:2103. When an AND group also filters
history_events[].showing_date, both conditions must match one shared
history_events[] element; values from unrelated history entries are not
combined. Deleting a segment requires segments:delete; segments:write is
not sufficient.
Each segment filter field validates its own operators:
status,segment:is,is_nottag:contains,not_contains,is_empty,is_not_emptyemail:contains,not_containsemailProvider,list:is,is_not,is_empty,is_not_emptyfirstName,lastName:contains,not_contains,is_empty,is_not_emptyadded:less_than,more_thanattribute:is,is_not,is_empty,is_not_empty,gte,lte,gt,lt,contains,not_containsevent, email engagement fields:is,is_not,at_least,less_than_countemailBounced: also supportsis_temporary_bounce,is_permanent_bouncestripeProduct:is,is_not,at_least,less_than_countstripeCurrentProduct,stripeTrialProduct:is,is_not,gte,lte,gt,ltcommerceProduct:is,is_not,at_least,less_than_count
Stripe product filter examples:
{ "field": "stripeProduct", "operator": "is", "value": "prod_pro" }
{ "field": "stripeProduct", "operator": "is_not", "value": "prod_pro" }
{ "field": "stripeProduct", "operator": "at_least", "value": "prod_pro:3" }
{ "field": "stripeProduct", "operator": "less_than_count", "value": "prod_pro:3" }
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:
{ "field": "commerceProduct", "operator": "is", "value": "api:starter-kit" }
{ "field": "commerceProduct", "operator": "at_least", "value": "shopify:42:2" }
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.
Audience Syncs (Meta Ads)
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.
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.
Templates
list_templates returns 50 email bodies newest first by default and accepts a
limit up to 100. Advance offset by pagination.count while
pagination.hasMore is true; pagination.total reports the full matching
count, including campaign and transactional-email bodies.
Set isTemplate: true on list_templates to return only saved master designs,
or false to return ordinary email bodies. Marked masters are offered as
starting points for dashboard sequence steps and campaigns; starting from one creates
an independent copy so edits leave the master intact.
Standalone/sequence source-design copying and AI rewriting within a selected layout are currently
dashboard-only. This release intentionally keeps those workflows in interactive
authoring, where users can review the source, translations, and any fallback copy
before saving a sequence step. REST, CLI, and MCP expose no equivalent standalone/sequence source-design
operation. create_template with prompt generates new content without preserving
an existing layout; supplied HTML or blocks create a new body without automatically
copying localized variants. See the interface availability documentation.
Campaign copies already work through REST POST /api/v1/campaigns and MCP
create_campaign with templateId; it cannot be combined with prompt for an AI rewrite.
For net-new content requested in natural language, pass prompt so Sequenzy
generates branded native blocks server-side. Use blocks only for finished
caller-supplied Sequenzy content, and use html only when preserving supplied
or explicitly requested markup. prompt, blocks, and html are mutually
exclusive; style and tone are valid only with prompt.
Use set_template_localization when translated copy comes from your own
localization workflow. It requires an enabled non-primary locale, a localized
subject, and exactly one of html or blocks. Use
sync_template_localizations to ask Sequenzy to translate selected locales;
omit locales to sync every enabled non-primary locale. Explicit sync works
even when automatic on-save localization is disabled.
Reusable Email Components
Components are copied into emails when those emails are built, so later edits affect newly built emails rather than rewriting existing content. The default footer keeps its unsubscribe link enabled, while transactional rendering hides that link. Raw HTML emails keep their own markup and do not receive block components; their send-time unsubscribe handling remains unchanged.
A/B Tests
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.
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.
Campaigns
Prompt-created campaigns are generated and persisted in one API request and
remain drafts. Use templateId, blocks, or html only when copying or
preserving existing content rather than asking the agent to author it. Omit all
content fields to create an empty draft for later editing.
Campaign goals credit recipients who were actually sent that campaign within
the configured attribution window; an open or click remains the stronger
last-touch signal when one exists. Event goals require triggerEventName,
subscriber-attribute goals require attributePath, and tag-applied goals
require triggerTagName. The campaign attribution window defaults to 168
hours when omitted.
To deliver at the same wall-clock time in every recipient's own timezone, call
schedule_campaign with sendInRecipientTimezone: true and an IANA
scheduledTimezone that identifies the wall clock represented by
scheduledAt. Contacts without a stored timezone receive the campaign at the
scheduledAt instant. This mode cannot be combined with recurring or spread
delivery.
Send Time Optimization is configured per campaign, not at the company or
sequence level. Audit it across campaigns with list_campaigns, or inspect one
campaign with get_campaign. Set sendTimeOptimization and
sendTimeWindowHours (1-24, default 12) on a draft with update_campaign, or
override them while scheduling with schedule_campaign. spreadOverHours
takes precedence and disables STO, as does recipient-timezone delivery.
Sequences instead use sendingWindow, a shared allowed-hours/days gate rather
than per-recipient predicted send times.
For campaign- and sequence-level identities, fromEmail plus fromName
selects the sender identity with that display name on the mailbox, creating it
when needed without renaming other same-address identities. A Reply-To address
instead has one company-wide saved name: when replyToName differs from that
name, the saved name is kept and the successful response includes recovery
guidance in warnings.
send_email and send_test_email return a durable emailSendId. Use
list_email_sends to discover recent IDs by subject/title, recipient, delivery
status, type, bounce type, or source; pass an ID to get_email_send to inspect
status, errorMessage, the stored body, and delivery events. Delivery-list
rows are retained for 14 days. Successful live-test and other test sends are
omitted so they do not bury real deliveries. Replies to those test sends show
in list_conversations only when inbound reply capture is enabled. Queue jobs
are internal execution details and
are not exposed through the MCP contract. Every returned delivery has a direct
dashboard url. Use list_recipient_suppressions to distinguish protected
global invalid-recipient, protected company hard-bounce, and complaint rows from removable company soft-bounce
escalations, and use get_recipient_suppression for the exact regional status.
remove_recipient_suppression removes only the company escalation; global and
Amazon SES account-level suppressions, complaints, unsubscribes, and email-hygiene
protections remain intact. A local hygiene result uses the bounced reason with
email_hygiene as its source without changing the subscriber's consent status.
Agents should pass a caller-owned idempotencyKey to send_email before the
first attempt and reuse it for every retry of that same logical email. Sequenzy
returns the original emailSendId for 14 days instead of creating another
delivery. Reusing the key with different send arguments is rejected, so do not
generate a fresh key inside a retry loop.
Email blocks may use conditional display rules or conditional-group branches.
Conditions support render-time variables and subscriber attributes plus live
subscriber data such as segment/list membership, tags, events, engagement,
subscription/SMS status, and Stripe or commerce purchases. Live-data
conditions use the same field values and operators as segment filters;
recipients without a stored subscriber match use the OTHERWISE branch.
Core block shapes are { "type": "heading", "content": "Title", "level": 1 }, { "type": "text", "content": "<p>Copy</p>" }, { "type": "button", "text": "Book a call", "url": "https://example.com", "variant": "primary" } , and { "type": "image", "src": "https://...", "alt": "Description", "width": 100, "widthType": "percent" }. Buttons also accept content as an
alias for text and default to the primary variant. Image widthType accepts
percent or px.
YouTube video blocks accept an optional custom cover: { "type": "video", "videoUrl": "https://www.youtube.com/watch?v=...", "thumbnailUrl": "https://cdn.example.com/cover.jpg", "alt": "Watch the product tour" }.
Replacing blocks without thumbnailUrl restores YouTube's own still while
keeping videoUrl as the click destination.
Raw html is stored as one opaque block. It preserves supplied markup but does
not add a company logo, native branded sections, or theme-driven block design.
Use prompt for a new branded draft or blocks for editor-native design; MCP
authoring results include a warning when raw HTML is used.
Use update_company with fromEmail and/or replyTo to set account-wide
defaults. fromEmail must use a configured, verified sending domain; replyTo
may be any valid mailbox. create_campaign, update_campaign,
create_sequence, and update_sequence accept the same direct-address fields
for resource-specific overrides and create the backing profile when needed.
Send fromName or replyToName alone to rename the existing default profile
without changing its address. When an address has multiple display names, use
senderProfileId or replyProfileId from list_sender_profiles to select the
exact profile to make default and rename.
update_company also manages the company's default email theme through
emailTheme (presetId, colors, typography, layout). Theme updates are
partial - omitted fields keep their current value (or the preset default) and
numeric values are clamped to supported ranges. Pass emailTheme: null to
reset the company to the platform default theme. Layout settings can control
the shared baseRadius and a separate buttonRadius. Within colors,
background paints the outer canvas, content paints the inner content card,
and surface paints nested cards or tinted tiles. Omitting content preserves
its current value; when no content color is stored, the card follows
background.
Reply tracking is available on the same company tools. Use
replyTrackingEnabled, replyTrackingDomainMode (sequenzy or custom), and
forwardReplies with update_company. Company reads also return the current
read-only replyRetentionDays value.
Polls and NPS surveys are native email blocks, so they work anywhere an email
tool accepts blocks, including campaigns, templates, A/B variants,
transactional templates, and sequence email steps. Transactional poll sends
must resolve to exactly one effective recipient after suppression filtering and
recipient deduplication, and that recipient must already exist as a subscriber;
otherwise Sequenzy rejects the send because the answer link cannot be safely
attributed. Use an answer-button poll:
{
"type": "poll",
"variant": "options",
"question": "What did you think of this email?",
"options": [
{ "label": "Loved it", "value": "loved" },
{ "label": "Not for me", "value": "not_for_me" }
],
"attributeKey": "email_feedback"
}
For NPS, use "variant": "nps", an empty options array, and an attribute
such as nps_score. The scale is always 0-10; optional npsLowLabel and
npsHighLabel customize its captions. Each answer updates the subscriber
attribute and fires poll.answered for automations and outbound webhooks.
Set "allowMultiple": true on a text-only options poll to open a hosted page
where recipients can check several answers and save the whole selection at
once. The subscriber attribute stores the selected-value list, so attribute
segments should use contains. Multi-select polls cannot use option images or
configurations whose encoded signed links exceed the delivery-safe size limit.
Campaign poll summaries set allowMultiple: true, use respondent count for
totalResponses, and can report answer percentages that add up past 100%.
Poll blocks also support brand-specific styling. accentColor recolors every
appearance, including "brutal"; optionRadius sets answer-button corners in
pixels (0 is square), independently of the container's
styles.borderRadius; and questionColor recolors only the question.
fontFamily applies to the poll. Use the optionFontSize,
optionFontWeight, optionLetterSpacing, and optionTextTransform fields for
answers, or the matching question* fields for the question. Sizes and
spacing are pixels, weights range from 100 to 900, and text transforms are
"none" or "uppercase".
Saved Forms
For Astro, Hugo, Jekyll, Cloudflare Pages, Netlify, GitHub Pages, or any other
static site, call list_forms, use create_form if a suitable form does not
exist, then call get_form_embed. The returned opaque formId is the public
capability: lists, tags, duplicate behavior, and success handling remain
server-side, so the deployed browser code never contains a Sequenzy API key.
Generated native and standalone markup includes "Powered by Sequenzy" for free
workspaces; paid workspaces receive unbranded markup. The API resolves that
entitlement server-side, so callers should use the returned snippet unchanged.
When updating a form, omitted fields remain unchanged and theme fields merge
into the current theme. Pass an empty tagIds array to clear tags or an empty
redirectUrl to restore confirmation-message behavior. The blocks field is
a complete replacement, so read the current content with list_forms first
and retain exactly one required email field and one submit button. Add custom
inputs as form-field blocks with a supported fieldType; select, radio, and
checkbox fields require options, while hidden defaults are enforced server-side.
Saved Popups
Popup deployment uses one public script tag; API keys, audience settings,
triggering, targeting, scheduling, and frequency rules remain server-side.
Popups capture into every list by default unless listIds is provided. When
updating blocks, read the popup first and send the complete replacement array,
retaining exactly one required email field and one submit button. Setting
`stat
