Build and manage RightMessage from your AI assistant.

List all segment groups (dimensions) for a team. In the RightMessage UI, segment groups with a linked question are displayed as "Questions" — this tool returns the underlying dimension data. Each result includes a hasQuestion flag. Use list-questions to see the question text and answer options for each.

Get a single segment group (dimension) by ID. In the RightMessage UI, segment groups with a linked question appear as "Questions." To see the question text and answer options linked to this segment group, use get-question with the question that has this dimension ID.

Create a new segment group (dimension) for a team. In the RightMessage UI, segment groups are displayed as "Questions" when they have a linked question. IMPORTANT: If this segment group will be used as a question in a flow, you must ALSO call create-question to link a question to it — otherwise the flow node will have nothing to display. Set auto_create_question=true to automatically create both the segment group AND its linked question in one step (recommended). For quiz dimensions, use auto_create_question=true and pass per-option scores inline in the segments array — this is the canonical one-shot path and avoids N separate update-question-option retrofits. You can also add signals (automatic segment detection rules) — use list-condition-sources to see available condition types for signal definitions.

Update an existing segment group (dimension) for a team. In the RightMessage UI, segment groups with a linked question appear as "Questions." Supports partial updates — only provided fields are changed. To update the question text or answer options, use update-question instead. You can add or replace signals (automatic segment detection rules) using the signals parameter.

Delete a segment group (dimension) and cascade-remove its linked question (if any), funnel nodes, and phrases. In the RightMessage UI, segment groups with a linked question appear as "Questions" — deleting the segment group also deletes the question.

List all survey questions configured for a team. Questions are what users see in the RightMessage UI — each question is linked to an underlying segment group (dimension) that stores answers as segments. Returns question IDs, text, display types, linked dimensions, and options.

Get a single survey question by its ID. Each question is linked to a segment group (dimension) that stores answers as segments. Returns question text, display type, linked dimension, options with segment mappings, and other settings.

Create a new survey question for a team. The question is added to the draft config. Link it to a segment group via segment_group_id so that answers are stored as segments. IMPORTANT: A segment group (dimension) must exist BEFORE creating a question for it — use create-segment-group first, or use create-segment-group with auto_create_question=true to create both at once. Each answer option should map to a segment via segment_id. This question is required for any flow "sg" node that references the same segment group — without it, the flow node will be broken.

Update an existing survey question. Only the provided fields will be changed (partial update). Updates the draft config. To update the underlying segment group (dimension name, segments, sync settings, signals), use update-segment-group instead.

Delete a survey question from the draft config. This removes the question and all its options permanently. Note: this does NOT delete the underlying segment group (dimension) — use delete-segment-group to remove both the segment group and its linked question.

List all campaigns for a team.

Get a single campaign by ID.

Create a new personalization campaign for a team. A campaign personalizes website content for different audience segments. Each campaign contains variants that target specific audiences using dimension/segment rules, and each variant defines what content changes to make. ## Creating a campaign with content changes Pass a `changes` array where each object describes one content modification: ```json { "name": "Homepage Personalization", "base_url": "example.com/", "changes": [ { "selector": "h1.hero-title", "segment_ids": "seg_saas, seg_growth", "page": "example.com/", "content": "Scale Your SaaS to $10M ARR" }, { "selector": "h1.hero-title", "segment_ids": "", "page": "example.com/", "content": "Grow Your Business Faster" } ] } ``` Changes with identical `segment_ids` are grouped into one variant. Empty `segment_ids` = default/fallback variant. ## Page targeting Use `page` to restrict changes to specific URLs. Format: "domain/path" (comma-separated for multiple). - `"example.com/"` - exact homepage - `"example.com/pricing"` - pricing page - `"*/blog"` - blog on any domain ## Segment targeting Use `segment_ids` as a comma-separated string of segment IDs (e.g. "seg_saas, seg_growth"). Use list-condition-sources to discover available dimensions and segments. ## Changes fields - `selector`: CSS selector for the element to modify. Required unless `targeting` is provided. - `targeting`: Smart Match targeting object from `get-page-elements`. When provided, the client-side personalizer uses fingerprint matching (text content, DOM structure, semantic hints) instead of brittle CSS selectors. Format: `{"mode": "fingerprint", "fingerprint": {...}, "fallbackSelector": "..."}`. **Always use this when available from `get-page-elements` — it's far more reliable than CSS selectors.** - `segment_ids`: comma-separated segment IDs (empty string = default variant) - `page`: URL patterns (comma-separated "domain/path") - `content`: the new text for the element. Each element should get its own change/action — even if two elements have the same text (the fingerprint differentiates them). For partial edits within an element (e.g., swapping "SaaS" to "Agency" without replacing the full paragraph), use `/find text/replace text/` format. - `visibility`: "show" or "hide" - `style`: CSS overrides object (e.g. {"color": "red"}) - `attr`: HTML attribute overrides (e.g. {"href": "/new-link"}) - `add_classes`: comma-separated CSS classes to add - `remove_classes`: comma-separated CSS classes to remove Creating a campaign without `changes` creates an empty campaign with no variants.

Update an existing campaign. Only provided fields will be changed. ## Updating content changes Pass a new `changes` array to replace all existing variants/content changes. The format is the same as create-campaign: ```json { "campaign_id": "cpn_abc12345", "changes": [ { "selector": "h1.hero-title", "segment_ids": "seg_saas", "page": "example.com/", "content": "Built for SaaS Companies" }, { "selector": "h1.hero-title", "segment_ids": "", "content": "Grow Your Business" } ] } ``` IMPORTANT: `segment_ids` must be a comma-separated STRING, not an array. Example: "seg_saas, seg_growth" (not ["seg_saas", "seg_growth"]). ## Page targeting Use `page` field on each change to restrict modifications to specific URLs: - `"example.com/pricing"` - only the pricing page - `"*/blog*"` - any blog page on any domain - Omit `page` to apply to all pages Use list-condition-sources to discover available dimensions and segments for targeting.

Delete a campaign from the team configuration.

Duplicate an existing campaign. Creates an exact copy with a new ID, optional new name (defaults to "Original Name (Copy)"), and fresh variant/action IDs. The duplicate is saved to the draft config.

List all widgets for a team. Note: for inline/embedded widgets, RightMessage does not track which pages they appear on (they render wherever the embed code is placed). To see actual pages, use get-flow-performance and check exposurePages for the linked flow.

Get a single widget by ID. Note: for inline/embedded widgets, RightMessage does not track which pages they appear on. To see actual pages where the widget's flow runs, use get-flow-performance.

Create a new widget for a team.

Update an existing widget (modal, bar, toaster, inline, or takeover). Only provided fields will be changed. ## Common operations **Attach or swap a flow on a widget:** ```json {"widget_id": "wdg_abc12345", "flow_id": "ofn_xyz789"} ``` **Change widget type and trigger:** ```json {"widget_id": "wdg_abc12345", "type": "bar", "visibility": {"trigger": "immediate"}} ``` **Enable/disable a widget:** ```json {"widget_id": "wdg_abc12345", "is_enabled": false} ```

Delete a widget from a team.

Duplicate an existing widget. Creates an exact copy with a new ID and optional new name (defaults to "Original Name (Copy)"). The duplicate is saved to the draft config.

List all flows (offer funnels) for a team.

Get a single flow's metadata, stats, and flat node list (for editing). Does not include branching logic or node connections. To understand how visitors traverse a flow, use get-flow-summary instead.

Create a new flow (offer funnel) for a team. Flows define the visitor journey through questions, conditional branches, offers, and redirects. ## Minimal flow example (empty) ```json {"name": "My Flow"} ``` Omitting `definition` creates an empty flow with a root node and no children. ## Flow with a question (sg node) ```json { "name": "Onboarding Quiz", "definition": { "type": "root", "child": [ { "type": "sg", "segmentGroupId": "dim_businessType", "ask": true, "split": false } ] } } ``` IMPORTANT: `sg` nodes require BOTH `ask` (boolean) AND `split` (either `false` or an array of branch objects). The `segmentGroupId` must reference a dimension that has a linked question (created via create-question). ## Flow with conditional branching (yesno node) ```json { "definition": { "type": "root", "child": [ { "type": "yesno", "condition": { "and": [{"$source": "segments", "$type": "dim_businessType", "operator": "include any", "segmentId": ["seg_saas"]}] }, "yes": [ {"type": "redirect", "url": "https://other.example/saas", "open": false, "sendSubscriberData": true} ], "no": [ {"type": "exit"} ] } ] } } ``` ## Node types - `sg`: Ask a question (requires segmentGroupId, ask, split) - `yesno`: Conditional branch (requires condition, yes, no) - `offer`: Show an offer (requires offerId) - `redirect`: Redirect to URL (requires url; optional open and sendSubscriberData, both default false). Use sendSubscriberData only for an absolute URL on another domain that also runs this RightMessage project; keep it false for same-site paths or same-origin URLs. - `data`: Track data/set segments (requires actions array) - `message`: Display message (requires content) - `code`: Execute custom JS (requires name, code) - `exit`: End the flow - `highscore`: Branch by score (requires split) - `random`: Random split (requires split) Use list-condition-sources to discover available condition sources/types/operators for yesno nodes. Use validate-condition to verify conditions before saving. ## System Flows Set `is_system_flow: true` to create a **System Flow** — a flow that runs automatically on every page view WITHOUT a widget. System flows contain no user-facing elements and are used for background automation: conditional tagging, setting ESP custom fields, running custom JavaScript, score-based routing. ```json { "name": "Auto-Tag by Page", "is_system_flow": true, "definition": { "type": "root", "child": [ { "type": "yesno", "condition": {"and": [{"$source": "pageview", "$type": "urlContains", "operator": "contains", "value": "/pricing"}]}, "yes": [{"type": "data", "actions": [{"type": "set_segment", "segmentId": "seg_pricing_visitor", "segmentGroupId": "dim_interest"}]}], "no": [{"type": "exit"}] } ] } } ``` System flows should only use action nodes: `data`, `code`, `webhook`, `yesno`, `highscore`, `redirect`, `random`, `exit`. Avoid `sg`, `offer`, `message` (those require a widget).

Create a complete flow from a plain-text description. The server's AI generates all required resources (dimensions, segments, questions, offers) and assembles the flow tree automatically. Use this instead of manually calling create-segment-group, create-question, create-offer, and create-flow-node in sequence. The server handles dependency ordering, ID generation, and deduplication against existing resources. ## When to use this tool - Building a NEW flow from scratch (quiz, survey, lead qualifier, onboarding sequence) - When the flow needs multiple questions, branching logic, and/or conditional offers - When you don't yet have the dimensions/questions/offers created For modifying an EXISTING flow, use modify-flow or update-flow-node instead. ## Examples **Simple survey:** ```json { "description": "Ask what type of business they run (SaaS, Agency, Consultant, E-commerce), then ask their biggest challenge (Getting leads, Converting leads, Retaining customers). Show a tailored offer for each business type.", "name": "Onboarding Quiz" } ``` **Lead qualifier:** ```json { "description": "First ask company size (1-10, 11-50, 51-200, 200+). If 51+, ask their role (Marketing, Sales, Engineering, Executive). Show a 'Book a Demo' CTA for executives and a 'Download Guide' offer for everyone else.", "name": "Lead Qualifier" } ``` **Populate existing flow:** ```json { "description": "Ask about their experience level (Beginner, Intermediate, Advanced) and show different resources for each level.", "name": "Resource Matcher", "target_flow_id": "ofn_existingFlow" } ```

Update an existing flow (offer funnel) by ID. Supports partial updates — only provided fields are changed. IMPORTANT: Flow nodes of type "sg" with ask:true require a linked question in rightAsk. If no question exists for the referenced segmentGroupId, the node will be broken. Always ensure a question has been created (via create-question) before adding an sg node to a flow. ## Example: Update flow definition ```json { "flow_id": "ofn_abc12345", "definition": { "type": "root", "child": [ {"type": "sg", "segmentGroupId": "dim_businessType", "ask": true, "split": false}, {"type": "exit"} ] } } ``` ## Node type requirements - `sg`: requires segmentGroupId, ask (bool), split (false or array) - `yesno`: requires condition (object), yes (array), no (array) - `redirect`: requires url (string); optional open (bool) and sendSubscriberData (bool), both default false. Use sendSubscriberData only for an absolute URL on another domain that also runs this RightMessage project; keep it false for same-site paths or same-origin URLs. - `data`: requires actions (array of {id, type, ...}) - `message`: requires content (string) - `code`: requires name (string), code (string) - `offer`, `exit`: minimal — just type Use list-condition-sources to discover available condition sources/types/operators. Use validate-condition to verify conditions before saving.

Delete a flow (offer funnel) by ID. Cascades: nullifies contentId on widgets referencing this flow.

Duplicate an existing flow. Creates an exact copy with a new ID, optional new name (defaults to "Original Name (Copy)"), and fresh node UUIDs. The duplicate is saved to the draft config.

Add a new node to an existing flow. Nodes are positioned relative to other nodes using the position parameter. ## Node type requirements - `sg`: requires segmentGroupId (string), ask (bool, defaults true), split (false or array, defaults false). The segmentGroupId must reference a dimension that has a linked question (created via create-question). - `yesno`: requires condition (object). The `yes` and `no` branches start empty; add children to them via separate create-flow-node calls using `position: {"parent": "<yesno_uuid>", "branch": "yes"}`. - `offer`: requires offerId (string referencing an offer). - `redirect`: requires url (string), optional open (bool, defaults false), optional sendSubscriberData (bool, defaults false). Set sendSubscriberData to true only for an absolute URL on another domain that also runs this RightMessage project; leave it false for same-site paths like `/pricing`. - `data`: requires actions (array of action objects with id, type, etc.). - `message`: requires content (string). - `code`: requires name (string), code (string). - `webhook`: requires url (string, must start with https://), method (string, defaults to POST), fireOnce (bool, defaults true), customPayload (string, optional additional context merged as "meta" key), timeoutMs (int, defaults 10000). Visitor context (segments, scores, email) is always included. - `exit`: no additional fields required. - `highscore`: requires split (array of branch objects with `{score, child}` each). Optional `mode`: `"scores"` (default, compare in-flow scores) or `"variables"` (compare persistent visitor variables). No null/fallback branch — ties go to the first branch in order. - `random`: requires split (array of branch objects). ## Position parameter (IMPORTANT) **Preferred: use `after`** — the simplest and most reliable positioning method. - `after`: UUID of any existing node. The new node is inserted immediately after it at the **same nesting level**, no matter how deep. The tree is searched automatically. **You do NOT need to specify `parent`.** - `parent` + `branch`: Insert into a specific branch of a parent node: - For `yesno` parents: branch must be `"yes"` or `"no"` - For `sg`/split parents: branch must be a **segment ID** (e.g., `"seg_abc123"`), NOT `"yes"`/`"no"` - For `random` parents: branch must be the **array index** (0, 1, 2, etc.) of the target branch - For `highscore` parents: branch must be the **array index** (0, 1, 2, etc.) of the target branch - Omit position entirely to append at the root level. **Common mistake:** Using `branch: "yes"` on an `sg` (split) node. Split nodes use segment IDs as branches (e.g., `"seg_umzbjk15"`), not `"yes"`/`"no"`. When in doubt, use `after` instead — it always works correctly. ## Example: Add a question node after another node inside a branch ```json { "flow_id": "ofn_abc123", "type": "sg", "data": { "segmentGroupId": "dim_businessType", "ask": true, "split": false }, "position": { "after": "550e8400-e29b-41d4-a716-446655440000" } } ``` ## Example: Add an offer into a random node's second branch ```json { "flow_id": "ofn_abc123", "type": "offer", "data": { "offerId": "ofr_holiday_sale" }, "position": { "parent": "random-node-uuid-here", "branch": 1 } } ```

Update properties of an existing flow node. Only provided fields are changed. ALWAYS call get-flow-summary FIRST to get the node UUIDs and current values. **Protected keys (cannot be set here):** `_uuid`, `type`, `child`, `split`, `yes`, `no`. These define tree structure — use `create-flow-node`, `delete-flow-node`, or `move-flow-node` to manage branches and children. ## Updatable fields by node type - **sg**: `segmentGroupId` (dimension ID), `ask` (bool) - **yesno**: `condition` (LogicDefinition object) - **offer**: `offerId` (offer ID, e.g. "ofr_abc123") - **redirect**: `url` (string), `open` (bool — open in new tab), `sendSubscriberData` (bool — include RightMessage visitor/subscriber context; defaults false). Set it to true only for an absolute URL on another domain that also runs this RightMessage project; leave it false for same-site paths like `/pricing`. - **message**: `content` (string — the message text) - **code**: `name` (string), `code` (string — JavaScript code) - **data**: `actions` (array of action objects) - **webhook**: `url` (string), `method` (string), `fireOnce` (bool), `customPayload` (string), `timeoutMs` (int) ## Examples ### Change a redirect URL ```json { "flow_id": "ofn_abc123", "node_uuid": "550e8400-e29b-41d4-a716-446655440000", "data": {"url": "https://other.example/new-page", "open": true, "sendSubscriberData": true} } ``` ### Change which offer a node shows ```json { "flow_id": "ofn_abc123", "node_uuid": "550e8400-e29b-41d4-a716-446655440000", "data": {"offerId": "ofr_newOffer1"} } ``` ### Update a message node's text ```json { "flow_id": "ofn_abc123", "node_uuid": "550e8400-e29b-41d4-a716-446655440000", "data": {"content": "Thanks for completing the survey!"} } ``` ### Change a yesno node's condition ```json { "flow_id": "ofn_abc123", "node_uuid": "550e8400-e29b-41d4-a716-446655440000", "data": { "condition": { "and": [{"$source": "segments", "$type": "dim_businessType", "operator": "include any", "segmentId": ["seg_saas"]}] } } } ``` ### Change which question an sg node asks ```json { "flow_id": "ofn_abc123", "node_uuid": "550e8400-e29b-41d4-a716-446655440000", "data": {"segmentGroupId": "dim_newDimension"} } ```

Remove a node from a flow. Child nodes of the deleted node are also removed.

Move a node to a different position within the same flow. The node is removed from its current location and re-inserted at the new position. ## Position parameter - `parent`: UUID of the new parent node. Omit to move to root level. - `after`: UUID of a sibling to place after. Omit to append at the end. - `branch`: For yesno parent nodes use "yes" or "no". For split parent nodes use the segment ID. ## Example: Move a node into the "yes" branch of a yesno node ```json { "flow_id": "ofn_abc123", "node_uuid": "550e8400-e29b-41d4-a716-446655440000", "position": { "parent": "660e8400-e29b-41d4-a716-446655440000", "branch": "yes" } } ```

Modify an existing flow using a simplified operations array. Preferred way to add yesno conditionals, questions, or other nodes to existing flows. Instead of constructing complex LogicDefinition JSON and orchestrating multiple sequential tool calls, send a single operations array and the server handles all the complexity. ALWAYS call get-flow-summary FIRST to get node UUIDs, dimension IDs, and segment IDs. ## Supported operations (as JSON array in `operations` parameter) - `insert_node`: Add a node. Requires `type` and positioning (`after` UUID or `parent`+`branch`). - For `yesno`: include simplified `condition`: `{dimension: "dim_xxx", operator: "include_any", segments: ["seg_xxx"]}` - For `sg`: include `dimension` (dim ID), optionally `ask` (default true) - For `offer`: include `offer_id` - Inline children: `yes_path`/`no_path` arrays on yesno (each child follows same format without positioning) - `delete_node`: Remove a node. Requires `node_uuid`. - `enable_split`: Convert sg from linear to branching. Requires `node_uuid`. - `update_node`: Modify node properties. Requires `node_uuid` and fields to update. ## Example — yesno with question on yes path ```json [{ "action": "insert_node", "type": "yesno", "after": "UUID_from_get_flow_summary", "condition": { "dimension": "dim_830jshhh", "operator": "include_any", "segments": ["seg_abc", "seg_def"] }, "yes_path": [ {"type": "sg", "dimension": "dim_PkmB3lhE", "ask": true} ], "no_path": [] }] ``` CRITICAL: Use IDs from get-flow-summary, not names.

List all offers for a team. Offers are items with action type "link" — CTAs that direct visitors to a URL. For forms and other action types, use list-forms.

Get a single offer by ID. Offers are items with action type "link" — CTAs that direct visitors to a URL. For items with other action types, use get-form instead.

Create a new offer (CTA) for a team. Offers have action type "link" — CTAs that direct visitors to a URL. For forms and other action types, use create-form.

Update an existing offer. Offers are items with action type "link" — CTAs that direct visitors to a URL. Supports partial updates with deep-merged parts and settings.

Delete an offer. Offers are items with action type "link". Cascades: nullifies offerId on any flow nodes that reference this offer.

Duplicate an existing offer. Creates an exact copy with a new ID and optional new name (defaults to "Original Name (Copy)"). The duplicate is saved to the draft config.

List all forms for a team. Forms are items with any action type other than "link" — includes form submissions, ESP tags, events, automations, etc.

Get a single form by ID. Forms are items with any action type other than "link" — includes form submissions, ESP tags, events, automations, etc.

Create a new form for a team. Forms have any triggeredAction type other than "link" — they handle data collection, ESP tagging, list subscriptions, etc. Supported action types: tag, list, automation, event, form, contact. Example — create a form that tags subscribers: ```json { "name": "Lead Magnet Download", "parts": {"title": "Get the Free Guide", "button_text": "Download Now"}, "triggered_action": { "type": "tag", "settings": {"platform": "convertkit", "tag_ids": ["downloaded_guide"], "thanks_message": "Check your email!"} } } ```

Update an existing form. Forms are items with any triggeredAction type other than "link". Supports partial updates — only provided fields are changed. Parts and action settings are deep-merged with existing values. ## Changing a form's submission action Use the `triggered_action` parameter to set or change what happens when the form is submitted. Supported types: - **tag**: Apply a tag in your ESP. Settings: `platform`, `tag_ids` (array of tag IDs/names), `thanks_message` - **list**: Add to a list. Settings: `platform`, `list_id`, `thanks_message` - **automation**: Trigger an automation. Settings: `platform`, `automation_id`, `thanks_message` - **event**: Fire a custom event. Settings: `platform`, `event_name`, `thanks_message` - **contact**: Create/update a contact. Settings: `platform`, `thanks_message` - **form**: Standard form submission. Settings: `platform`, `form_ids`, `tag_ids`, `fields`, `show_labels`, `thanks_message` Example — change a form to apply a tag on submit: ```json { "form_id": "ofr_abc12345", "triggered_action": { "type": "tag", "settings": { "platform": "convertkit", "tag_ids": ["3847291"], "thanks_message": "Thanks! Check your email." } } } ```

Delete a form. Forms are items with any action type other than "link". Cascades: nullifies offerId on flow nodes referencing this form.

Add a new field to an existing form. Appends the field to triggeredAction.settings.fields. Forms are items with any action type other than "link".

Update a specific field on an existing form by its 0-based index. Merges provided properties into the existing field.

Remove a field from an existing form by its 0-based index. Remaining fields shift down to fill the gap.

Duplicate an existing form. Creates an exact copy with a new ID and optional new name (defaults to "Original Name (Copy)"). The duplicate is saved to the draft config.

List all dynamic text phrases for a project. Phrases replace text based on visitor segments.

Get a single phrase by ID. Returns the phrase fallback text, linked dimension, and segment-to-text map.

Create a new dynamic text phrase. Phrases display different text based on which segment a visitor belongs to.

Update an existing phrase. Map entries are merged (not replaced) — to remove a map entry, set its value to null.

Delete a phrase from the project.

List all conversion goals for a team. Goals track user actions (clicks, pageviews, custom events) and are referenced by campaigns via goal_ids.

Get a single conversion goal by ID, including its events.

Create a new conversion goal for a team. Goals track specific user actions as conversions. Each goal contains events that define what counts as a conversion. ## Event types - **click**: Tracks clicks on a CSS selector. Requires `selector` and optionally `page`. - **pageview**: Tracks visits to specific pages. Requires `page`. - **custom**: Tracks custom JavaScript events by name. ## Events format ```json { "events": [ { "type": "click", "selector": ".checkout-button", "page": "example.com/checkout" }, { "type": "pageview", "page": "example.com/thank-you" } ] } ``` ## Page targeting Use `page` as a "domain/path" string (comma-separated for multiple): - `"example.com/pricing"` — specific page - `"*/thank-you"` — any domain, specific path Goals are referenced by campaigns via `goal_ids` to measure conversion rates.

Update an existing conversion goal. Only provided fields will be changed. Pass a new `events` array to replace all existing events. Each event: {type: "click"|"pageview"|"custom", selector?: "CSS selector", page?: "domain/path string"}. IMPORTANT: Updating events replaces the entire events array. Include all events you want to keep.

Delete a conversion goal. Also removes the goal ID from any campaigns that reference it via goal_ids.

List all personalized email records for a team. Each record contains the original email content and its AI-personalized Liquid version with segment-based conditionals.

Get a personalized email by its public ID (pid). Returns the original email content, the personalized Liquid version, rationale, affected segments, and instructions.

Create a new personalized email record. Provide the original email content and optional instructions for how to personalize it. After creation, the email is automatically processed by AI to generate a personalized Liquid version using the team's segmentation dimensions. Use get-personalized-email to check if processing is complete (completed_at will be set). ## Workflow 1. Use `get-email-personalization-context` first to understand the team's segmentation setup and Liquid syntax 2. Create the email with the original content 3. The AI automatically generates the personalized Liquid version 4. Use `get-personalized-email` to retrieve the result ## Instructions field Use `instructions` to guide the AI personalization: - "Focus on the headline and CTA button text" - "Only personalize for SaaS vs Agency segments" - "Keep the tone professional but vary the value propositions"

Update a personalized email record. Only provided fields will be changed. Use this to update the name or original email content.

Delete a personalized email record.

Add a new segment (answer value) to an existing segment group (dimension). Segments represent the possible values within a dimension (e.g. "SaaS", "Agency", "Consultant" within a "Business Type" question). If the segment group has a linked question, you should also use create-question-option to add a corresponding answer option that maps to this segment.

Update a segment's properties (name, description). Segments are the answer values within a question/dimension. Only provided fields are changed. Note: to update the corresponding question answer option label, use update-question-option. Signals/conditions are set on the parent segment group via update-segment-group, not on individual segments.

Delete a segment (answer value) from its segment group (dimension). Cascades: automatically removes question answer options linked to this segment, and removes phrase map entries for this segment.

Add a new answer option to an existing question. Each option can optionally map to a segment via segment_id, which links the answer to a dimension segment for visitor classification. You can also add conditions to control when this option is shown or hidden — use list-condition-sources to discover available condition types, and validate-condition to verify the condition object before saving.

Update a question option's properties (label, segment mapping, visibility conditions, scores). Only provided fields are changed. Use list-condition-sources and validate-condition to build valid conditions for controlling option visibility.

Delete an answer option from a question. This also removes the option's segment mapping and any conditions associated with it.

Create a new RightMessage project (team) for the authenticated user. Accepts a project name and website URL. The website is normalized (https:// added if missing, trailing paths stripped). A new project is created with the user as owner, and an initial configuration is set up automatically. Returns the new project's public ID (project_id) which can be used with all other tools.

Set the active project for this session. Once set, all subsequent tool calls will default to this project without needing to pass project_id each time. Note: if you only have access to one project, or have a recently used project, it will be auto-selected — you only need this tool to switch between multiple projects.

Publish the current draft configuration for a team. Compiles and deploys the tag to production. If no message is provided, set auto_generate_message to true to automatically generate a commit-style message from the changes made since the last publish.

Get dashboard core metrics (visitors, personalizations, conversions, survey responses) for a date range. Maximum 30 days — longer ranges are automatically truncated. Returns time-series data for charting.

Get the current audience distribution across dimensions, exact cross-dimension overlaps, and website-analytics-filtered audience cohorts.

Get per-campaign performance: lift percentage, statistical confidence, variant breakdown, and control vs personalized conversion rates. Exact custom date ranges are not supported here; requests are rounded up to the nearest preset bucket (7, 14, 30, or 90 days) and the response includes both the requested range and the bucket used.

Get per-offer performance metrics: visitor exposures, conversions, conversion rates, and period-over-period change.

Get flow execution metrics: starts, completions, drop-off rates, node-level stats, and visitor paths through a flow. Also includes exposurePages showing which URLs the flow ran on with per-page visitor counts — use this to see where a flow actually appears on the site.

Get detailed visitor engagement data for a flow: who answered, what they chose, outcomes, duration, device, and country. Only returns identified visitors (with email) who answered at least one question. Supports pagination via search_after cursor. For large flows, narrow the date_from/date_to range or use a smaller limit (default 25, max 100) to keep response sizes manageable.

Get web traffic analytics: visitor types (anonymous/subscriber), traffic sources, top referrers, landing pages, most viewed pages, UTM campaigns/sources/mediums, countries, languages, device types, operating systems, and browsers.

Get per-segment engagement metrics: pages viewed per visitor with +/- % lift vs rest-of-population baseline. Shows which audience segments are most or least engaged. Can also measure goal conversion rates or offer conversion rates per segment.

Get full AI-ready context for a project: segments, survey answers, traffic patterns, and voice-of-customer data. Useful for understanding a team's personalization setup.

Get dimension-to-ESP field mapping with Liquid template examples. Shows which dimensions sync to email platform custom fields and how to use them in email templates.

Get comprehensive email personalization context: ESP-specific Liquid syntax, available dimensions with custom field mappings and analytics, business context, and Liquid templating rules. Call this before generating personalized email templates with Liquid conditionals.

Use this tool (not get-flow) to understand a flow's logic. Returns the full node tree as human-readable YAML with branching logic, question text, offers, conditions, and per-node visitor metrics (exposures, conversions, conversion rates). Trunk vs branch semantics: each sg (question/router) node has a `trunk_next` field showing where control flows after the question if no answer-branch overrides it. Each answer's `next` either overrides (jumps to a specific UUID) or matches `trunk_next` (returns to the trunk, annotated `# returns to trunk`). `(flow-end)` is a distinct marker meaning the flow has no further nodes — only treat this token as termination. Branches that return to the trunk are NOT the flow ending.

Check whether the tracking snippet is installed and sending data. Returns the timestamp of the last received event.

Get the JavaScript tracking snippet code to install on a website. Returns the full <script> tag that should be pasted into the <head> of every page.

Generate a shareable preview URL for testing specific segment combinations on any RightMessage-enabled page. The URL includes `rmpreview=1` (loads your draft config) and a `__rm_test` parameter with base64-encoded visitor data. When opened: - Loads your unpublished draft config so you can test changes before publishing - Forces the specified segments for the visitor - Simulates ESP context (email, tags, custom fields) if provided - Automatically disables analytics tracking so test visits don't pollute data Accepts segment names (e.g., "SaaS") or IDs (e.g., "seg_abc123"). Names are resolved against the project's config.

Search for recent visitors with flexible filters. Combine any filters to answer questions like: - "Find visitors who saw the Trial Signup offer" (filter by offer_id) - "Who answered the Business Type question?" (filter by question_id) - "Show visitors who went through the Onboarding Quiz flow" (filter by flow_id) - "Find identified visitors in the SaaS segment" (filter by segment_id + visitor_type=identified) - "Who converted on the Homepage campaign?" (filter by campaign_id) You can pass resource NAMES instead of IDs — the tool will resolve them automatically using the project config. For example, offer_id can be "Trial Signup" instead of "ofr_abc123".

Get the publish history for a project — when configs were published, with optional publish messages. Useful for answering questions like "When was the last publish?" or "What changes were deployed recently?"

List all optimization best practices that RightMessage can detect and recommend. Returns the playbook of what the recommendation engine looks for — useful for understanding what optimizations are possible and advising users on next steps. No project_id needed.

Get the structured methodology for building a quiz, survey, assessment, or lead qualification flow. Returns a 5-phase workflow: gather context, interview the user, design strategy, build, and hand off. Call this BEFORE creating any dimensions or flow nodes when a user asks to build a quiz, survey, lead qualifier, or any flow that involves asking visitors questions. This is the right tool even if the survey also involves scoring, routing, or showing different outcomes — it covers all of that.

Get the structured methodology for building targeted CTA flows, smart popups, or personalized offers that route visitors based on EXISTING data (subscriber status, ESP tags, page URL, segments) WITHOUT asking new survey questions. Returns a 5-phase workflow: audit data, interview user, design routing strategy, build, and hand off. Call this BEFORE creating flow nodes when a user wants to show DIFFERENT offers to different visitor types based purely on data they already have. Do NOT use this for quizzes, surveys, assessments, or lead qualification — use get_survey_builder_guide instead, even if the survey also involves routing at the end.

Get the structured methodology for building a personalized quiz results page. Returns a 4-phase workflow: understand quiz segments → scaffold HTML page → wire up RightMessage campaign → publish. Call this BEFORE creating any resources when a user wants to create a results page for a quiz, assessment, or scored survey. The guide covers the full pipeline including spinner/redirect patterns, tier-matched CTAs, and per-segment content personalization.

List all available condition sources, types, operators, and required fields for building conditions. Conditions are used in three places: 1. YesNo flow nodes — branching logic based on visitor attributes 2. Segment signals — automatic segment detection rules on dimensions 3. Campaign variant rules — targeting specific audiences All conditions follow the LogicDefinition structure: { "or": [ { "and": [condition1, condition2] }, { "and": [condition3] } ] } Each condition item has: $source, $type, operator, and source-specific fields. This tool returns all available sources with their types, operators, and required fields — including dynamic sources based on the team's existing dimensions and ESP integration.

Validate a condition object (LogicDefinition) before using it in a YesNo flow node, segment signal, or campaign rule. Returns { valid: true } or { valid: false, errors: [...] } with details about what's wrong and how to fix it. Pass the full condition object as the "condition" parameter. It should follow the LogicDefinition structure: { "and": [...] } or { "or": [ { "and": [...] }, ... ] } Use list-condition-sources to discover all available sources, types, operators, and fields.

Start an async CSV export of survey "other" answers (free-text responses). Returns a job ID to poll with get-export-status.

Start an async CSV export of leads/subscribers. Returns a job ID to poll with get-export-status. Default range: last 30 days.

Check the status of an async export job. Returns progress info and download URL when complete.

Get the full activity timeline for a specific visitor. Returns sessions with pageviews, flow executions, campaign activity, and sync events. Use this to answer questions like: - "What has john@example.com been doing on my site?" - "Show me visitor abc123's session history" - "What flows did this visitor go through?" - "What pages did they visit before converting?" Pass an email address or visitor ID as the identifier. The tool auto-detects which one based on whether it contains "@". Results are paginated — use next_page_token from the response to fetch older sessions.

Get a comprehensive visitor dossier by email or visitor ID. Returns: - Identity: email, all visitor IDs, first/last seen timestamps - Segmentation: dimension names and segment names for all segments the visitor belongs to - Integration data: tags and custom fields from the connected ESP (if any) - Survey responses: free-text "other" answers from surveys - Activity summary: total sessions, pageviews, pages per session, top 5 most visited pages Examples: - "Look up john@example.com" (identifier = "john@example.com") - "Get profile for visitor v_abc123" (identifier = "v_abc123") The tool auto-detects whether the identifier is an email (contains @) or a visitor ID.

Extract personalizable elements from a webpage with Smart Match targeting data. Fetches rendered HTML via Firecrawl, parses the DOM, and returns each element with: 1. **Partial fingerprint** — text content, tag name, DOM structure (sibling position, parent chain), and semantic hints (IDs, data attributes, ARIA labels, meaningful classes). This fingerprint is compatible with RightMessage's client-side Smart Match resolver, which combines it with visual signals at runtime for robust element identification — even on pages with no unique CSS classes or IDs. 2. **Fallback CSS selector** — a best-effort selector. Only reliable when `selector_stable` is true (element has a unique ID). ## How to use this data when creating campaigns **IMPORTANT: Do NOT fetch the page HTML yourself or try to construct CSS selectors manually.** Use the targeting data from this tool instead. ### Default approach: fingerprint targeting + full text replacement For each element you want to personalize, create a separate campaign action (change) with: - `targeting`: pass the element's `targeting` object directly - `content`: the new replacement text for that element Each element gets its own action, even if two elements have the same text (e.g., a CTA that appears twice). The fingerprint differentiates them by DOM position. Check the `text_unique` field — when false, there are multiple elements with identical text, so each needs its own targeted action. ### When to use find/replace instead Use `/find/replace/` content format ONLY when you want to swap specific words or phrases within an element while keeping the rest intact. Example: changing "SaaS companies" to "agencies" inside a paragraph, without replacing the entire paragraph. This is a modification strategy for partial edits, not a targeting strategy. Use this tool before creating campaigns to understand what's on the page and how to target it.

List all available email/marketing platform integrations and their connection status. Returns each provider's name, auth type (keys or oauth), whether it's currently connected, and feature support (tags, custom fields, lists, events, etc.). OAuth providers that require browser-based setup will include a setup_url for the user.

Get detailed information about a specific email/marketing platform integration. Returns connection status, auth type, supported features, and configuration details. For connected integrations, includes timestamps and health status.

Connect an email/marketing platform integration using API key credentials. Only works for API key-based providers (e.g., ConvertKit, ActiveCampaign, Klaviyo, Bento, Encharge, Beehiiv, Braze, Mailerlite). For OAuth-based providers (e.g., Mailchimp, HubSpot, GoHighLevel, Pardot, Infusionsoft), the user must set up the connection in the RightMessage dashboard instead. Credentials are validated against the provider's API before saving. Use list-integrations first to check auth_type and see what credentials are needed. Use get-integration with the provider name to see setup_instructions for credential details.

Create a new custom field in the team's connected email/marketing platform. Use this when setting up dimension sync and the needed custom field doesn't exist in the ESP yet. Before calling this tool, check existing fields in the ESP and verify the provider supports programmatic field creation. Returns the created field's ID, label, and slug so you can pass the ID to update-segment-group's sync_field parameter. Only works with structured ESPs that support programmatic field creation (e.g., ActiveCampaign, Beehiiv, Bento, Encharge, Mailerlite, GoHighLevel, Intercom). Unstructured ESPs (like Customer.io, Klaviyo) don't need this — any field key works without pre-creation.

Test the health of an existing email/marketing platform integration. Verifies that the stored credentials are still valid and the provider's API is reachable. Returns a health status with a message indicating success or describing the failure.

Disconnect and delete an email/marketing platform integration. This removes the stored credentials and disconnects the provider. Existing visitor data and segment assignments are NOT affected.

Fetch data from a connected email/marketing platform integration. Retrieves custom fields, tags, lists, and/or native fields depending on what the provider supports. Use the `data_types` parameter to specify which data to fetch (defaults to all available). This is useful for understanding what fields/tags exist in the ESP before creating segment sync mappings.

Undo the last config change by restoring the previous version. Returns what was undone.

List the team-wide backup timeline across publish boundaries, including snapshot backups and publish events. Paginated.

Generate or return the stored plain-language summary for a specific snapshot version from list-config-versions.

Return the compact before/after change list for a specific snapshot version from list-config-versions.

After identifying the exact backup timestamp and summary and getting explicit user confirmation, restore the draft to a specific snapshot version ID from list-config-versions. The live site stays unchanged until publish-config is called.

After identifying the exact published timestamp and summary and getting explicit user confirmation, restore the draft to a specific prior published config from list-config-versions. The live site stays unchanged until publish-config is called.

List all split tests for the project. Optionally filter by resource_type and resource_id to see tests for a specific question or offer. Returns test pid, status, resource info, variants, and timestamps.

Get details of a specific split test by its pid, including the original resource content (question text/options or offer parts) alongside variant overrides, and current metrics (impressions, conversions, conversion rate per variant) if the test is active or completed.

Get live performance metrics for an active or completed split test. Returns per-variant exposures (unique visitors who saw the variant), conversions (unique visitors who answered/converted), and conversion rate. Use this to decide which variant is winning before ending a test.

Create an A/B split test for a question, offer, or flow. This creates a separate test record with variant overrides — it does NOT create new questions, offers, or flows. For QUESTION tests: provide variant text/answer/description/buttonText overrides. The engine randomly assigns visitors to control (original) or variant and shows the appropriate version. For OFFER tests: provide variant parts overrides (title, description, buttonText, imageUrl). For FLOW tests: provide a complete funnelDefinition for the variant. The engine assigns visitors to see either the original flow structure (control) or the variant's flow structure. MVP supports 1 variant only. The test starts in "draft" status. Use start-split-test to activate it. IMPORTANT: Do NOT include a "control" variant — control is implicit (it shows the original content). Only pass the test variants that override specific fields. If a control variant is passed, it will be stripped automatically. Traffic is split equally among control + all variants. For 1 variant: 50/50. For 2 variants: 33/33/33. Example: single variant question test: [ {"id": "variant_b", "name": "Variant B", "weight": 50, "text": "New headline?", "description": "New subtext", "answers": {"seg_abc": {"label": "New label"}}} ] Example: multi-variant question test: [ {"id": "variant_b", "name": "Direct approach", "weight": 50, "text": "What do you sell?"}, {"id": "variant_c", "name": "Benefit-led approach", "weight": 50, "text": "What would help you grow fastest?"} ] Example: offer test: [ {"id": "variant_b", "name": "Urgency variant", "weight": 50, "parts": {"title": "Limited time offer", "buttonText": "Claim now"}} ]

Update a split test's variants or configuration. Only works on tests in "draft" status — active tests cannot be modified.

Delete a split test. Can only delete tests in "draft" or "completed" status. Active tests must be ended first.

Activate a draft split test. Sets the status to "active" and begins randomly assigning visitors to variants. The test must be in "draft" status.

End an active split test and declare a winner. If the winner is a non-control variant, its content is automatically promoted to the original resource (the question text/answers or offer parts are updated in the draft config). Pass winner_id="control" to keep the original content unchanged. Use get-split-test with include_metrics=true first to review performance data before deciding a winner.