Nevent MCP

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.

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

Query event marketing analytics. Supports dimensions, metrics, time ranges, and filters across campaigns, purchases, fans (user_tenants), 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 "eq" (or "neq") with the boolean value true or false; "is_true"/"is_false" are segmentation operators and analytics rejects them. (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.

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

Generate the monthly campaign report of the current brand for a calendar month (year + month). Executes 13 parallel queries in one call: marketing campaign metrics for that month and the previous one, ROI and attribution, revenue, variable costs, 24-month purchase history, transactional campaigns, segments and industry benchmarks. For a single campaign use nevent_get_campaign_insights.

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.

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).

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.

Create and persist a new audience segment from a filter definition. SEMANTICS: criteria in the same stanza are OR-combined — a fan matches the stanza if ANY criterion matches. Stanzas are AND-combined — a fan must match EVERY stanza. To require A AND B, put them in separate stanzas; to accept A OR B, put both in the same stanza. 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. Separate stanzas are AND-combined, so a fan must match both. After creation, call nevent_segment_preview to count the audience, then nevent_create_campaign to send to this segment.

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.

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.

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.

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

Where the ticket sales of ONE event come from (nev-data-api, analytics warehouse). Pick the event with nevent_list_events (TICKETED events), then choose a view. summary (default): sales grouped by dimension — provider, distribution channel, purchase channel, promo code or marketing (UTM source > medium > campaign; drill down with level + parent, copying the group key from the previous response); returns the top groups and an «Otros» bucket. daily: day-by-day series stacked by one dimension (provider | distribution | purchaseChannel | promoCode). campaigns: sales attributed to Nevent campaigns through tracking links. overview: totals, coverage and freshness of each block — read it first to know how much of the data carries provenance. from and to (YYYY-MM-DD, purchase days in tz, default Europe/Madrid) are required. Currencies are never added together: omit currency for one block per currency, or pass EUR. population defaults to SETTLED_SALES (settled sales); ALL_REPORTED includes refunded purchases and is NOT collected revenue. Amounts are the gross reported by the source, never net. Provenance fields can be missing: coverage and «unknown» buckets are part of the answer, do not present them as zero or as organic. The data is a warehouse (lags the sale by the pipeline); the view reports its freshness. Scoped to the active tenant and its descendants by the session JWT.

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.

Email deliverability of ONE campaign (nev-api, the "Entregabilidad" tab of the campaign). view=summary (default): sent, delivered, soft bounces, hard bounces and complaints, plus a warning when something is off. view=bounce_reasons: why messages bounced, grouped by SES bounce subtype; needs bounce_type=soft|hard (call it once per family). view=segment_breakdown: delivery, soft and hard bounces per segment; empty when the campaign targeted a single segment or has no segment attribution. Use it after a send when nevent_get_campaign_metrics shows a high bounce rate, to learn whether the cause is invalid addresses (hard) or mailbox/transient problems (soft). Email campaigns only. For tenant-wide sender health use nevent_get_sending_profile and nevent_get_suppressions_summary instead; for the people behind the bounces use nevent_list_campaign_recipients(status=BOUNCES). Requires ADMIN, OWNER or SUPERADMIN.

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.

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).

Unsubscribes and spam complaints of ONE campaign (nev-api). view=summary (default): number of unsubscribes, unsubscribe rate, spam complaints and complaint rate. view=reasons: the reasons people gave when unsubscribing, grouped into canonical buckets. view=segment_breakdown: unsubscribes and complaints per segment; empty when the campaign targeted a single segment or has no segment attribution. Use it to explain a spike in nevent_get_campaign_metrics.unsubscribes or to compare how audiences reacted. Complaint rates above roughly 0.1% put sender reputation at risk: pair a high value with nevent_get_campaign_deliverability. Email campaigns only. For tenant-wide totals use nevent_get_suppressions_summary. Requires ADMIN, OWNER or SUPERADMIN.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

List the events of the active tenant, one page at a time (nev-api GET /events). Use it to find an event ID before reading its sales with nevent_event_sales_provenance, or to look an event up by name. By default it returns upcoming events ordered by start date; pass future=false for past events, search for text on the name, nature=TICKETED for events with ticket sales, active_only=true to hide inactive ones. Returns { events, page, page_size, totalElements, totalPages }: each event carries id, name, state, active, url, startDate, endDate, ticketsSold, ticketsAvailable, ticketsNumber, location, tenantId and tenantName. Zones, ticket types and experiences are left out to keep the response small. Always paginated (default 25 per page, max 100): request the next page with page+1 while page+1 < totalPages. Scoped to the active tenant by the session JWT; use nevent_switch_tenant to change it.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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).

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.

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.

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.

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.