Nevent MCP

Official59 toolsLive

by nevent-dev · TypeScript

Talk to your live-events CRM (campaigns, analytics, paid ads, segments) in Claude and ChatGPT.

Nevent MCP Server (io.github.nevent-dev/mcp-nevent)

This Model Context Protocol (MCP) server provides tools to connect Claude and ChatGPT to a live-events CRM. It supports CRM interactions for campaigns, analytics, paid ads, segments, and short URLs. The package is published as mcp-nevent and described as an official MCP server for Nevent.

🛠️ Key Features

Live-events CRM access for campaigns
Analytics integration
Paid ads support
Segment handling
Short URL capabilities
MCP toolset (59 tools)

🚀 Use Cases

Query or work with live-event campaign data in Claude/ChatGPT
Review analytics outputs for events
Coordinate information related to paid ads
Manage or reference CRM segments
Generate or use short URLs

⚡ Developer Benefits

Typed integration surface via MCP tools (toolCount: 59)
Works with Anthropic Claude and ChatGPT as stated
Developer-focused package for TypeScript ecosystems

⚠️ Limitations

Scope is limited to Nevent live-events CRM areas listed (campaigns, analytics, paid ads, segments, short URLs).

Topics

anthropicchatgptclaudecrmeventsmarketingmcpmodel-context-protocoltypescriptnevent

Captured live from the server via tools/list.

nevent_analytics_query

Query event marketing analytics. Supports dimensions, metrics, time ranges, and filters across campaigns, purchases, users, and more. MANDATORY RULES: (1) ALWAYS call nevent_analytics_table_schema BEFORE querying to discover exact field names. NEVER guess field names. (2) For BOOLEAN fields, use operator "is_true" or "is_false". NEVER use "eq" with string "true"/"false". (3) For enum fields (state, status), check the field description for valid values. Common values: purchases.state = SUCCEEDED|COMPLETE|PENDING|FAILED; campaigns.status = EXECUTED|DRAFT|PAUSED|STOPPED.

Parameters16

collection	string	required	Collection name, e.g. "purchases", "tickets", "campaigns"
dimensions	array	optional	Fields to group by (SELECT dimensions). Omit for aggregate-only queries.
metrics	array	optional	Aggregated metrics to compute (SUM, COUNT, etc.)
timeRange	object	optional	Time range filter with optional granularity for trend analysis
filters	array	optional	WHERE clause filters to apply before aggregation
having	array	optional	HAVING clause filters to apply after aggregation
sort	any	optional	Sort the result rows. Accepts a single { field, order } object or an array for multi-field sorting.
limit	number	optional	Maximum rows to return (max 1000, default 100)
compareDimensions	object	optional	Comparative dimension analysis configuration
distinct	boolean	optional	Add SELECT DISTINCT to deduplicate result rows (v3.19.0+)
dryRun	boolean	optional	Dry-run mode: estimate query cost without executing (v3.19.0+). Response includes estimatedBytes in metadata.
timeGranularity	string	optional	Time granularity for bucketing (v3.19.0+). Known values: day \| week \| month \| quarter \| year \| hour \| minute \| fiscalQuarter \| fiscalYear
groupBy	array	optional	Calendar-based group-by fields (v3.19.0+). Known values: dayOfWeek \| weekOfYear \| hourOfDay \| minuteOfHour \| month \| quarter \| year
comparePeriods	object	optional	Period-over-period comparison (YoY, MoM, etc.) — v3.19.0+
ctes	array	optional	CTE (Common Table Expression) sub-queries — v3.19.0+
sourceTable	string	optional	CTE name to use as source instead of a raw collection — v3.19.0+

Raw schema

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "Collection name, e.g. \"purchases\", \"tickets\", \"campaigns\""
    },
    "dimensions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field name"
          },
          "alias": {
            "type": "string",
            "description": "Alias for the column in results"
          }
        },
        "required": [
          "field"
        ],
        "additionalProperties": false
      },
      "description": "Fields to group by (SELECT dimensions). Omit for aggregate-only queries."
    },
    "metrics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field name to aggregate"
          },
          "operation": {
            "type": "string",
            "description": "Aggregation function. Known values: sum | count | avg | min | max | count_distinct | median | percentile | stddev | variance | date_diff"
          },
          "alias": {
            "type": "string",
            "description": "Alias for the aggregated column in results"
          }
        },
        "required": [
          "field",
          "operation"
        ],
        "additionalProperties": false
      },
      "description": "Aggregated metrics to compute (SUM, COUNT, etc.)"
    },
    "timeRange": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "Start date in ISO 8601 format, e.g. \"2024-01-01\""
        },
        "end": {
          "type": "string",
          "description": "End date in ISO 8601 format, e.g. \"2024-12-31\""
        },
        "granularity": {
          "type": "string",
          "description": "Time bucket granularity (deprecated: use top-level timeGranularity)"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Time range filter with optional granularity for trend analysis"
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field name to filter on"
          },
          "operator": {
            "type": "string",
            "description": "Comparison operator. Known values: eq | neq | gt | gte | lt | lte | in | not_in | like | contains | not_contains | starts_with | ends_with | regex | between | is_null | is_not_null | is_true | is_false | array_contains | array_contains_any"
          },
          "value": {
            "description": "Filter value; use array for \"in\" / \"not_in\" / \"between\" operators"
          }
        },
        "required": [
          "field",
          "operator"
        ],
        "additionalProperties": false
      },
      "description": "WHERE clause filters to apply before aggregation"
    },
    "having": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Aggregated field name"
          },
          "operator": {
            "type": "string",
            "description": "Comparison operator (e.g. \"gt\", \"gte\")"
          },
          "value": {
            "description": "HAVING threshold value"
          }
        },
        "required": [
          "field",
          "operator"
        ],
        "additionalProperties": false
      },
      "description": "HAVING clause filters to apply after aggregation"
    },
    "sort": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "field": {
              "type": "string",
              "description": "Field to sort by"
            },
            "order": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "description": "Sort direction: asc | desc"
            }
          },
          "required": [
            "field",
            "order"
          ],
          "additionalProperties": false
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/properties/sort/anyOf/0"
          },
          "minItems": 1
        }
      ],
      "description": "Sort the result rows. Accepts a single { field, order } object or an array for multi-field sorting."
    },
    "limit": {
      "type": "number",
      "maximum": 1000,
      "default": 100,
      "description": "Maximum rows to return (max 1000, default 100)"
    },
    "compareDimensions": {
      "type": "object",
      "properties": {
        "active": {
          "type": "boolean",
          "description": "Enable comparative analysis"
        },
        "dimensions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string",
                "description": "Dimension field name"
              },
              "value": {
                "type": "string",
                "description": "Dimension field value to compare"
              },
              "name": {
                "type": "string",
                "description": "Display name for the comparison group"
              }
            },
            "required": [
              "field",
              "value",
              "name"
            ],
            "additionalProperties": false
          },
          "description": "Dimension values to compare against each other"
        }
      },
      "required": [
        "active",
        "dimensions"
      ],
      "additionalProperties": false,
      "description": "Comparative dimension analysis configuration"
    },
    "distinct": {
      "type": "boolean",
      "description": "Add SELECT DISTINCT to deduplicate result rows (v3.19.0+)"
    },
    "dryRun": {
      "type": "boolean",
      "description": "Dry-run mode: estimate query cost without executing (v3.19.0+). Response includes estimatedBytes in metadata."
    },
    "timeGranularity": {
      "type": "string",
      "description": "Time granularity for bucketing (v3.19.0+). Known values: day | week | month | quarter | year | hour | minute | fiscalQuarter | fiscalYear"
    },
    "groupBy": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Calendar-based group-by fields (v3.19.0+). Known values: dayOfWeek | weekOfYear | hourOfDay | minuteOfHour | month | quarter | year"
    },
    "comparePeriods": {
      "type": "object",
      "properties": {
        "active": {
          "type": "boolean",
          "description": "Enable period-over-period comparison"
        },
        "current": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string",
              "description": "ISO 8601 start date, e.g. \"2024-01-01\""
            },
            "end": {
              "type": "string",
              "description": "ISO 8601 end date, e.g. \"2024-12-31\""
            }
          },
          "required": [
            "start",
            "end"
          ],
          "additionalProperties": false,
          "description": "The reference (current) time period"
        },
        "previous": {
          "type": "object",
          "properties": {
            "start": {
              "$ref": "#/properties/comparePeriods/properties/current/properties/start"
            },
            "end": {
              "$ref": "#/properties/comparePeriods/properties/current/properties/end"
            }
          },
          "required": [
            "start",
            "end"
          ],
          "additionalProperties": false,
          "description": "The baseline (previous) time period to compare against"
        }
      },
      "required": [
        "active",
        "current",
        "previous"
      ],
      "additionalProperties": false,
      "description": "Period-over-period comparison (YoY, MoM, etc.) — v3.19.0+"
    },
    "ctes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name used to reference this CTE via the sourceTable field"
          },
          "collection": {
            "type": "string",
            "description": "Source collection for this CTE"
          },
          "dimensions": {
            "type": "array",
            "items": {
              "$ref": "#/properties/dimensions/items"
            },
            "description": "Dimensions to select in the CTE"
          },
          "metrics": {
            "type": "array",
            "items": {
              "$ref": "#/properties/metrics/items"
            },
            "description": "Metrics to compute in the CTE"
          },
          "filters": {
            "type": "array",
            "items": {
              "$ref": "#/properties/filters/items"
            },
            "description": "Filters to apply in the CTE"
          },
          "timeRange": {
            "$ref": "#/properties/timeRange",
            "description": "Time range filter for the CTE"
          },
          "sort": {
            "$ref": "#/properties/sort",
            "description": "Sort order for the CTE"
          },
          "limit": {
            "type": "number",
            "maximum": 10000,
            "description": "Row limit for the CTE"
          }
        },
        "required": [
          "name",
          "collection"
        ],
        "additionalProperties": false
      },
      "description": "CTE (Common Table Expression) sub-queries — v3.19.0+"
    },
    "sourceTable": {
      "type": "string",
      "description": "CTE name to use as source instead of a raw collection — v3.19.0+"
    }
  },
  "required": [
    "collection"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_analytics_capabilities

Discover available analytics tables and their summary metadata. Call this before nevent_analytics_query, then use nevent_analytics_table_schema to learn valid field names for a selected table.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_analytics_table_schema

Get the full column schema for a specific analytics table including column names, types, and descriptions.

Parameters1

table

string

required

Table name to inspect, e.g. "purchases", "tickets"

Raw schema

{
  "type": "object",
  "properties": {
    "table": {
      "type": "string",
      "description": "Table name to inspect, e.g. \"purchases\", \"tickets\""
    }
  },
  "required": [
    "table"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_analytics_filter_values

Get distinct values available for a field in an analytics table. Useful for building valid filter values before querying.

Parameters2

collection	string	required	Collection name to get filter values for
filters	array	required	Fields to get distinct values for

Raw schema

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "Collection name to get filter values for"
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field name to get distinct values for"
          },
          "operator": {
            "type": "string",
            "description": "Optional operator to apply when retrieving values"
          },
          "value": {
            "description": "Optional seed value"
          }
        },
        "required": [
          "field"
        ],
        "additionalProperties": false
      },
      "description": "Fields to get distinct values for"
    }
  },
  "required": [
    "collection",
    "filters"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_campaign_report

Generate a comprehensive analytics report for a single campaign. Executes 13 parallel queries in one call returning opens, clicks, bounces, unsubscribes, conversions, revenue, and other key performance metrics. Use nevent_list_campaigns to get valid campaign IDs.

Parameters2

campaignId	string	required	Campaign ID to generate the analytics report for
timeRange	object	optional	Optional time range to restrict report data. Defaults to full campaign lifetime.

Raw schema

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "description": "Campaign ID to generate the analytics report for"
    },
    "timeRange": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "Start date in ISO 8601 format, e.g. \"2024-01-01\""
        },
        "end": {
          "type": "string",
          "description": "End date in ISO 8601 format, e.g. \"2024-12-31\""
        },
        "granularity": {
          "type": "string",
          "description": "Time bucket granularity (deprecated: use top-level timeGranularity)"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Optional time range to restrict report data. Defaults to full campaign lifetime."
    }
  },
  "required": [
    "campaignId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_segmentation_criteria

List all available audience segmentation criteria including their IDs, operators, and value types.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_segment_preview

Preview estimated audience size for a segment definition without saving it. Returns fan count and sample contacts. MANDATORY RULES: (1) ENTITY operators (is/is_not) accept a single string OR an array of strings (e.g. value: "EVENT_ID" or value: ["EVENT_1","EVENT_2"]). (2) Do NOT include modifiers unless specifically asked for frequency or recency filtering. If included, time_range.value MUST be > 0. KNOWN LIMITATION: Do NOT combine attendance criteria (attended_event, ticket_type) with spending criteria (total_spent, ticket_spent, cashless_recharge_amount) in the SAME stanza. Put them in SEPARATE stanzas. Example: { stanzas: [{ criteria: [{ criterion_id: "attended_event", operator: "is", value: "EVENT_ID" }] }, { criteria: [{ criterion_id: "total_spent", operator: "gte", value: 200 }] }] }.

Parameters1

definition

object

required

Segment DSL: stanzas are OR-combined, criteria within each stanza are AND-combined

Raw schema

{
  "type": "object",
  "properties": {
    "definition": {
      "type": "object",
      "properties": {
        "stanzas": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Optional stable ID for the stanza. If omitted, the MCP client auto-generates one before sending to the API. Provide your own only if you need stable references across requests."
              },
              "criteria": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Optional stable ID for UI/cross-request correlation. If omitted, the MCP client auto-generates one before sending to the API."
                    },
                    "criterion_id": {
                      "type": "string",
                      "description": "Criterion identifier from nevent_segmentation_criteria. Examples: total_spent, attended_event, user_gender, user_age, campaign_opened, nevent_temperature"
                    },
                    "operator": {
                      "type": "string",
                      "description": "Comparison operator. Rules by data type:\n- ENTITY: \"is\" and \"is_not\" accept a single string ID OR an array of string IDs (valueType=array per API). \"is_set\", \"is_not_set\" also supported.\n- TEXT: \"eq\", \"neq\", \"contains\", \"starts_with\", \"ends_with\", \"is_set\", \"is_not_set\"\n- NUMBER/CURRENCY: \"eq\", \"neq\", \"gt\", \"gte\", \"lt\", \"lte\", \"is_set\", \"is_not_set\"\n- BOOLEAN: \"is_true\", \"is_false\". NEVER use \"eq\" with \"true\"/\"false\" strings.\n- DATE: \"before\", \"after\", \"between\", \"eq\", \"is_set\", \"is_not_set\""
                    },
                    "value": {
                      "description": "Value to match. IMPORTANT rules:\n- ENTITY operators (is/is_not): accepts a single string ID OR an array of string IDs (e.g. \"event_123\" or [\"event_1\", \"event_2\"]).\n- NUMBER: must be a number (not string)\n- BOOLEAN operators (is_true/is_false): no value needed, omit this field.\n- DATE \"between\": array of 2 ISO date strings [start, end]"
                    },
                    "filters": {
                      "type": "object",
                      "additionalProperties": {},
                      "description": "Only needed for user_custom_field criterion. Pass { \"property_name\": \"field_name\" } to specify which custom field."
                    },
                    "modifiers": {
                      "type": "object",
                      "properties": {
                        "frequency": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "number"
                            },
                            "operator": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "count",
                            "operator"
                          ],
                          "additionalProperties": false
                        },
                        "time_range": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "number",
                              "minimum": 1
                            },
                            "unit": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "value",
                            "unit"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "additionalProperties": false,
                      "description": "ADVANCED: Usually OMIT this field entirely. Only include when the user explicitly asks for:\n- \"at least X times\" → { frequency: { count: X, operator: \"gte\" } }\n- \"in the last X days\" → { time_range: { value: X, unit: \"day\" } } (value MUST be > 0)\nIf not asked for frequency or recency, DO NOT include modifiers."
                    }
                  },
                  "required": [
                    "criterion_id",
                    "operator"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Criteria combined with AND logic within this stanza."
              }
            },
            "required": [
              "criteria"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "description": "Array of stanzas (OR logic). Each stanza contains criteria (AND logic)."
        }
      },
      "required": [
        "stanzas"
      ],
      "additionalProperties": false,
      "description": "Segment DSL: stanzas are OR-combined, criteria within each stanza are AND-combined"
    }
  },
  "required": [
    "definition"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_segment_execute

Execute a segment definition and retrieve matching contacts with pagination.

Parameters3

definition	object	required	Segment DSL: stanzas are OR-combined, criteria within each stanza are AND-combined
page	number	optional	Zero-based page index (default 0)
page_size	number	optional	Results per page (max 100, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "definition": {
      "type": "object",
      "properties": {
        "stanzas": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Optional stable ID for the stanza. If omitted, the MCP client auto-generates one before sending to the API. Provide your own only if you need stable references across requests."
              },
              "criteria": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Optional stable ID for UI/cross-request correlation. If omitted, the MCP client auto-generates one before sending to the API."
                    },
                    "criterion_id": {
                      "type": "string",
                      "description": "Criterion identifier from nevent_segmentation_criteria. Examples: total_spent, attended_event, user_gender, user_age, campaign_opened, nevent_temperature"
                    },
                    "operator": {
                      "type": "string",
                      "description": "Comparison operator. Rules by data type:\n- ENTITY: \"is\" and \"is_not\" accept a single string ID OR an array of string IDs (valueType=array per API). \"is_set\", \"is_not_set\" also supported.\n- TEXT: \"eq\", \"neq\", \"contains\", \"starts_with\", \"ends_with\", \"is_set\", \"is_not_set\"\n- NUMBER/CURRENCY: \"eq\", \"neq\", \"gt\", \"gte\", \"lt\", \"lte\", \"is_set\", \"is_not_set\"\n- BOOLEAN: \"is_true\", \"is_false\". NEVER use \"eq\" with \"true\"/\"false\" strings.\n- DATE: \"before\", \"after\", \"between\", \"eq\", \"is_set\", \"is_not_set\""
                    },
                    "value": {
                      "description": "Value to match. IMPORTANT rules:\n- ENTITY operators (is/is_not): accepts a single string ID OR an array of string IDs (e.g. \"event_123\" or [\"event_1\", \"event_2\"]).\n- NUMBER: must be a number (not string)\n- BOOLEAN operators (is_true/is_false): no value needed, omit this field.\n- DATE \"between\": array of 2 ISO date strings [start, end]"
                    },
                    "filters": {
                      "type": "object",
                      "additionalProperties": {},
                      "description": "Only needed for user_custom_field criterion. Pass { \"property_name\": \"field_name\" } to specify which custom field."
                    },
                    "modifiers": {
                      "type": "object",
                      "properties": {
                        "frequency": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "number"
                            },
                            "operator": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "count",
                            "operator"
                          ],
                          "additionalProperties": false
                        },
                        "time_range": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "number",
                              "minimum": 1
                            },
                            "unit": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "value",
                            "unit"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "additionalProperties": false,
                      "description": "ADVANCED: Usually OMIT this field entirely. Only include when the user explicitly asks for:\n- \"at least X times\" → { frequency: { count: X, operator: \"gte\" } }\n- \"in the last X days\" → { time_range: { value: X, unit: \"day\" } } (value MUST be > 0)\nIf not asked for frequency or recency, DO NOT include modifiers."
                    }
                  },
                  "required": [
                    "criterion_id",
                    "operator"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Criteria combined with AND logic within this stanza."
              }
            },
            "required": [
              "criteria"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "description": "Array of stanzas (OR logic). Each stanza contains criteria (AND logic)."
        }
      },
      "required": [
        "stanzas"
      ],
      "additionalProperties": false,
      "description": "Segment DSL: stanzas are OR-combined, criteria within each stanza are AND-combined"
    },
    "page": {
      "type": "number",
      "minimum": 0,
      "default": 0,
      "description": "Zero-based page index (default 0)"
    },
    "page_size": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Results per page (max 100, default 20)"
    }
  },
  "required": [
    "definition"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_dimension_values

Autocomplete values for a segmentation criterion. Useful for discovering valid values when building segment definitions.

Parameters2

criterion_id	string	required	Criterion ID from nevent_segmentation_criteria, e.g. "country", "event_attended"
search	string	optional	Optional search string to filter matching values

Raw schema

{
  "type": "object",
  "properties": {
    "criterion_id": {
      "type": "string",
      "description": "Criterion ID from nevent_segmentation_criteria, e.g. \"country\", \"event_attended\""
    },
    "search": {
      "type": "string",
      "description": "Optional search string to filter matching values"
    }
  },
  "required": [
    "criterion_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_help

Get guidance when you are unsure which tool to call or how to handle an error. Returns structured markdown for the requested topic. Call with topic="workflows" for common patterns, topic="errors" for error code meanings, topic="tenants" for multi-tenant guidance, or topic=<category> like "paid_media" / "analytics" / "segments". Omit topic to get an index of all available topics.

Parameters1

topic

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "workflows",
        "errors",
        "tenants",
        "analytics",
        "segments",
        "campaigns",
        "templates",
        "deliverability",
        "paid_media",
        "short_urls",
        "media"
      ],
      "description": "Topic to get guidance on. Omit to get an index of all available topics. Values: workflows | errors | tenants | analytics | segments | campaigns | templates | deliverability | paid_media | short_urls | media"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_tenants

List all Nevent tenants (clients) accessible to the authenticated user. Returns tenant IDs and names for use with nevent_switch_tenant. SUPERADMIN: returns all tenants in the platform. OWNER/ADMIN: returns only your tenant hierarchy subtree (up to 3 levels).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_switch_tenant

Switch the active tenant for this session. All subsequent queries (analytics, segments, campaigns, paid media) will use the specified tenant's data. SUPERADMIN: this mutates your user record in the database — the switch PERSISTS. Always call nevent_reset_tenant when cross-tenant work is done to avoid leaving your account pointing at another tenant. OWNER/ADMIN/STAFF: session-scoped only; you can only switch to tenants in your hierarchy subtree (max 3 levels deep). Use nevent_list_tenants to discover available tenant IDs.

Parameters1

tenant_id

string

required

The tenant ID to activate for this MCP session. All subsequent analytics, segmentation, campaign, and paid media queries will use this tenant's data. Use nevent_list_tenants to discover available tenant IDs. SUPERADMIN: this mutates your user record in the database; call nevent_reset_tenant when done. OWNER/ADMIN/STAFF: session-scoped only (can only switch to descendants in your tenant hierarchy).

Raw schema

{
  "type": "object",
  "properties": {
    "tenant_id": {
      "type": "string",
      "description": "The tenant ID to activate for this MCP session. All subsequent analytics, segmentation, campaign, and paid media queries will use this tenant's data. Use nevent_list_tenants to discover available tenant IDs. SUPERADMIN: this mutates your user record in the database; call nevent_reset_tenant when done. OWNER/ADMIN/STAFF: session-scoped only (can only switch to descendants in your tenant hierarchy)."
    }
  },
  "required": [
    "tenant_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_reset_tenant

Restore the original tenant context set at session start. ALWAYS call this after cross-tenant queries (nevent_switch_tenant) to avoid leaving your SUPERADMIN account pointing to another tenant. For SUPERADMIN users, tenant switches PERSIST in the user record in the database — this tool reverses that. For OWNER/ADMIN/STAFF users, this resets to the session's home tenant. No parameters needed.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_segments

Call this FIRST when you need to build or target an audience. Returns all saved segments for the active tenant: id, name, estimated contact count, and last-execution date. Use the returned segment ids to call nevent_get_segment (for the filter definition), nevent_segment_preview (to verify the audience), or nevent_create_campaign (to send a campaign to that segment).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_segment

Retrieve the complete filter definition of a specific segment (criteria stanzas, operators, values) along with its estimated contact count and metadata. Call this after nevent_list_segments when you need to inspect, clone, or explain a segment's logic. Next step: nevent_segment_preview to count the audience, or nevent_update_segment to modify the definition.

Parameters1

segment_id

string

required

Identifier of the segment to retrieve. Get valid IDs from nevent_list_segments.

Raw schema

{
  "type": "object",
  "properties": {
    "segment_id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[a-f0-9]{24}$",
      "description": "Identifier of the segment to retrieve. Get valid IDs from nevent_list_segments."
    }
  },
  "required": [
    "segment_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_create_segment

Create and persist a new audience segment from a filter definition. PREREQUISITE: call nevent_segmentation_criteria first to discover valid criterion_ids and operators. MANDATORY RULES: (1) ENTITY operators (is/is_not) accept a single string OR an array of strings — e.g. value: "EVENT_ID" or value: ["E1","E2"]. (2) Omit modifiers unless the user explicitly requests frequency/recency filtering; if included, time_range.value MUST be > 0. (3) Criteria fields: only criterion_id, operator, value — omit id, timeframe, type. (4) KNOWN LIMITATION: do NOT mix attendance criteria (attended_event, ticket_type) with spending criteria (total_spent, ticket_spent, cashless_recharge_amount) in the same stanza — put them in separate stanzas. After creation, call nevent_segment_preview to count the audience, then nevent_create_campaign to send to this segment.

Parameters3

name	string	required	Human-readable name for the segment, e.g. "VIP Attendees 2025"
definition	object	required	Segment DSL: stanzas are OR-combined, criteria within each stanza are AND-combined. Must have at least one stanza with at least one criterion. Use nevent_segment_preview first to validate the definition.
description	string	optional	Optional description of the segment's purpose

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable name for the segment, e.g. \"VIP Attendees 2025\""
    },
    "definition": {
      "type": "object",
      "properties": {
        "stanzas": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Optional stable ID for the stanza. If omitted, the MCP client auto-generates one before sending to the API. Provide your own only if you need stable references across requests."
              },
              "criteria": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Optional stable ID for UI/cross-request correlation. If omitted, the MCP client auto-generates one before sending to the API."
                    },
                    "criterion_id": {
                      "type": "string",
                      "description": "Criterion identifier from nevent_segmentation_criteria. Examples: total_spent, attended_event, user_gender, user_age, campaign_opened, nevent_temperature"
                    },
                    "operator": {
                      "type": "string",
                      "description": "Comparison operator. Rules by data type:\n- ENTITY: \"is\" and \"is_not\" accept a single string ID OR an array of string IDs (valueType=array per API). \"is_set\", \"is_not_set\" also supported.\n- TEXT: \"eq\", \"neq\", \"contains\", \"starts_with\", \"ends_with\", \"is_set\", \"is_not_set\"\n- NUMBER/CURRENCY: \"eq\", \"neq\", \"gt\", \"gte\", \"lt\", \"lte\", \"is_set\", \"is_not_set\"\n- BOOLEAN: \"is_true\", \"is_false\". NEVER use \"eq\" with \"true\"/\"false\" strings.\n- DATE: \"before\", \"after\", \"between\", \"eq\", \"is_set\", \"is_not_set\""
                    },
                    "value": {
                      "description": "Value to match. IMPORTANT rules:\n- ENTITY operators (is/is_not): accepts a single string ID OR an array of string IDs (e.g. \"event_123\" or [\"event_1\", \"event_2\"]).\n- NUMBER: must be a number (not string)\n- BOOLEAN operators (is_true/is_false): no value needed, omit this field.\n- DATE \"between\": array of 2 ISO date strings [start, end]"
                    },
                    "filters": {
                      "type": "object",
                      "additionalProperties": {},
                      "description": "Only needed for user_custom_field criterion. Pass { \"property_name\": \"field_name\" } to specify which custom field."
                    },
                    "modifiers": {
                      "type": "object",
                      "properties": {
                        "frequency": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "number"
                            },
                            "operator": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "count",
                            "operator"
                          ],
                          "additionalProperties": false
                        },
                        "time_range": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "number",
                              "minimum": 1
                            },
                            "unit": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "value",
                            "unit"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "additionalProperties": false,
                      "description": "ADVANCED: Usually OMIT this field entirely. Only include when the user explicitly asks for:\n- \"at least X times\" → { frequency: { count: X, operator: \"gte\" } }\n- \"in the last X days\" → { time_range: { value: X, unit: \"day\" } } (value MUST be > 0)\nIf not asked for frequency or recency, DO NOT include modifiers."
                    }
                  },
                  "required": [
                    "criterion_id",
                    "operator"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Criteria combined with AND logic within this stanza."
              }
            },
            "required": [
              "criteria"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "description": "Array of stanzas (OR logic). Each stanza contains criteria (AND logic)."
        }
      },
      "required": [
        "stanzas"
      ],
      "additionalProperties": false,
      "description": "Segment DSL: stanzas are OR-combined, criteria within each stanza are AND-combined. Must have at least one stanza with at least one criterion. Use nevent_segment_preview first to validate the definition."
    },
    "description": {
      "type": "string",
      "description": "Optional description of the segment's purpose"
    }
  },
  "required": [
    "name",
    "definition"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_update_segment

Modify an existing segment's name and/or filter definition. Call this after nevent_get_segment to inspect the current definition before changing it. At least one of name or definition must be provided. After update, call nevent_segment_preview to confirm the new audience count before scheduling a campaign.

Parameters3

segment_id	string	required	Identifier of the segment to update. Use nevent_list_segments to get valid segment IDs.
name	string	optional	New human-readable name for the segment. Omit to leave unchanged.
definition	object	optional	Replacement segment DSL. The full definition is replaced when provided. Omit to leave the existing definition unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "segment_id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[a-f0-9]{24}$",
      "description": "Identifier of the segment to update. Use nevent_list_segments to get valid segment IDs."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "New human-readable name for the segment. Omit to leave unchanged."
    },
    "definition": {
      "type": "object",
      "properties": {
        "stanzas": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Optional stable ID for the stanza. If omitted, the MCP client auto-generates one before sending to the API. Provide your own only if you need stable references across requests."
              },
              "criteria": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Optional stable ID for UI/cross-request correlation. If omitted, the MCP client auto-generates one before sending to the API."
                    },
                    "criterion_id": {
                      "type": "string",
                      "description": "Criterion identifier from nevent_segmentation_criteria. Examples: total_spent, attended_event, user_gender, user_age, campaign_opened, nevent_temperature"
                    },
                    "operator": {
                      "type": "string",
                      "description": "Comparison operator. Rules by data type:\n- ENTITY: \"is\" and \"is_not\" accept a single string ID OR an array of string IDs (valueType=array per API). \"is_set\", \"is_not_set\" also supported.\n- TEXT: \"eq\", \"neq\", \"contains\", \"starts_with\", \"ends_with\", \"is_set\", \"is_not_set\"\n- NUMBER/CURRENCY: \"eq\", \"neq\", \"gt\", \"gte\", \"lt\", \"lte\", \"is_set\", \"is_not_set\"\n- BOOLEAN: \"is_true\", \"is_false\". NEVER use \"eq\" with \"true\"/\"false\" strings.\n- DATE: \"before\", \"after\", \"between\", \"eq\", \"is_set\", \"is_not_set\""
                    },
                    "value": {
                      "description": "Value to match. IMPORTANT rules:\n- ENTITY operators (is/is_not): accepts a single string ID OR an array of string IDs (e.g. \"event_123\" or [\"event_1\", \"event_2\"]).\n- NUMBER: must be a number (not string)\n- BOOLEAN operators (is_true/is_false): no value needed, omit this field.\n- DATE \"between\": array of 2 ISO date strings [start, end]"
                    },
                    "filters": {
                      "type": "object",
                      "additionalProperties": {},
                      "description": "Only needed for user_custom_field criterion. Pass { \"property_name\": \"field_name\" } to specify which custom field."
                    },
                    "modifiers": {
                      "type": "object",
                      "properties": {
                        "frequency": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "number"
                            },
                            "operator": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "count",
                            "operator"
                          ],
                          "additionalProperties": false
                        },
                        "time_range": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "number",
                              "minimum": 1
                            },
                            "unit": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "value",
                            "unit"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "additionalProperties": false,
                      "description": "ADVANCED: Usually OMIT this field entirely. Only include when the user explicitly asks for:\n- \"at least X times\" → { frequency: { count: X, operator: \"gte\" } }\n- \"in the last X days\" → { time_range: { value: X, unit: \"day\" } } (value MUST be > 0)\nIf not asked for frequency or recency, DO NOT include modifiers."
                    }
                  },
                  "required": [
                    "criterion_id",
                    "operator"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Criteria combined with AND logic within this stanza."
              }
            },
            "required": [
              "criteria"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "description": "Array of stanzas (OR logic). Each stanza contains criteria (AND logic)."
        }
      },
      "required": [
        "stanzas"
      ],
      "additionalProperties": false,
      "description": "Replacement segment DSL. The full definition is replaced when provided. Omit to leave the existing definition unchanged."
    }
  },
  "required": [
    "segment_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_create_campaign

Create a new campaign draft (email, SMS, WhatsApp, push, or multi-channel). PREREQUISITES: call nevent_list_segments to get the target segment_id, and nevent_list_templates to get the template_id. The campaign is always created in DRAFT status — no messages are sent. After creation, call nevent_schedule_campaign to schedule delivery. For EMAIL_ONLY (and email multi-channel): email_subject is required. For SMS_ONLY/WHATSAPP_ONLY/PUSH_ONLY and multi-channel involving those: message is required. Optional fields: from_name, preview_text, template_id, segment_ids, utm_source/medium/campaign/content/term/custom_params, reply_to (email address for reply routing — useful when replies should go to a different mailbox than the From address). Always confirm the segment audience count with the user before scheduling.

Parameters16

name	string	required	Campaign name (required, max 255 characters)
channel	string	required	Delivery channel (nev-api CommunicationChannel enum). Use EMAIL_ONLY, SMS_ONLY, WHATSAPP_ONLY, PUSH_ONLY for single-channel; EMAIL_AND_SMS, EMAIL_AND_WHATSAPP, PUSH_AND_SMS, PUSH_AND_WHATSAPP, SMS_AND_WHATSAPP for multi-channel; ALL_CHANNELS or OMNICHANNEL for broad delivery. Legacy values EMAIL/SMS/WHATSAPP are accepted but deprecated.
email_subject	string	optional	Email subject line (required when channel=EMAIL, max 998 chars per RFC 5322)
email_body	string	optional	HTML body content of the email (optional, can be set later)
preview_text	string	optional	Inbox preview text (optional, shown in email client summaries)
from_name	string	optional	Sender display name (optional, defaults to tenant sender name)
message	string	optional	Message text body (required when channel=SMS or WHATSAPP)
segment_ids	array	optional	Array of segment IDs to target (optional, can be set later)
template_id	string	optional	Template ID to pre-populate campaign content (optional)
utm_source	string	optional	UTM source parameter (e.g. "nevent", "newsletter"). Max 100 chars.
utm_medium	string	optional	UTM medium parameter (e.g. "email", "sms"). Max 100 chars. Auto-detected from channel if omitted.
utm_campaign	string	optional	UTM campaign parameter (e.g. "summer-sale-2026"). Max 100 chars. Defaults to slugified campaign name.
utm_content	string	optional	UTM content parameter — differentiates links/variants. Max 100 chars.
utm_term	string	optional	UTM term parameter — paid search keyword. Max 100 chars.
utm_custom_params	object	optional	Custom tracking parameters as key-value pairs appended to tracked links (optional).
reply_to	string	optional	Reply-To email address (optional). Recipients' replies go to this address instead of the From address. Must be a valid email, max 254 chars. Only meaningful for email-bearing channels.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Campaign name (required, max 255 characters)"
    },
    "channel": {
      "type": "string",
      "enum": [
        "EMAIL_ONLY",
        "SMS_ONLY",
        "WHATSAPP_ONLY",
        "PUSH_ONLY",
        "EMAIL_AND_SMS",
        "EMAIL_AND_WHATSAPP",
        "PUSH_AND_SMS",
        "PUSH_AND_WHATSAPP",
        "SMS_AND_WHATSAPP",
        "ALL_CHANNELS",
        "OMNICHANNEL",
        "EMAIL",
        "SMS",
        "WHATSAPP"
      ],
      "description": "Delivery channel (nev-api CommunicationChannel enum). Use EMAIL_ONLY, SMS_ONLY, WHATSAPP_ONLY, PUSH_ONLY for single-channel; EMAIL_AND_SMS, EMAIL_AND_WHATSAPP, PUSH_AND_SMS, PUSH_AND_WHATSAPP, SMS_AND_WHATSAPP for multi-channel; ALL_CHANNELS or OMNICHANNEL for broad delivery. Legacy values EMAIL/SMS/WHATSAPP are accepted but deprecated."
    },
    "email_subject": {
      "type": "string",
      "maxLength": 998,
      "description": "Email subject line (required when channel=EMAIL, max 998 chars per RFC 5322)"
    },
    "email_body": {
      "type": "string",
      "description": "HTML body content of the email (optional, can be set later)"
    },
    "preview_text": {
      "type": "string",
      "maxLength": 500,
      "description": "Inbox preview text (optional, shown in email client summaries)"
    },
    "from_name": {
      "type": "string",
      "maxLength": 255,
      "description": "Sender display name (optional, defaults to tenant sender name)"
    },
    "message": {
      "type": "string",
      "description": "Message text body (required when channel=SMS or WHATSAPP)"
    },
    "segment_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of segment IDs to target (optional, can be set later)"
    },
    "template_id": {
      "type": "string",
      "description": "Template ID to pre-populate campaign content (optional)"
    },
    "utm_source": {
      "type": "string",
      "maxLength": 100,
      "description": "UTM source parameter (e.g. \"nevent\", \"newsletter\"). Max 100 chars."
    },
    "utm_medium": {
      "type": "string",
      "maxLength": 100,
      "description": "UTM medium parameter (e.g. \"email\", \"sms\"). Max 100 chars. Auto-detected from channel if omitted."
    },
    "utm_campaign": {
      "type": "string",
      "maxLength": 100,
      "description": "UTM campaign parameter (e.g. \"summer-sale-2026\"). Max 100 chars. Defaults to slugified campaign name."
    },
    "utm_content": {
      "type": "string",
      "maxLength": 100,
      "description": "UTM content parameter — differentiates links/variants. Max 100 chars."
    },
    "utm_term": {
      "type": "string",
      "maxLength": 100,
      "description": "UTM term parameter — paid search keyword. Max 100 chars."
    },
    "utm_custom_params": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Custom tracking parameters as key-value pairs appended to tracked links (optional)."
    },
    "reply_to": {
      "type": "string",
      "format": "email",
      "maxLength": 254,
      "description": "Reply-To email address (optional). Recipients' replies go to this address instead of the From address. Must be a valid email, max 254 chars. Only meaningful for email-bearing channels."
    }
  },
  "required": [
    "name",
    "channel"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_schedule_campaign

Schedule an existing DRAFT campaign for delivery at a specific ISO-8601 datetime. IMPORTANT: this is a DESTRUCTIVE action — the campaign will be queued for sending to real contacts. You MUST set confirmed=true in the call, which requires explicit user consent. Call nevent_get_campaign first to verify the draft content and recipient segment. scheduled_time must be in the future (ISO-8601, e.g. 2025-06-01T10:00:00Z). The campaign transitions from DRAFT to SCHEDULED status on success.

Parameters3

campaign_id	string	required	Campaign ID to schedule (must be in DRAFT status)
scheduled_time	string	required	ISO 8601 datetime for scheduled send (must be in the future). Example: "2026-05-01T10:00:00Z" or "2026-05-01T10:00:00+02:00"
confirmed	boolean	required	Must be the literal value true to proceed. Set confirmed=true to confirm you want to schedule this campaign for sending.

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign ID to schedule (must be in DRAFT status)"
    },
    "scheduled_time": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 datetime for scheduled send (must be in the future). Example: \"2026-05-01T10:00:00Z\" or \"2026-05-01T10:00:00+02:00\""
    },
    "confirmed": {
      "type": "boolean",
      "const": true,
      "description": "Must be the literal value true to proceed. Set confirmed=true to confirm you want to schedule this campaign for sending."
    }
  },
  "required": [
    "campaign_id",
    "scheduled_time",
    "confirmed"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_quote_campaign

Estimate the credit cost and eligible audience of a campaign BEFORE sending it. Read-only pre-flight check against nev-api POST /campaigns/quote — it never debits credits and never sends. Call this after nevent_create_campaign and before nevent_schedule_campaign: scheduling a campaign the tenant cannot afford fails at send time with a 402. Returns cost (credits required), available (credits in the pool), missing (shortfall), recipientCount, affordable (boolean — the gate to check), blocked, unlimited, and an audience block with uniqueAudience, estimatedEligible per channel, eligibleAnyChannel and emailExclusions (no_email / invalid_email / opt_out / unknown). The audience block is null when the estimate could not be computed: any channel mix touching WhatsApp, more than 20 segments, or a data-api timeout — cost and recipientCount are still valid in that case. Use segment_ids from nevent_list_segments; omit them to quote the full addressable audience. Set transactional=true only for genuinely transactional sends (order confirmations, ticket delivery) — it estimates against the TRANSACTIONAL consent mode, which reaches recipients who opted out of marketing.

Parameters3

channel	string	required	Delivery channel to quote (nev-api CommunicationChannel enum). Legacy values EMAIL/SMS/WHATSAPP are accepted and mapped to the _ONLY variants. Channel mixes involving WhatsApp return a null audience block.
segment_ids	array	optional	Segment IDs to quote (optional, max 20). Omit to quote the full addressable audience for the channel. More than 20 segments makes the backend skip the audience estimate.
transactional	boolean	optional	Whether this is a transactional campaign (default false). Transactional uses the TRANSACTIONAL consent mode for the audience estimate, which reaches recipients who have opted out of marketing.

Raw schema

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "enum": [
        "EMAIL_ONLY",
        "SMS_ONLY",
        "WHATSAPP_ONLY",
        "PUSH_ONLY",
        "EMAIL_AND_SMS",
        "EMAIL_AND_WHATSAPP",
        "PUSH_AND_SMS",
        "PUSH_AND_WHATSAPP",
        "SMS_AND_WHATSAPP",
        "ALL_CHANNELS",
        "OMNICHANNEL",
        "EMAIL",
        "SMS",
        "WHATSAPP"
      ],
      "description": "Delivery channel to quote (nev-api CommunicationChannel enum). Legacy values EMAIL/SMS/WHATSAPP are accepted and mapped to the _ONLY variants. Channel mixes involving WhatsApp return a null audience block."
    },
    "segment_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "description": "Segment IDs to quote (optional, max 20). Omit to quote the full addressable audience for the channel. More than 20 segments makes the backend skip the audience estimate."
    },
    "transactional": {
      "type": "boolean",
      "description": "Whether this is a transactional campaign (default false). Transactional uses the TRANSACTIONAL consent mode for the audience estimate, which reaches recipients who have opted out of marketing."
    }
  },
  "required": [
    "channel"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_campaign_metrics

Get the delivery and engagement counters nev-api holds for one campaign: totalRecipients, totalSent, totalDelivered, totalBounces, totalComplaints, totalOpens, uniqueOpens, totalClicks, uniqueClicks, unsubscribes, the derived rates (openRate, clickRate, clickToOpenRate, bounceRate, unsubscribeRate) and the conversion counters (carts, purchases, revenue). This is the OPERATIONAL source of truth, read straight from nev-api — use it right after a send, and prefer it over nevent_campaign_report when the two disagree, because the report reads the analytics warehouse and lags behind by the data pipeline. Use nevent_campaign_report instead when you need to compare many campaigns, slice by dimension, or join against other analytics. Get campaign_id from nevent_list_campaigns. Follow up with nevent_list_campaign_recipients to see who is behind a number (for example which recipients bounced).

Parameters1

campaign_id

string

required

Campaign ID. Get it from nevent_list_campaigns, or from the response of nevent_create_campaign.

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign ID. Get it from nevent_list_campaigns, or from the response of nevent_create_campaign."
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_campaign_recipients

List the individual recipients of a campaign and what happened to each message. Use this to put names behind the aggregate numbers from nevent_get_campaign_metrics: who bounced, who clicked, who unsubscribed. Filter with status (SCHEDULED, DELIVERED, OPENED, CLICKED, BOUNCES, UNSUBSCRIBES), narrow to one audience with segment_id when the campaign targeted several segments, or find one person with search (matches name and email). Returns a paginated envelope — content (the recipient rows), page, size, totalElements, totalPages. Rows contain personal data: request the smallest page that answers the question, filter rather than paginate through everything, and do not dump full recipient lists into a summary.

Parameters6

campaign_id	string	required	Campaign ID. Get it from nevent_list_campaigns, or from the response of nevent_create_campaign.
status	string	optional	Filter recipients by delivery state. SCHEDULED = queued but not sent; DELIVERED = accepted by the receiving server; OPENED / CLICKED = engaged; BOUNCES = delivery failed; UNSUBSCRIBES = opted out from this send. Omit to return every recipient.
search	string	optional	Free-text search across recipient name and email address.
segment_id	string	optional	Restrict the listing to recipients that came from one segment. Useful on multi-segment campaigns to compare which segment engaged. Get segment IDs from nevent_list_segments.
page	integer	optional	Zero-based page number. Default: 0 (first page).
page_size	integer	optional	Recipients per page (1-100). Default: 25. Keep this small — recipient rows contain personal data and large pages waste context.

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "description": "Campaign ID. Get it from nevent_list_campaigns, or from the response of nevent_create_campaign."
    },
    "status": {
      "type": "string",
      "enum": [
        "SCHEDULED",
        "DELIVERED",
        "OPENED",
        "CLICKED",
        "BOUNCES",
        "UNSUBSCRIBES"
      ],
      "description": "Filter recipients by delivery state. SCHEDULED = queued but not sent; DELIVERED = accepted by the receiving server; OPENED / CLICKED = engaged; BOUNCES = delivery failed; UNSUBSCRIBES = opted out from this send. Omit to return every recipient."
    },
    "search": {
      "type": "string",
      "description": "Free-text search across recipient name and email address."
    },
    "segment_id": {
      "type": "string",
      "description": "Restrict the listing to recipients that came from one segment. Useful on multi-segment campaigns to compare which segment engaged. Get segment IDs from nevent_list_segments."
    },
    "page": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based page number. Default: 0 (first page)."
    },
    "page_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Recipients per page (1-100). Default: 25. Keep this small — recipient rows contain personal data and large pages waste context."
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_campaigns

Call this to discover existing campaigns before reporting on performance or scheduling new sends. Returns campaigns for the active tenant with status, channel, send date, and top-level engagement metrics (sent, open rate, click rate). Filter by status (DRAFT/SCHEDULED/SENT/FAILED), channel (EMAIL/SMS), or date range. Use the returned campaign id to call nevent_get_campaign (full content + metrics) or nevent_get_campaign_insights (AI analysis).

Parameters7

status	string	optional	Filter by campaign status: EXECUTED \| DRAFT \| PAUSED \| STOPPED \| SCHEDULED
channel	string	optional	Filter by channel: EMAIL \| SMS \| WHATSAPP
date_from	string	optional	Filter campaigns created on or after this date (ISO 8601, e.g. "2024-01-01T00:00:00Z")
date_to	string	optional	Filter campaigns created on or before this date (ISO 8601, e.g. "2024-12-31T23:59:59Z")
limit	integer	optional	Maximum number of campaigns to return (default 50, max 200)
sort	string	optional	Field to sort by: createdAt (default) \| executedAt \| name
sort_order	string	optional	Sort direction: asc \| desc (default desc)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "EXECUTED",
        "DRAFT",
        "PAUSED",
        "STOPPED",
        "SCHEDULED"
      ],
      "description": "Filter by campaign status: EXECUTED | DRAFT | PAUSED | STOPPED | SCHEDULED"
    },
    "channel": {
      "type": "string",
      "enum": [
        "EMAIL",
        "SMS",
        "WHATSAPP"
      ],
      "description": "Filter by channel: EMAIL | SMS | WHATSAPP"
    },
    "date_from": {
      "type": "string",
      "format": "date-time",
      "description": "Filter campaigns created on or after this date (ISO 8601, e.g. \"2024-01-01T00:00:00Z\")"
    },
    "date_to": {
      "type": "string",
      "format": "date-time",
      "description": "Filter campaigns created on or before this date (ISO 8601, e.g. \"2024-12-31T23:59:59Z\")"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Maximum number of campaigns to return (default 50, max 200)"
    },
    "sort": {
      "type": "string",
      "enum": [
        "createdAt",
        "executedAt",
        "name"
      ],
      "default": "createdAt",
      "description": "Field to sort by: createdAt (default) | executedAt | name"
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Sort direction: asc | desc (default desc)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_campaign

Retrieve the complete record of a campaign: email subject and body HTML, sending profile, all delivery and engagement metrics (sent, delivered, opens, clicks, unsubscribes, bounces), and tracked links with click counts. Call this after nevent_list_campaigns to drill into a specific campaign. Next step: nevent_get_campaign_insights for AI-generated recommendations, or nevent_campaign_report for a full analytics query.

Parameters1

campaign_id

string

required

The campaign Identifier. Use nevent_list_campaigns to discover valid campaign IDs.

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "description": "The campaign Identifier. Use nevent_list_campaigns to discover valid campaign IDs."
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_campaign_insights

Get pre-computed AI analysis for a specific campaign: performance summary, detected anomalies (e.g. unusually high bounce rate), and improvement recommendations. Call this after nevent_get_campaign when the user asks "how did this campaign perform?" or "what could be improved?". Complements raw metrics from nevent_get_campaign with narrative insights.

Parameters1

campaign_id

string

required

The campaign Identifier. Use nevent_list_campaigns to discover valid campaign IDs.

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "description": "The campaign Identifier. Use nevent_list_campaigns to discover valid campaign IDs."
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_templates

Call this to discover available email templates before creating a campaign. Returns templates for the active tenant: id, name, tags, and whether they use MJML or HTML. Use the returned template id in nevent_create_campaign. Call nevent_get_template to inspect the full HTML/MJML source of a specific template.

Parameters5

tags	array	optional	Filter templates by tags. Only templates that have ALL specified tags are returned. Omit to return templates regardless of tags.
content_nature	string	optional	Filter by AI-assigned content nature classification (e.g. "promotional", "transactional", "newsletter", "event_reminder"). Omit to return templates of all natures.
limit	integer	optional	Maximum number of templates to return (default 50, max 200)
sort	string	optional	Sort field: createdAt \| modifiedAt \| name (default modifiedAt)
sort_order	string	optional	Sort direction: asc \| desc (default desc)

Raw schema

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter templates by tags. Only templates that have ALL specified tags are returned. Omit to return templates regardless of tags."
    },
    "content_nature": {
      "type": "string",
      "description": "Filter by AI-assigned content nature classification (e.g. \"promotional\", \"transactional\", \"newsletter\", \"event_reminder\"). Omit to return templates of all natures."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Maximum number of templates to return (default 50, max 200)"
    },
    "sort": {
      "type": "string",
      "enum": [
        "createdAt",
        "modifiedAt",
        "name"
      ],
      "default": "modifiedAt",
      "description": "Sort field: createdAt | modifiedAt | name (default modifiedAt)"
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Sort direction: asc | desc (default desc)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_template

Retrieve the full content of an email template: MJML source, rendered HTML, tags, and usage metrics (how many campaigns used this template). Call this after nevent_list_templates when the user wants to inspect, copy, or modify a template. Next step: nevent_update_template to change the content, or nevent_create_campaign to use this template in a new campaign.

Parameters1

template_id

string

required

The Identifier of the template to retrieve. Get valid IDs from nevent_list_templates.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "The Identifier of the template to retrieve. Get valid IDs from nevent_list_templates."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_create_template

Create and persist a new email template with MJML or raw HTML content. Prefer MJML for responsive email (set format="MJML"). The template is saved and available for reuse across campaigns. After creation, call nevent_create_campaign with the returned template id to send it to a segment.

Parameters5

name	string	required	Human-readable name for the template, e.g. "Event Reminder — Spring 2026"
format	string	required	Template format: "html" for raw HTML, "mjml" for MJML source code
mjml_body	string	optional	MJML source code for the template. Provide this field when format is "mjml".
html_body	string	optional	Raw HTML content for the template. Provide this field when format is "html".
tags	array	optional	List of string tags to categorise the template (e.g. ["promotional", "event", "reminder"]). Omit to create with no tags.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable name for the template, e.g. \"Event Reminder — Spring 2026\""
    },
    "format": {
      "type": "string",
      "enum": [
        "html",
        "mjml"
      ],
      "description": "Template format: \"html\" for raw HTML, \"mjml\" for MJML source code"
    },
    "mjml_body": {
      "type": "string",
      "description": "MJML source code for the template. Provide this field when format is \"mjml\"."
    },
    "html_body": {
      "type": "string",
      "description": "Raw HTML content for the template. Provide this field when format is \"html\"."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of string tags to categorise the template (e.g. [\"promotional\", \"event\", \"reminder\"]). Omit to create with no tags."
    }
  },
  "required": [
    "name",
    "format"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_update_template

Update an existing email template: change the name, MJML/HTML content, or tags. Call nevent_get_template first to inspect the current version before modifying. At least one of name, content, or tags must be provided. Note: updating a template does NOT retroactively change campaigns already sent with it.

Parameters6

template_id	string	required	Identifier of the template to update. Use nevent_list_templates to get valid template IDs.
name	string	optional	New human-readable name for the template. Omit to leave unchanged.
format	string	optional	New template format: "html" or "mjml". Omit to leave unchanged.
mjml_body	string	optional	New MJML source code for the template. Omit to leave unchanged.
html_body	string	optional	New raw HTML content for the template. Omit to leave unchanged.
tags	array	optional	Replacement list of tags. The full tag list is replaced when provided. Omit to leave existing tags unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "Identifier of the template to update. Use nevent_list_templates to get valid template IDs."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "New human-readable name for the template. Omit to leave unchanged."
    },
    "format": {
      "type": "string",
      "enum": [
        "html",
        "mjml"
      ],
      "description": "New template format: \"html\" or \"mjml\". Omit to leave unchanged."
    },
    "mjml_body": {
      "type": "string",
      "description": "New MJML source code for the template. Omit to leave unchanged."
    },
    "html_body": {
      "type": "string",
      "description": "New raw HTML content for the template. Omit to leave unchanged."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Replacement list of tags. The full tag list is replaced when provided. Omit to leave existing tags unchanged."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_clone_template

Clone an existing email template to create a duplicate as a starting point for a new campaign. Use after nevent_list_templates to pick a template to duplicate. Returns the new cloned template (id, name with "(Copy)" suffix, format, tags). Typically follow with nevent_rename_template and nevent_update_template to customize the clone.

Parameters1

template_id

string

required

The ID of the email template to clone. Use nevent_list_templates to discover valid template IDs. The clone will have a new unique ID and its name will be suffixed with "(Copy)".

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1,
      "description": "The ID of the email template to clone. Use nevent_list_templates to discover valid template IDs. The clone will have a new unique ID and its name will be suffixed with \"(Copy)\"."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_rename_template

Rename an email template without modifying its content (lightweight — no re-render triggered). Use after nevent_clone_template to give the clone a proper name, or to reorganize existing templates. Returns the updated template with the new name. Next step: nevent_update_template to change content, or nevent_preview_template to validate rendering.

Parameters2

template_id	string	required	The ID of the email template to rename. Use nevent_list_templates to get valid template IDs.
name	string	required	The new name for the template. Must be between 1 and 255 characters. Duplicate names are allowed by the API.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1,
      "description": "The ID of the email template to rename. Use nevent_list_templates to get valid template IDs."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The new name for the template. Must be between 1 and 255 characters. Duplicate names are allowed by the API."
    }
  },
  "required": [
    "template_id",
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_preview_template

Preview a template with merge tags resolved against a sample user's profile. Returns originalBody (raw {{tags}}) and personalizedBody (tags replaced with user data), plus detectedMergeTags (all unique tags found). Always call before nevent_send_test_template to validate rendering. Provide sample_user_id or sample_user_email to see real personalization; omit both to see raw tags only.

Parameters4

template_id	string	required	The ID of the email template to preview. Use nevent_list_templates to discover valid template IDs.
sample_user_id	string	optional	Optional MongoDB user ID for merge-tag personalization. When provided, {{name}}, {{email}} and custom fields are resolved from this user's profile. Takes priority over sample_user_email. Omit to return raw merge tags only.
sample_user_email	string	optional	Optional user email to look up within the active tenant for merge-tag personalization. Ignored when sample_user_id is also provided. Omit to return raw merge tags only.
subject	string	optional	Optional subject line to preview with merge-tag resolution. Example: "Hola {{name\|title}}, tu resumen semanal". Omit to skip subject personalization.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1,
      "description": "The ID of the email template to preview. Use nevent_list_templates to discover valid template IDs."
    },
    "sample_user_id": {
      "type": "string",
      "minLength": 1,
      "description": "Optional MongoDB user ID for merge-tag personalization. When provided, {{name}}, {{email}} and custom fields are resolved from this user's profile. Takes priority over sample_user_email. Omit to return raw merge tags only."
    },
    "sample_user_email": {
      "type": "string",
      "format": "email",
      "description": "Optional user email to look up within the active tenant for merge-tag personalization. Ignored when sample_user_id is also provided. Omit to return raw merge tags only."
    },
    "subject": {
      "type": "string",
      "description": "Optional subject line to preview with merge-tag resolution. Example: \"Hola {{name|title}}, tu resumen semanal\". Omit to skip subject personalization."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_send_test_template

Send a test email of the template to one or more email addresses via SES. Use after nevent_preview_template validates rendering. Test emails carry test indicators in headers and are sent via AWS SES. This call may take up to 60 seconds due to SES delivery. Returns success status, list of recipients the email was sent to, and any error details.

Parameters6

template_id	string	required	The ID of the email template to send as a test. Use nevent_list_templates to discover valid template IDs.
emails	array	required	List of email addresses to send the test email to. Each entry must be a valid email address. Minimum 1, maximum 10 recipients. Example: ["qa@example.com", "dev@company.com"].
subject	string	optional	Optional subject line for the test email. Omit to use the default subject from the template.
sample_user_id	string	optional	Optional user ID for merge-tag personalization in the test email. When provided, {{name}}, {{email}} and custom fields are resolved from this user's profile. Takes priority over sample_user_email.
sample_user_email	string	optional	Optional user email within the active tenant for merge-tag personalization. Ignored when sample_user_id is also provided.
parameters	object	optional	Optional custom parameters for merge-tag substitution in the test email. Key-value pairs where keys match merge tag names. Example: {name: "Juan", city: "Madrid"}. When provided, overrides sample user profile data for the corresponding tags.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1,
      "description": "The ID of the email template to send as a test. Use nevent_list_templates to discover valid template IDs."
    },
    "emails": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      },
      "minItems": 1,
      "maxItems": 10,
      "description": "List of email addresses to send the test email to. Each entry must be a valid email address. Minimum 1, maximum 10 recipients. Example: [\"qa@example.com\", \"dev@company.com\"]."
    },
    "subject": {
      "type": "string",
      "description": "Optional subject line for the test email. Omit to use the default subject from the template."
    },
    "sample_user_id": {
      "type": "string",
      "minLength": 1,
      "description": "Optional user ID for merge-tag personalization in the test email. When provided, {{name}}, {{email}} and custom fields are resolved from this user's profile. Takes priority over sample_user_email."
    },
    "sample_user_email": {
      "type": "string",
      "format": "email",
      "description": "Optional user email within the active tenant for merge-tag personalization. Ignored when sample_user_id is also provided."
    },
    "parameters": {
      "type": "object",
      "additionalProperties": {},
      "description": "Optional custom parameters for merge-tag substitution in the test email. Key-value pairs where keys match merge tag names. Example: {name: \"Juan\", city: \"Madrid\"}. When provided, overrides sample user profile data for the corresponding tags."
    }
  },
  "required": [
    "template_id",
    "emails"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_sending_profile

Call this before creating a campaign to verify the tenant is ready to send email. Returns: sender domain(s) and their validation status, warm-up phase (cold/warming/warmed), daily send rate cap, and throttle settings. If the sending profile is not validated or still in warm-up, warn the user before scheduling a large campaign. Combine with nevent_get_suppressions_summary for a full deliverability health check.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_suppressions_summary

Get a deliverability health snapshot for the active tenant: total suppressed emails (hard bounces + complaints + manual unsubscribes), 30-day trend, and breakdown by suppression reason. Call this when the user asks about list health, unsubscribe rates, or bounce issues. A suppression rate above 2% indicates deliverability risk — surface this as a warning before scheduling a large campaign.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_paid_ads_status

Check if a paid ads provider account (meta, google, or tiktok) is connected to this tenant and when data was last synced. Call this first before any ads queries to confirm the integration is active. Returns: connected (bool), accountId, accountName, lastSyncAt.

Parameters1

provider

string

required

Ad provider: meta | google | tiktok

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_paid_ads_health

Get operational health signals for a paid ads provider. Always call this before claiming "no data" to the user — it surfaces throttle state, feature gate enrollment, stale syncs, and tier. Key fields: throttle.isThrottled (API throttled), throttle.nextAttemptAt (next retry), featureGate.isInTenantAllowlist (pilot access), lastSuccessfulSyncAt, lastSuccessfulInsightsAt, backfillEnabled. A 404 here means this tenant is not enrolled in the insights pilot for this provider.

Parameters1

provider

string

required

Ad provider: meta | google | tiktok

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_paid_campaigns

List all paid campaigns synced from a provider (meta, google, or tiktok). Call this to discover campaignId values — you need a campaignId to call insights or ad group tools. Returns campaign IDs, names, statuses, objectives, and budgets. Use the returned campaignId values with nevent_get_paid_campaign_insights and nevent_list_paid_ad_groups.

Parameters1

provider

string

required

Ad provider: meta | google | tiktok

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_paid_campaign_insights

Get daily performance metrics for a specific paid campaign. Use after nevent_list_paid_campaigns to get a valid campaignId. Date range defaults to the last 7 days when from/to are omitted. Returns daily rows with: spend, impressions, reach, frequency, clicks, CTR, CPM, CPC, ROAS, engagement rate, video metrics. Each row.date is an ISO 8601 UTC timestamp (e.g. "2026-05-10T00:00:00Z"). A 404 may mean this tenant is not enrolled in the insights pilot — call nevent_paid_ads_health to confirm.

Parameters4

provider	string	required	Ad provider: meta \| google \| tiktok
campaignId	string	required	Paid campaign ID from the provider (not a Nevent ObjectId). Use nevent_list_paid_campaigns to get valid campaignId values.
from	string	optional	Start date for insights window (yyyy-MM-dd). Defaults to 7 days ago when omitted.
to	any	optional	End date for insights window (yyyy-MM-dd). Defaults to today when omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Paid campaign ID from the provider (not a Nevent ObjectId). Use nevent_list_paid_campaigns to get valid campaignId values."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date for insights window (yyyy-MM-dd). Defaults to 7 days ago when omitted."
    },
    "to": {
      "$ref": "#/properties/from",
      "description": "End date for insights window (yyyy-MM-dd). Defaults to today when omitted."
    }
  },
  "required": [
    "provider",
    "campaignId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_paid_attribution

Get the most business-focused view of paid ads: links campaigns to actual ticket sales and revenue via UTM matching. Returns per-campaign: ticketsSold, revenue, budget, utmCampaigns (matched UTM values), status. Use this when the user asks about ROI, conversion, or revenue from paid ads. Use after nevent_list_paid_campaigns to cross-reference campaign IDs.

Parameters1

provider

string

required

Ad provider: meta | google | tiktok

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_paid_ad_groups

List ad groups (ad sets) for a paid ads provider, optionally filtered by campaign. Use after nevent_list_paid_campaigns to drill down into a campaign's ad sets. Returns ad group IDs, names, statuses, and lastSyncedAt. Use the returned adGroupId values with the ad group insights, targeting, and comparative stats tools.

Parameters2

provider	string	required	Ad provider: meta \| google \| tiktok
campaignId	string	optional	Optional: filter ad groups by parent campaign ID. Use nevent_list_paid_campaigns to get valid campaignId values.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Optional: filter ad groups by parent campaign ID. Use nevent_list_paid_campaigns to get valid campaignId values."
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_paid_ad_group_insights

Get daily performance metrics for a specific ad group (ad set). Use after nevent_list_paid_ad_groups to get a valid adGroupId. Date range defaults to the last 7 days when from/to are omitted. Returns daily rows with: spend, impressions, reach, frequency, clicks, CTR, CPM, CPC, ROAS, engagement rate, video metrics. Each row.date is an ISO 8601 UTC timestamp (e.g. "2026-05-10T00:00:00Z"). A 404 may mean this tenant is not enrolled in the insights pilot — call nevent_paid_ads_health to confirm.

Parameters4

provider	string	required	Ad provider: meta \| google \| tiktok
adGroupId	string	required	Ad group (ad set) ID from the provider. Use nevent_list_paid_ad_groups to get valid adGroupId values.
from	string	optional	Start date for insights window (yyyy-MM-dd). Defaults to 7 days ago when omitted.
to	any	optional	End date for insights window (yyyy-MM-dd). Defaults to today when omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "adGroupId": {
      "type": "string",
      "minLength": 1,
      "description": "Ad group (ad set) ID from the provider. Use nevent_list_paid_ad_groups to get valid adGroupId values."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date for insights window (yyyy-MM-dd). Defaults to 7 days ago when omitted."
    },
    "to": {
      "$ref": "#/properties/from",
      "description": "End date for insights window (yyyy-MM-dd). Defaults to today when omitted."
    }
  },
  "required": [
    "provider",
    "adGroupId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_paid_ad_group_comparative_stats

Compare an ad group's performance metrics against the mean of its campaign sibling ad groups. Use to detect underperforming ad sets — each metric (costPerResult, CPM, frequency, CTR) is returned with its campaign sibling mean and ratioVsMean (1.0 = on par). For cost metrics (costPerResult, CPM, frequency): ratio > 1.0 means WORSE than siblings (higher cost). For CTR: ratio > 1.0 means BETTER than siblings (higher CTR is better). Use after nevent_list_paid_ad_groups to get a valid adGroupId. A 404 may mean this tenant is not enrolled in the insights pilot — call nevent_paid_ads_health to confirm.

Parameters4

provider	string	required	Ad provider: meta \| google \| tiktok
adGroupId	string	required	Ad group (ad set) ID from the provider. Use nevent_list_paid_ad_groups to get valid adGroupId values.
from	string	optional	Start date for the comparison window (yyyy-MM-dd). Defaults to 7 days ago when omitted.
to	any	optional	End date for the comparison window (yyyy-MM-dd). Defaults to today when omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "adGroupId": {
      "type": "string",
      "minLength": 1,
      "description": "Ad group (ad set) ID from the provider. Use nevent_list_paid_ad_groups to get valid adGroupId values."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date for the comparison window (yyyy-MM-dd). Defaults to 7 days ago when omitted."
    },
    "to": {
      "$ref": "#/properties/from",
      "description": "End date for the comparison window (yyyy-MM-dd). Defaults to today when omitted."
    }
  },
  "required": [
    "provider",
    "adGroupId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_paid_ad_group_targeting

Get the full audience targeting configuration for an ad group. Use after nevent_list_paid_ad_groups to get a valid adGroupId. Returns: ageRange, genders, geoSummary (countries/cities/regions), topInterests, topBehaviors, placements, Advantage+ flags (automaticPlacements, expandAge, expandGender), custom and excluded audiences, bidStrategy, promotedObject. A 404 may mean this tenant is not enrolled in the insights pilot — call nevent_paid_ads_health to confirm.

Parameters2

provider	string	required	Ad provider: meta \| google \| tiktok
adGroupId	string	required	Ad group (ad set) ID from the provider. Use nevent_list_paid_ad_groups to get valid adGroupId values.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "adGroupId": {
      "type": "string",
      "minLength": 1,
      "description": "Ad group (ad set) ID from the provider. Use nevent_list_paid_ad_groups to get valid adGroupId values."
    }
  },
  "required": [
    "provider",
    "adGroupId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_paid_ads

List individual ads for a paid ads provider, optionally filtered by campaign and/or ad group. Use after nevent_list_paid_campaigns or nevent_list_paid_ad_groups to drill down to ad level. Returns ad IDs, names, statuses, UTM fields (utmSource, utmMedium, utmCampaign, utmContainsMacros), and lastSyncedAt. Use the returned adId values with nevent_get_paid_ad_creative.

Parameters3

provider	string	required	Ad provider: meta \| google \| tiktok
campaignId	string	optional	Optional: filter ads by parent campaign ID. Use nevent_list_paid_campaigns to get valid campaignId values.
adGroupId	string	optional	Optional: filter ads by parent ad group ID. Use nevent_list_paid_ad_groups to get valid adGroupId values.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "campaignId": {
      "type": "string",
      "minLength": 1,
      "description": "Optional: filter ads by parent campaign ID. Use nevent_list_paid_campaigns to get valid campaignId values."
    },
    "adGroupId": {
      "type": "string",
      "minLength": 1,
      "description": "Optional: filter ads by parent ad group ID. Use nevent_list_paid_ad_groups to get valid adGroupId values."
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_paid_ad_creative

Get the creative content of a specific ad: copy (body, title, description, CTA), click URL, UTM params, and pre-signed S3 image/video URLs (TTL ~1 hour). Use after nevent_list_paid_ads to get a valid adId. Null imageUrl/videoUrl means the asset mirror job has not run yet — retry in ~5 minutes. For Dynamic Creative Ads (hasDca: true), the dca field contains multiple creative variants. A 404 may mean this tenant is not enrolled in the insights pilot — call nevent_paid_ads_health to confirm.

Parameters2

provider	string	required	Ad provider: meta \| google \| tiktok
adId	string	required	Ad ID from the provider. Use nevent_list_paid_ads to get valid adId values.

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "meta",
        "google",
        "tiktok"
      ],
      "description": "Ad provider: meta | google | tiktok"
    },
    "adId": {
      "type": "string",
      "minLength": 1,
      "description": "Ad ID from the provider. Use nevent_list_paid_ads to get valid adId values."
    }
  },
  "required": [
    "provider",
    "adId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_short_urls

List all short URLs for the current tenant with their tracking metrics (click count, last clicked). Use to discover existing campaign links or to audit active tracking URLs. Returns items (array of ShortUrlDTO), total, page, pageSize, totalPages. Key fields per item: id (use with nevent_get_short_url_metrics or nevent_get_short_url_clicks), shortCode (use with nevent_get_short_url_campaign_metrics or nevent_list_short_url_user_links), shortUrl, longUrl, title, tags, clickCount, isActive, isParent. Filter by isActive=true for active links only. Use search to filter by title or URL.

Parameters4

isActive	boolean	optional	Filter by active status. true = only active links, false = only inactive/expired links. Omit to return both.
search	string	optional	Free-text search across short code, title, and target URL. E.g. "summer" to find links tagged or titled with that word.
page	integer	optional	Zero-based page number for pagination. Default: 0 (first page).
pageSize	integer	optional	Number of results per page. Default: 20. Max: 200.

Raw schema

{
  "type": "object",
  "properties": {
    "isActive": {
      "type": "boolean",
      "description": "Filter by active status. true = only active links, false = only inactive/expired links. Omit to return both."
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "description": "Free-text search across short code, title, and target URL. E.g. \"summer\" to find links tagged or titled with that word."
    },
    "page": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based page number for pagination. Default: 0 (first page)."
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Number of results per page. Default: 20. Max: 200."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_short_url

Get complete details of a specific short URL including target URL, metadata, creation date, expiration, tags, and current click count. Use after nevent_list_short_urls to get the `id`. Key fields returned: id, shortCode, shortUrl, longUrl, title, tags, metadata, clickCount, lastClickedAt, isActive, isExpired, isParent, parentShortCode, userId, userLinksCount. Use the returned id with nevent_get_short_url_metrics for time-series analytics.

Parameters1

string

required

MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field "id".

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field \"id\"."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_short_url_metrics

Get aggregated click analytics for a specific short URL over a time window (default 30 days). Use after nevent_list_short_urls to get the `id`. Returns: totalClicks, uniqueVisitors, firstClickAt, lastClickAt, clicksByDay (date → count), clicksByCountry, clicksByDevice (mobile/desktop/tablet), clicksByBrowser, clicksByOs, topReferers. Use for performance analysis of individual tracking links. For campaign-wide aggregation across all user links, use nevent_get_short_url_campaign_metrics instead.

Parameters2

id	string	required	MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field "id".
days	integer	optional	Number of days to include in metrics calculation. Default: 30. Max: 365. Use 7 for last week, 30 for last month, 90 for last quarter.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field \"id\"."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Number of days to include in metrics calculation. Default: 30. Max: 365. Use 7 for last week, 30 for last month, 90 for last quarter."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_short_url_campaign_metrics

Get aggregated click metrics across a parent short URL and all its per-user variants. Use when a marketing campaign was sent with per-user tracking links (created via nevent_create_bulk_user_short_urls) to see total reach and CTR. Requires the `parentShortCode` from nevent_list_short_urls (where isParent=true). Returns: totalChildUrls, totalClicks, urlsWithClicks, avgClicksPerUrl, clickThroughRate (%), topUsersByClicks (userId, shortCode, clickCount, lastClickedAt), clicksByDay, clicksByDevice, clicksByBrowser, clicksByCountry. This tool aggregates across ALL child user links — use nevent_get_short_url_metrics(id) when you need per-link breakdown for a single URL.

Parameters3

parentShortCode	string	required	Short code of the parent (campaign) short URL (6-8 alphanumeric characters). Obtain from nevent_list_short_urls where isParent=true, field "shortCode".
days	integer	optional	Number of days to include in metrics. Default: 30.
topN	integer	optional	Number of top-performing users to return in topUsersByClicks. Default: 10.

Raw schema

{
  "type": "object",
  "properties": {
    "parentShortCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{6,8}$",
      "description": "Short code of the parent (campaign) short URL (6-8 alphanumeric characters). Obtain from nevent_list_short_urls where isParent=true, field \"shortCode\"."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Number of days to include in metrics. Default: 30."
    },
    "topN": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Number of top-performing users to return in topUsersByClicks. Default: 10."
    }
  },
  "required": [
    "parentShortCode"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_get_short_url_clicks

Get individual click event records for a specific short URL, ordered by most recent first. Use after nevent_list_short_urls to get the `id`. Each click record includes: clickedAt, ipAddress, userAgent, referer, country, city, device, browser, os, utmSource, utmCampaign, fbclid, gclid, isPaidTraffic. Use for detailed click attribution, fraud detection, or per-user behavior analysis. Default returns 100 most recent clicks; use limit to adjust.

Parameters2

id	string	required	MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field "id".
limit	integer	optional	Maximum number of recent click records to return, ordered newest-first. Default: 100. Max: 1000.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field \"id\"."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "Maximum number of recent click records to return, ordered newest-first. Default: 100. Max: 1000."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_short_url_user_links

List all per-user short URL variants created under a parent (campaign) short URL. Use after nevent_create_bulk_user_short_urls to inspect the generated links, or to audit which users have a tracking link for a campaign. Requires the `parentShortCode` from nevent_list_short_urls (where isParent=true). Returns an array of ShortUrlDTO — each with userId, shortCode, shortUrl, clickCount. Use the returned `id` values with nevent_get_short_url_metrics for per-user analytics.

Parameters1

parentShortCode

string

required

Short code of the parent (campaign) short URL (6-8 alphanumeric characters). Obtain from nevent_list_short_urls where isParent=true, field "shortCode".

Raw schema

{
  "type": "object",
  "properties": {
    "parentShortCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{6,8}$",
      "description": "Short code of the parent (campaign) short URL (6-8 alphanumeric characters). Obtain from nevent_list_short_urls where isParent=true, field \"shortCode\"."
    }
  },
  "required": [
    "parentShortCode"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_create_short_url

Create a new short URL that redirects to the specified destination. Persists immediately — the short code is active as soon as the call returns. Requires at minimum a valid longUrl. All other fields are optional. Returns the created ShortUrlDTO with: id, shortCode, shortUrl (full redirect URL), longUrl, title, tags, isActive. Use the returned shortCode with nevent_create_bulk_user_short_urls to generate per-user variants. WRITE operation — requires STANDARD or FULL operation mode. In READ_ONLY mode this tool returns an operation_not_permitted error immediately without making any API call.

Parameters6

longUrl	string	required	The full destination URL to redirect to. Must include protocol (https:// or http://). Example: "https://nevent.es/events/summer-festival-2025".
title	string	optional	Descriptive label for the short URL (max 200 chars). Shown in the admin list view and used for search.
expiresAt	string	optional	Expiration date/time in ISO 8601 format, e.g. "2025-12-31T23:59:59.000Z". After this date the short URL stops redirecting. Omit for a permanent link.
tags	array	optional	Tags for categorization and filtering. Example: ["campaign", "summer", "2025"]. Use consistent tag names across campaigns.
metadata	object	optional	Arbitrary key-value metadata. Useful for storing campaignId, eventId, or other business identifiers. Example: {"campaignId": "NEV-123", "eventId": "evt-456"}.
customShortCode	string	optional	Custom short code (6-8 alphanumeric characters). If omitted, a unique code is auto-generated. Example: "SUMMER". Use nevent_validate_short_code (if available) to check availability first.

Raw schema

{
  "type": "object",
  "properties": {
    "longUrl": {
      "type": "string",
      "format": "uri",
      "description": "The full destination URL to redirect to. Must include protocol (https:// or http://). Example: \"https://nevent.es/events/summer-festival-2025\"."
    },
    "title": {
      "type": "string",
      "maxLength": 200,
      "description": "Descriptive label for the short URL (max 200 chars). Shown in the admin list view and used for search."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Expiration date/time in ISO 8601 format, e.g. \"2025-12-31T23:59:59.000Z\". After this date the short URL stops redirecting. Omit for a permanent link."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Tags for categorization and filtering. Example: [\"campaign\", \"summer\", \"2025\"]. Use consistent tag names across campaigns."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Arbitrary key-value metadata. Useful for storing campaignId, eventId, or other business identifiers. Example: {\"campaignId\": \"NEV-123\", \"eventId\": \"evt-456\"}."
    },
    "customShortCode": {
      "type": "string",
      "minLength": 6,
      "maxLength": 8,
      "pattern": "^[A-Za-z0-9]+$",
      "description": "Custom short code (6-8 alphanumeric characters). If omitted, a unique code is auto-generated. Example: \"SUMMER\". Use nevent_validate_short_code (if available) to check availability first."
    }
  },
  "required": [
    "longUrl"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_update_short_url

Update an existing short URL's configuration. Only provided fields are changed — omitted fields remain unchanged. Changes apply immediately. Use after nevent_list_short_urls to get the `id`. Supported updates: title, expiresAt (pass null to remove expiration), isActive (true/false), tags (replaces existing), metadata (replaces existing), longUrl (changes redirect destination). Returns the updated ShortUrlDTO. WRITE operation — requires STANDARD or FULL operation mode. In READ_ONLY mode this tool returns an operation_not_permitted error immediately without making any API call.

Parameters7

id	string	required	MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field "id".
title	string	optional	New descriptive title (max 200 chars). Replaces the existing title.
expiresAt	any	optional	New expiration date/time (ISO 8601). Pass null to remove an existing expiration and make the link permanent. Omit this field entirely to leave expiration unchanged.
isActive	boolean	optional	Activate (true) or deactivate (false) the short URL. Deactivated links stop redirecting immediately.
tags	array	optional	New tag list. Replaces (not merges) the existing tags.
metadata	object	optional	New metadata object. Replaces (not merges) the existing metadata.
longUrl	string	optional	New destination URL. Changes where existing links redirect to — takes effect immediately.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$",
      "description": "MongoDB ObjectId of the short URL (24 hex characters). Obtain from nevent_list_short_urls response field \"id\"."
    },
    "title": {
      "type": "string",
      "maxLength": 200,
      "description": "New descriptive title (max 200 chars). Replaces the existing title."
    },
    "expiresAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "New expiration date/time (ISO 8601). Pass null to remove an existing expiration and make the link permanent. Omit this field entirely to leave expiration unchanged."
    },
    "isActive": {
      "type": "boolean",
      "description": "Activate (true) or deactivate (false) the short URL. Deactivated links stop redirecting immediately."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "New tag list. Replaces (not merges) the existing tags."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "New metadata object. Replaces (not merges) the existing metadata."
    },
    "longUrl": {
      "type": "string",
      "format": "uri",
      "description": "New destination URL. Changes where existing links redirect to — takes effect immediately."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_create_bulk_user_short_urls

Generate per-user short URL variants for an existing parent short URL. Each user receives their own unique short link that resolves to the same destination as the parent, but identifies the user on click — used for fan-level click attribution in email/SMS campaigns. The parent short URL must already exist (create it first with nevent_create_short_url). Requires: parentShortCode (from nevent_list_short_urls) and userIds (list of user IDs). Returns: parentShortCode, totalRequested, totalCreated, createdLinks (array of ShortUrlDTO with userId, shortCode, shortUrl per user). Use nevent_get_short_url_campaign_metrics afterwards to track aggregate CTR. WRITE operation — requires STANDARD or FULL operation mode. In READ_ONLY mode this tool returns an operation_not_permitted error immediately without making any API call. Note: parentShortCode is sent in both the URL path and request body — they must match (validated server-side).

Parameters2

parentShortCode	string	required	Short code of the parent (campaign) short URL (6-8 alphanumeric characters) under which user links will be created. Must already exist. Obtain from nevent_list_short_urls where isParent=true.
userIds	array	required	List of user IDs (MongoDB ObjectIds or Nevent user identifiers) to create individual tracking links for. Each user gets a unique short code that resolves to the same destination as the parent. Duplicates are skipped.

Raw schema

{
  "type": "object",
  "properties": {
    "parentShortCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{6,8}$",
      "description": "Short code of the parent (campaign) short URL (6-8 alphanumeric characters) under which user links will be created. Must already exist. Obtain from nevent_list_short_urls where isParent=true."
    },
    "userIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "description": "List of user IDs (MongoDB ObjectIds or Nevent user identifiers) to create individual tracking links for. Each user gets a unique short code that resolves to the same destination as the parent. Duplicates are skipped."
    }
  },
  "required": [
    "parentShortCode",
    "userIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_short_url_destinations

List short links grouped by DESTINATION URL — one row per destination instead of one per link. Use this to answer "how much traffic is this landing page getting across all my campaigns?", which nevent_list_short_urls cannot answer because every campaign send creates its own parent link. Campaign parents pointing at the same canonical destination collapse into a single row with aggregated totalClicks, linksCount (how many links form the group) and campaignsCount (how many distinct campaigns used it). Unlike nevent_list_short_urls, this INCLUDES system-managed assistant links (the ones the chatbot pushes), flagged readOnly=true — never try to edit or delete those. Filter with origin: MANUAL (human-created), CAMPAIGN (generated by sends), ASSISTANT (chatbot), or ALL (default). Each row carries canonicalId and members[] (id + shortCode) — pass those ids to nevent_get_short_url or nevent_get_short_url_metrics to drill into a specific link. Pagination is over GROUPS, not documents.

Parameters4

origin	string	optional	Filter by where the links came from. ALL (default) = every origin; MANUAL = links a human created; CAMPAIGN = links generated by campaign sends; ASSISTANT = system-managed links the chatbot pushed (read-only).
search	string	optional	Free-text search across destination URL, title, and short code. E.g. "festival" to find every destination for that event.
page	integer	optional	Zero-based page number over destination GROUPS. Default: 0 (first page).
pageSize	integer	optional	Number of destination groups per page (1-100). Default: 20.

Raw schema

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "enum": [
        "ALL",
        "MANUAL",
        "CAMPAIGN",
        "ASSISTANT"
      ],
      "description": "Filter by where the links came from. ALL (default) = every origin; MANUAL = links a human created; CAMPAIGN = links generated by campaign sends; ASSISTANT = system-managed links the chatbot pushed (read-only)."
    },
    "search": {
      "type": "string",
      "description": "Free-text search across destination URL, title, and short code. E.g. \"festival\" to find every destination for that event."
    },
    "page": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based page number over destination GROUPS. Default: 0 (first page)."
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Number of destination groups per page (1-100). Default: 20."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_upload_image

Upload an image to the Nevent media library and get a CDN URL. Accepts base64-encoded images as a data URL (data:image/png;base64,...) or as raw base64 with an explicit mimeType. Returns a destinationUrl (CloudFront CDN URL) that can be used directly in <img src="..."> inside email template HTML. Maximum decoded size: 5 MB. Upload the image, then reference the returned destinationUrl in nevent_update_template or nevent_create_template HTML content.

Parameters3

source	string	required	Base64-encoded image. Two accepted forms: 1. Data URL: "data:image/png;base64,<base64data>" — MIME type parsed from prefix. 2. Raw base64 string — mimeType parameter required. Maximum decoded size: 5 MB. URL sources are not accepted.
imageName	string	optional	Optional file name for the uploaded resource (e.g. "event-banner.png"). When omitted, a name is generated from the upload timestamp.
mimeType	string	optional	MIME type of the image, e.g. "image/png" or "image/jpeg". Required when source is raw base64 (no data URL prefix). Ignored when source is a data URL (MIME type parsed from prefix). Common values: image/png \| image/jpeg \| image/gif \| image/webp \| image/svg+xml.

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "minLength": 1,
      "description": "Base64-encoded image. Two accepted forms:\n1. Data URL: \"data:image/png;base64,<base64data>\" — MIME type parsed from prefix.\n2. Raw base64 string — mimeType parameter required.\nMaximum decoded size: 5 MB. URL sources are not accepted."
    },
    "imageName": {
      "type": "string",
      "minLength": 1,
      "description": "Optional file name for the uploaded resource (e.g. \"event-banner.png\"). When omitted, a name is generated from the upload timestamp."
    },
    "mimeType": {
      "type": "string",
      "minLength": 1,
      "description": "MIME type of the image, e.g. \"image/png\" or \"image/jpeg\". Required when source is raw base64 (no data URL prefix). Ignored when source is a data URL (MIME type parsed from prefix). Common values: image/png | image/jpeg | image/gif | image/webp | image/svg+xml."
    }
  },
  "required": [
    "source"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_list_images

List all images stored in the Nevent media library for the current tenant. Returns each image's CDN URL (src), file name, MIME type, and size in bytes. Use the src value in <img src="..."> in email template HTML, or pass it to nevent_delete_image to remove it.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

nevent_delete_image

Permanently delete one or more images from the Nevent media library. Provide the CDN URLs (src / destinationUrl) from nevent_list_images or nevent_upload_image. The operation is irreversible. Any email template HTML that references the deleted URLs will show broken images. Requires FULL operation mode (NEVENT_OPERATION_MODE=FULL) and ADMIN, SUPERADMIN, or OWNER role.

Parameters1

urls

array

required

Array of CDN image URLs to delete. Use the src/destinationUrl values from nevent_list_images or nevent_upload_image. Minimum 1 URL required. The operation is permanent. Example: ["https://cdn.nevent.es/resources/tenant123/banner.png"].

Raw schema

{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "description": "Array of CDN image URLs to delete. Use the src/destinationUrl values from nevent_list_images or nevent_upload_image. Minimum 1 URL required. The operation is permanent. Example: [\"https://cdn.nevent.es/resources/tenant123/banner.png\"]."
    }
  },
  "required": [
    "urls"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md6 KBView on GitHub

Nevent MCP

Talk to your live-events CRM (campaigns, analytics, paid ads, segments, short URLs) in Claude and ChatGPT.

smithery badge

Official MCP server for Nevent — the marketing platform for live event promoters. 59 tools across 10 groups (analytics, segmentation, campaigns, templates, deliverability, paid media, short URLs, media library, multi-tenant, and help/discovery) over OAuth 2.1 (hosted) or stdio (local).

📚 Full documentation: https://help.nevent.ai/en/nevent-ai/

Install

Hosted (recommended — no install needed)

Add https://mcp.nevent.ai/ as a remote MCP server in your client. Works with Claude.ai, ChatGPT, Cursor, Cline, Continue and any compatible MCP client.

→ Step-by-step with screenshots: Connect with Claude · Connect with ChatGPT

Local (stdio via npm)

bash

npx mcp-nevent

Required env: NEVENT_JWT_TOKEN. Optional: NEVENT_OPERATION_MODE (READ_ONLY | STANDARD | FULL).

→ Full local setup: Local installation

Quick add

Claude.ai · ChatGPT (hosted, no setup)

Settings → Integrations / Connectors → Add custom MCP → URL https://mcp.nevent.ai/. Authorize with your Nevent admin account.

Claude Code

bash

# Hosted (OAuth)
claude mcp add --transport http nevent https://mcp.nevent.ai/

# Or local (stdio)
claude mcp add nevent -- node /path/to/mcp-nevent/dist/index.js
export NEVENT_JWT_TOKEN=your_token

→ Full guide: Claude Code

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

json

{
  "mcpServers": {
    "nevent": {
      "command": "node",
      "args": ["/path/to/mcp-nevent/dist/index.js"],
      "env": {
        "NEVENT_JWT_TOKEN": "your_nevent_jwt_token"
      }
    }
  }
}

→ Full guide: Claude Desktop

Cursor · Cline · Continue · VS Code

→ Per-client setup: Cursor, Cline, Continue, VS Code

What you can ask

code

"Show me registrations for EventX broken down by ticket type"

"Which campaigns sent last month had an open rate above 30%?"

"Create a segment of attendees who bought a VIP ticket in 2025
 but haven't opened any email in the last 90 days"

"Schedule the 'Summer Gala' campaign for next Monday at 10:00 CET"

"Compare ROAS across our Meta ad campaigns for March"

"Create per-user tracking links for the Summer Gala campaign
 and show me which users clicked"

→ More patterns: Ready-to-use prompts · Use cases

Documentation

Topic	Link
What Nevent AI is and how it works	https://help.nevent.ai/en/nevent-ai/
Capabilities by area (analytics, campaigns, audience, paid media…)	https://help.nevent.ai/en/nevent-ai/what-you-can-do/
End-to-end use cases	https://help.nevent.ai/en/nevent-ai/use-cases/
Permissions and security	https://help.nevent.ai/en/nevent-ai/permissions-and-security/
FAQ	https://help.nevent.ai/en/nevent-ai/faq/

For developers

Topic	Link
Overview, transports and architecture	https://help.nevent.ai/en/nevent-ai/developers/
Local installation and env vars	https://help.nevent.ai/en/nevent-ai/developers/local-installation/
Multi-tenant model	https://help.nevent.ai/en/nevent-ai/developers/multi-tenant/
Reference of all 59 tools	https://help.nevent.ai/en/nevent-ai/developers/tools/
Troubleshooting and error codes	https://help.nevent.ai/en/nevent-ai/developers/troubleshooting/

How it works

code

LLM (Claude / ChatGPT / Cursor / …)
        |
        | MCP (Streamable HTTP or stdio)
        v
  ┌─────────────────┐
  │  Nevent MCP     │  mcp.nevent.ai (hosted) or local
  └─────────────────┘
        |
        | REST + JWT
        v
  Nevent APIs (analytics, campaigns, segments, paid media, short URLs)

Hosted mode uses OAuth 2.1: the MCP server issues short-lived JWT tokens after validating your Nevent credentials. Each session is isolated — no shared service accounts.

Privacy

The Nevent MCP server processes tenant data on Nevent's own infrastructure (AWS, eu-west-1). Data does not leave Nevent's infrastructure and is not used for model training.

For details on data collection, retention, third-party sharing, and contact information, see the full privacy policy: https://nevent.ai/en/privacy/

Security disclosure: see SECURITY.md.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md.

License

MIT © Nevent

Support

Help Center: https://help.nevent.ai
Issues: https://github.com/nevent-dev/mcp-nevent/issues
Email: support@nevent.ai
Product: https://nevent.ai/en

Install

Tools (59)

nevent_analytics_querynevent_analytics_capabilitiesnevent_analytics_table_schemanevent_analytics_filter_valuesnevent_campaign_reportnevent_segmentation_criterianevent_segment_previewnevent_segment_execute

Configuration

Environment variables

NEVENT_JWT_TOKENrequiredsecret

Nevent JWT access token for authenticating with the Nevent API

NEVENT_OPERATION_MODEdefault READ_ONLY

Tool operation mode: READ_ONLY (default), STANDARD, or FULL

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-nevent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-nevent@1.8.0"
      ],
      "env": {
        "NEVENT_JWT_TOKEN": "<YOUR_NEVENT_JWT_TOKEN>",
        "NEVENT_OPERATION_MODE": "READ_ONLY"
      }
    }
  }
}