@sendinel/mcp-server 1.0.50 → 1.0.52

package/build/lib/action-approvals.js

@@ -192,10 +192,11 @@ export function buildApprovalSummary(action, params, display = {}) {
             const count = typeof display.campaign_count === 'number' ? display.campaign_count : p.campaign_ids?.length ?? 0;
             const emails = typeof display.email_count === 'number' ? ` (${display.email_count} email${display.email_count === 1 ? '' : 's'})` : '';
             const names = display.campaign_names ? `: ${display.campaign_names}` : '';
-            return `Activate ${count} campaign${count === 1 ? '' : 's'}${emails}${names} — each emails contacts when its trigger fires`;
+            const warnings = display.content_warnings ? ` — Check before approving: ${display.content_warnings}` : '';
+            return `Activate ${count} campaign${count === 1 ? '' : 's'}${emails}${names} — each emails contacts when its trigger fires${warnings}`;
         },
         update_campaign_status: (p) => (p.status === 'active'
-            ? `Activate campaign "${display.campaign_name ?? p.campaign_id}"${typeof display.enrolled === 'number' ? ` — sends email to ${display.enrolled.toLocaleString('en-US')} enrolled contact${display.enrolled === 1 ? '' : 's'}` : ' — will send emails to real contacts'}${display.trigger ? ` and to new contacts on "${display.trigger}"` : ''}`
+            ? `Activate campaign "${display.campaign_name ?? p.campaign_id}"${typeof display.enrolled === 'number' ? ` — sends email to ${display.enrolled.toLocaleString('en-US')} enrolled contact${display.enrolled === 1 ? '' : 's'}` : ' — will send emails to real contacts'}${display.trigger ? ` and to new contacts on "${display.trigger}"` : ''}${display.content_warnings ? ` — Check before approving: ${display.content_warnings}` : ''}`
             : `Change campaign "${display.campaign_name ?? p.campaign_id}" to ${p.status}`),
         rotate_custom_webhook_secret: (p) => `Rotate custom webhook ${p.connection_id} signing secret — immediately invalidates the previous secret with no grace period`,
         create_campaign_with_content: (p) => `Create + activate campaign "${p.name}" with ${p.steps?.length ?? 0} email(s) and enroll contacts`,

package/build/lib/content-sources.d.ts

@@ -0,0 +1,62 @@
+import { type ContentIssue } from '@sendinel/domain';
+/** Data keys seen on an event in the project's history, or null when the lookup failed. */
+export declare function eventKeysFromHistory(projectId: string, eventName: string): Promise<string[] | null>;
+/**
+ * Contact property keys the project's contacts actually have, from the most recent contacts.
+ * complete is true only when every contact was read. Null when the lookup failed.
+ */
+export declare function contactPropertyKeys(projectId: string): Promise<{
+    keys: string[];
+    complete: boolean;
+    checked: number;
+} | null>;
+type ContentStep = {
+    campaign_id: string;
+    step_order: number;
+    subject: string | null;
+    body_html: string | null;
+    body_text: string | null;
+};
+type ContentCampaign = {
+    id: string;
+    name: string;
+    site_id: string | null;
+    trigger_event_name: string | null;
+};
+export type CampaignContentFinding = ContentIssue & {
+    campaign: string;
+    email: number;
+};
+/**
+ * Looks for placeholder text, links to the sending domain and merge tags with no data source in
+ * every email of the given campaigns (#3853). Placeholder text and sending-domain links are
+ * blocking; merge-tag findings are warnings. A failed lookup is reported as a warning, never as a pass.
+ */
+export declare function checkCampaignContent(projectId: string, campaigns: ContentCampaign[], steps: ContentStep[]): Promise<{
+    blocking: CampaignContentFinding[];
+    warnings: CampaignContentFinding[];
+    lookup_errors: string[];
+}>;
+/** The refusal for emails with placeholder text or a link to the sending domain (#3853). */
+export declare function contentNotReadyResponse(blocking: CampaignContentFinding[]): {
+    error: string;
+    code: string;
+    emails: {
+        campaign: string;
+        email: number;
+        kind: import("@sendinel/domain").ContentIssueKind;
+        problem: string;
+        excerpt: string;
+    }[];
+};
+export declare function contentWarningView(warnings: CampaignContentFinding[], lookupErrors: string[]): {
+    kind: string;
+    warning: string;
+}[];
+/** One line for the approval card: how many warnings and the first few. */
+export declare function summarizeContentWarnings(warnings: Array<{
+    campaign?: string;
+    email?: number;
+    warning: string;
+}>): string;
+export {};

package/build/lib/content-sources.js

@@ -0,0 +1,111 @@
+import { BLOCKING_CONTENT_ISSUE_KINDS, findContentIssues, sendingHostOf } from '@sendinel/domain';
+import { db } from '../db.js';
+/** Data keys seen on an event in the project's history, or null when the lookup failed. */
+export async function eventKeysFromHistory(projectId, eventName) {
+    const { data, error } = await db()
+        .from('contact_events')
+        .select('metadata')
+        .eq('project_id', projectId)
+        .eq('title', eventName)
+        .order('created_at', { ascending: false })
+        .limit(200);
+    if (error)
+        return null;
+    const keys = new Set();
+    for (const row of (data ?? [])) {
+        if (row.metadata && typeof row.metadata === 'object' && !Array.isArray(row.metadata))
+            for (const key of Object.keys(row.metadata))
+                keys.add(key);
+    }
+    return Array.from(keys);
+}
+const CONTACT_SAMPLE = 1000;
+/**
+ * Contact property keys the project's contacts actually have, from the most recent contacts.
+ * complete is true only when every contact was read. Null when the lookup failed.
+ */
+export async function contactPropertyKeys(projectId) {
+    const { data, count, error } = await db()
+        .from('subscribers')
+        .select('custom_properties', { count: 'exact' })
+        .eq('project_id', projectId)
+        .order('created_at', { ascending: false })
+        .limit(CONTACT_SAMPLE);
+    if (error)
+        return null;
+    const keys = new Set();
+    for (const row of (data ?? [])) {
+        const props = row.custom_properties;
+        if (props && typeof props === 'object' && !Array.isArray(props)) {
+            for (const [key, value] of Object.entries(props))
+                if (value !== null && value !== undefined && value !== '')
+                    keys.add(key);
+        }
+    }
+    const checked = (data ?? []).length;
+    return { keys: Array.from(keys), complete: typeof count === 'number' && count <= checked, checked };
+}
+/**
+ * Looks for placeholder text, links to the sending domain and merge tags with no data source in
+ * every email of the given campaigns (#3853). Placeholder text and sending-domain links are
+ * blocking; merge-tag findings are warnings. A failed lookup is reported as a warning, never as a pass.
+ */
+export async function checkCampaignContent(projectId, campaigns, steps) {
+    const lookupErrors = [];
+    const sendingHostsBySite = new Map();
+    const allHosts = new Set();
+    const { data: sites, error: sitesErr } = await db().from('sites').select('id, sending_domain, from_email').eq('project_id', projectId);
+    if (sitesErr)
+        lookupErrors.push(`Could not read your sending domains, so links were not checked against them: ${sitesErr.message}`);
+    for (const site of (sites ?? [])) {
+        const hosts = [sendingHostOf(site.sending_domain), sendingHostOf(site.from_email)].filter((h) => Boolean(h));
+        sendingHostsBySite.set(site.id, hosts);
+        for (const host of hosts)
+            allHosts.add(host);
+    }
+    const contactProps = await contactPropertyKeys(projectId);
+    if (contactProps === null)
+        lookupErrors.push('Could not read your contacts, so merge tags that use contact properties were not confirmed.');
+    const eventKeys = new Map();
+    for (const eventName of new Set(campaigns.map((c) => c.trigger_event_name).filter((e) => Boolean(e)))) {
+        const keys = await eventKeysFromHistory(projectId, eventName);
+        eventKeys.set(eventName, keys);
+        if (keys === null)
+            lookupErrors.push(`Could not read the event history for "${eventName}", so its merge tags were not confirmed.`);
+    }
+    const blocking = [];
+    const warnings = [];
+    for (const campaign of campaigns) {
+        const events = campaign.trigger_event_name ? eventKeys.get(campaign.trigger_event_name) : [];
+        const sourcedKeys = contactProps === null || events === null || events === undefined
+            ? null
+            : [...events, ...contactProps.keys.map((key) => `custom.${key}`)];
+        const hosts = (campaign.site_id ? sendingHostsBySite.get(campaign.site_id) : undefined) ?? [...allHosts];
+        for (const step of steps.filter((s) => s.campaign_id === campaign.id)) {
+            for (const issue of findContentIssues(step, { sendingHosts: hosts, sourcedKeys })) {
+                const finding = { ...issue, campaign: campaign.name, email: step.step_order + 1 };
+                (BLOCKING_CONTENT_ISSUE_KINDS.has(issue.kind) ? blocking : warnings).push(finding);
+            }
+        }
+    }
+    return { blocking, warnings, lookup_errors: lookupErrors };
+}
+/** The refusal for emails with placeholder text or a link to the sending domain (#3853). */
+export function contentNotReadyResponse(blocking) {
+    return {
+        error: 'Some emails are not ready to send. Fix the text or links below, then try again.',
+        code: 'CONTENT_NOT_READY',
+        emails: blocking.map((f) => ({ campaign: f.campaign, email: f.email, kind: f.kind, problem: f.message, excerpt: f.excerpt })),
+    };
+}
+export function contentWarningView(warnings, lookupErrors) {
+    return [
+        ...warnings.map((f) => ({ campaign: f.campaign, email: f.email, kind: f.kind, warning: f.message })),
+        ...lookupErrors.map((message) => ({ kind: 'could_not_check', warning: message })),
+    ];
+}
+/** One line for the approval card: how many warnings and the first few. */
+export function summarizeContentWarnings(warnings) {
+    const first = warnings.slice(0, 3).map((w) => (w.campaign ? `${w.campaign}, email ${w.email}: ${w.warning}` : w.warning));
+    return `${warnings.length} warning${warnings.length === 1 ? '' : 's'}. ${first.join(' | ')}${warnings.length > 3 ? ` | and ${warnings.length - 3} more` : ''}`;
+}

package/build/tools/campaign-sets.js

@@ -10,6 +10,7 @@ import { generateEmailFromBrief } from '../lib/email-generation.js';
 import { fireWebhookEvent } from '../lib/webhook-events.js';
 import { logAudit } from '../audit.js';
 import { applyCampaignTargetingFields } from './campaigns.js';
+import { checkCampaignContent, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
 /**
  * Campaign sets (#3669): build a whole set of triggered campaigns as drafts in one call, then
  * activate the set behind one human approval. Built for Cyber Wingman's lifecycle emails
@@ -286,6 +287,10 @@ export function registerCampaignSetTools(server) {
             if (current.campaigns.length !== ids.length || campaignSetContentHash(current.campaigns, current.steps) !== stored.content_hash) {
                 return j({ error: 'A campaign or email changed (or was deleted) after approval. Nothing was activated. Request a new approval.', code: 'CONTENT_CHANGED_SINCE_APPROVAL' });
             }
+            // Same content gate as the request, so a bad email can't ride through on an old approval.
+            const readiness = await checkCampaignContent(projectId, current.campaigns, current.steps);
+            if (readiness.blocking.length)
+                return j(contentNotReadyResponse(readiness.blocking));
             const check = await checkApproval(approval_id, { consume: true, action: 'activate_campaigns', params: stored });
             if (!check.approved)
                 return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
@@ -349,6 +354,11 @@ export function registerCampaignSetTools(server) {
                 emails: waitNotSet.map((s) => ({ campaign: set.campaigns.find((c) => c.id === s.campaign_id)?.name ?? s.campaign_id, email: s.step_order + 1, subject: s.subject })),
             });
         }
+        // Placeholder text and links to the sending domain never go out (#3853). Merge tags with no data source are warnings.
+        const readiness = await checkCampaignContent(projectId, set.campaigns, set.steps);
+        if (readiness.blocking.length)
+            return j(contentNotReadyResponse(readiness.blocking));
+        const contentWarnings = contentWarningView(readiness.warnings, readiness.lookup_errors);
         const approvalParams = { campaign_ids: [...ids].sort(), content_hash: campaignSetContentHash(set.campaigns, set.steps) };
         const channelContext = currentChannelContext();
         const decision = assertChannelCanExecute('activate_campaigns', approvalParams, channelContext);
@@ -359,10 +369,12 @@ export function registerCampaignSetTools(server) {
             campaign_count: set.campaigns.length,
             email_count: set.steps.length,
             campaign_names: names.slice(0, 10).join(', ') + (names.length > 10 ? `, and ${names.length - 10} more` : ''),
+            ...(contentWarnings.length ? { content_warnings: summarizeContentWarnings(contentWarnings) } : {}),
         });
         return j({
             ...approval,
             campaigns: previewOf(set.campaigns, set.steps),
+            ...(contentWarnings.length ? { content_warnings: contentWarnings } : {}),
             next: 'Show the person the campaigns above and approve_url. After approval, call activate_campaigns with only approval_id.',
         });
     });

package/build/tools/campaigns.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { computeSendContentKey, NAME_FALLBACKS, ONE_SEND_MATCH_STATUSES, ONE_SEND_SENT_STATUSES, ONE_SEND_WINDOW_DAYS, normalizeTriggerConfig, renderTemplateString as renderTemplateVars, resolveBrandTokens, readAllRows, } from '@sendinel/domain';
+import { BLOCKING_CONTENT_ISSUE_KINDS, computeSendContentKey, findContentIssues, sendingHostOf, NAME_FALLBACKS, ONE_SEND_MATCH_STATUSES, ONE_SEND_SENT_STATUSES, ONE_SEND_WINDOW_DAYS, normalizeTriggerConfig, renderTemplateString as renderTemplateVars, resolveBrandTokens, readAllRows, } from '@sendinel/domain';
 // Subpath import, not the barrel above -- reply-actions.ts uses node:crypto,
 // and MCP-server-side that's fine (this never runs in an Edge Function), but
 // keeping it off the shared barrel avoids re-creating the Edge-Function
@@ -20,6 +20,7 @@ import { getScheduleWindowBounds, groupScheduleByCampaign, parseFutureDate } fro
 import { sendEmailForSite } from '../lib/email-provider.js';
 import { resolveSurveyShortLink } from '../lib/survey-link-resolver.js';
 import { logAudit } from '../audit.js';
+import { checkCampaignContent, contactPropertyKeys, eventKeysFromHistory, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
 import { recordBrandAssetUsage } from '../lib/brand-asset-usage.js';
 import { BLOCK_GENERATION_SCHEMA, blocksToHtml, blocksToText, normalizeComposerBlocks } from '../lib/composer-blocks.js';
 import { callSendinelV1 } from '../lib/v1-client.js';
@@ -714,8 +715,9 @@ export function registerCampaignTools(server) {
             variant_label: z.string().optional().default('A').describe('Variant label for A/B testing (default: A). Use B, C, etc. for additional variants.'),
             survey_id: z.string().uuid().optional(),
             brand_asset_ids: z.array(z.string().uuid()).optional().describe('Stable brand_media_assets ids explicitly referenced by this step.'),
+            skip_if_event: z.string().trim().min(1).optional().describe('Skip this step at send time if the contact already has an event with this name; the journey continues.'),
         },
-    }, async ({ campaign_id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, variant_label, survey_id, brand_asset_ids }) => {
+    }, async ({ campaign_id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, variant_label, survey_id, brand_asset_ids, skip_if_event }) => {
         const renderVars = {};
         if (survey_id) {
             const surveyLink = await resolveSurveyShortLink(db(), getProjectId(), survey_id);
@@ -730,7 +732,7 @@ export function registerCampaignTools(server) {
         const renderedText = body_text !== undefined && survey_id ? renderTemplateVars(body_text, renderVars) : body_text;
         const { data, error } = await db()
             .from('campaign_steps')
-            .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A' })
+            .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null })
             .select()
             .single();
         if (error)
@@ -780,6 +782,28 @@ export function registerCampaignTools(server) {
                     emails: unsetSteps.map((s) => ({ email: s.step_order + 1, subject: s.subject })),
                 });
             }
+            // Placeholder text and links to the sending domain never go out (#3853).
+            const { data: campRow, error: campErr } = await db()
+                .from('campaigns')
+                .select('id, name, site_id, trigger_event_name')
+                .eq('id', campaign_id)
+                .eq('project_id', getProjectId())
+                .maybeSingle();
+            if (campErr)
+                return j({ error: `Could not check the campaign: ${campErr.message}`, code: 'CAMPAIGN_LOOKUP_FAILED' });
+            let contentWarnings = [];
+            if (campRow) {
+                const { data: contentSteps, error: contentErr } = await db()
+                    .from('campaign_steps')
+                    .select('campaign_id, step_order, subject, body_html, body_text')
+                    .eq('campaign_id', campaign_id);
+                if (contentErr)
+                    return j({ error: `Could not check the campaign's emails: ${contentErr.message}`, code: 'STEP_LOOKUP_FAILED' });
+                const readiness = await checkCampaignContent(getProjectId(), [campRow], contentSteps ?? []);
+                if (readiness.blocking.length)
+                    return j(contentNotReadyResponse(readiness.blocking));
+                contentWarnings = contentWarningView(readiness.warnings, readiness.lookup_errors);
+            }
             const approvalParams = { campaign_id, status };
             if (!approval_id) {
                 const channelContext = currentChannelContext();
@@ -797,8 +821,9 @@ export function registerCampaignTools(server) {
                         campaign_name: camp?.name ?? null,
                         enrolled: typeof camp?.total_enrolled === 'number' ? camp.total_enrolled : null,
                         trigger: camp?.trigger_event_name ?? (camp?.trigger_tag ? `tag ${camp.trigger_tag}` : null),
+                        ...(contentWarnings.length ? { content_warnings: summarizeContentWarnings(contentWarnings) } : {}),
                     });
-                    return j(approval);
+                    return j(contentWarnings.length ? { ...approval, content_warnings: contentWarnings } : approval);
                 }
             }
             else {
@@ -2733,25 +2758,57 @@ Do not include body_html in your response; Sendinel renders body_html from block
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Validate an email template for variable errors and brand voice compliance. Checks for unknown {{variables}}, stock phrases, excessive CTAs, missing sign-off, and more.',
+        description: 'Validate an email template for variable errors and brand voice compliance. Checks for unknown {{variables}}, merge tags with no fallback, placeholder text left from an import ("Not specified in source material"), links to your sending domain, stock phrases, excessive CTAs, and a missing sign-off (only when your brand kit or site sets one). Pass trigger_event_name or event_keys to also check that each merge tag has data behind it.',
         inputSchema: {
             html: z.string().describe('HTML email content to validate'),
             site_id: z.string().uuid().optional().describe('Site UUID — uses the site brand voice config for sign-off check'),
             custom_variables: z.array(z.string()).optional().describe('Variable names (without braces) this template legitimately uses beyond the fixed known set.'),
+            subject: z.string().optional().describe('Subject line, checked for placeholder text and merge tags.'),
+            body_text: z.string().optional().describe('Plain text version, checked for placeholder text and links.'),
+            trigger_event_name: z.string().min(1).optional().describe('Event that starts the campaign. Its past data keys and your contact properties are used to check merge tags.'),
+            event_keys: z.array(z.string()).optional().describe('Data keys the trigger event sends. Merge tags not in this list, your contact properties or the built-in set are flagged.'),
         },
-    }, async ({ html, site_id, custom_variables }) => {
+    }, async ({ html, site_id, custom_variables, subject, body_text, trigger_event_name, event_keys }) => {
+        const projectId = getProjectId();
         let voiceConfig = null;
         if (site_id) {
             const { data: site } = await db()
                 .from('sites')
                 .select('brand_voice')
                 .eq('id', site_id)
-                .eq('project_id', getProjectId())
+                .eq('project_id', projectId)
                 .maybeSingle();
             voiceConfig = site?.brand_voice ?? null;
         }
-        const result = validateTemplate(html, voiceConfig, { customVariables: custom_variables });
-        return j(result);
+        // The brand kit's sign-off name applies to every site in the project (#3854).
+        const { data: projectRow } = await db().from('projects').select('brand_settings').eq('id', projectId).maybeSingle();
+        // #3853: placeholder text, links to the sending domain, merge tags with no data source.
+        const { data: siteRows } = await db().from('sites').select('id, sending_domain, from_email').eq('project_id', projectId);
+        const sendingHosts = (siteRows ?? [])
+            .filter((row) => !site_id || row.id === site_id)
+            .flatMap((row) => [sendingHostOf(row.sending_domain), sendingHostOf(row.from_email)])
+            .filter((host) => Boolean(host));
+        let sourcedKeys;
+        if (trigger_event_name || event_keys) {
+            const fromHistory = trigger_event_name ? await eventKeysFromHistory(projectId, trigger_event_name) : [];
+            const contacts = await contactPropertyKeys(projectId);
+            sourcedKeys = fromHistory === null || contacts === null
+                ? null
+                : [...(event_keys ?? []), ...fromHistory, ...contacts.keys.map((key) => `custom.${key}`)];
+        }
+        const result = validateTemplate(html, voiceConfig, {
+            customVariables: [...(custom_variables ?? []), ...(sourcedKeys ?? [])],
+            subject,
+            bodyText: body_text,
+            brandSettings: projectRow?.brand_settings ?? null,
+        });
+        for (const issue of findContentIssues({ subject, body_html: html, body_text }, { sendingHosts, sourcedKeys })) {
+            if (BLOCKING_CONTENT_ISSUE_KINDS.has(issue.kind))
+                result.errors.push(`${issue.message} (${issue.excerpt})`);
+            else if (!result.errors.some((error) => error.includes(issue.excerpt)))
+                result.warnings.push(issue.message);
+        }
+        return j({ ...result, valid: result.errors.length === 0 });
     });
     server.registerTool('check_content_consistency', {
         title: 'Check Content Consistency',
@@ -3039,7 +3096,7 @@ Return ONLY valid JSON with this exact shape:
             return j({ error: campaignErr?.message ?? 'Campaign not found', code: 'NOT_FOUND' });
         const { data, error } = await db()
             .from('campaign_steps')
-            .select('id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, created_at, updated_at')
+            .select('id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, skip_if_event, created_at, updated_at')
             .eq('campaign_id', campaign_id)
             .order('step_order', { ascending: true });
         if (error)
@@ -3065,6 +3122,7 @@ Return ONLY valid JSON with this exact shape:
             delay_hours: z.number().int().min(0).optional(),
             step_order: z.number().int().min(0).optional(),
             survey_id: z.string().uuid().optional(),
+            skip_if_event: z.string().trim().min(1).nullable().optional().describe('Event name that skips this step at send time; null clears the rule.'),
         },
     }, async ({ step_id, ...updates }) => {
         const projectId = getProjectId();
@@ -3105,7 +3163,7 @@ Return ONLY valid JSON with this exact shape:
             .from('campaign_steps')
             .update({ ...renderedUpdates, updated_at: new Date().toISOString() })
             .eq('id', step_id)
-            .select('id, step_order, subject, delay_days, delay_hours, updated_at')
+            .select('id, step_order, subject, delay_days, delay_hours, skip_if_event, updated_at')
             .single();
         if (error)
             return j({ error: error.message });

package/build/tools/contacts.js

@@ -1359,30 +1359,67 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Recent email sends with status, filterable by site and/or recipient',
+        description: 'See sent emails and their delivery status: the email history for your project, one row per message with recipient, subject, send time, status (sent, delivered, opened, clicked, bounced, complained, failed) and where it came from (source: campaign or transactional). Filter by recipient email, subject words, campaign, site, status, and a sent-between date range (sent_after / sent_before, ISO dates; a date alone covers the whole day, UTC). Newest first. Page past 200 with offset: when a filter or offset is used the answer is { emails, has_more, next_offset }; with no filters it is the plain list.',
         inputSchema: {
             site_id: z.string().uuid().optional(),
-            contact_email: z.string().optional(),
-            status: z.enum(['sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained', 'failed']).optional(),
+            contact_email: z.string().optional().describe('Exact recipient email address.'),
+            status: z.enum(['queued', 'sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained', 'unsubscribed', 'failed']).optional(),
+            sent_after: z.string().optional().describe('Only emails sent at or after this time. ISO 8601; a bare date like 2026-10-15 starts at 00:00 UTC.'),
+            sent_before: z.string().optional().describe('Only emails sent at or before this time. ISO 8601; a bare date like 2026-10-15 covers that whole day (UTC).'),
+            campaign_id: z.string().uuid().optional().describe('Only emails sent by this campaign.'),
+            subject_contains: z.string().min(1).max(200).optional().describe('Only emails whose subject contains these words (not case sensitive).'),
+            offset: z.number().int().min(0).max(100000).optional().describe('How many rows to skip, to page past the first 200. Use next_offset from the last answer.'),
             limit: z.number().int().min(1).max(200).optional().default(50),
         },
-    }, async ({ site_id, contact_email, status, limit }) => {
+    }, async ({ site_id, contact_email, status, sent_after, sent_before, campaign_id, subject_contains, offset, limit }) => {
+        const parseBound = (raw, edge) => {
+            const value = /^\d{4}-\d{2}-\d{2}$/.test(raw) ? `${raw}${edge === 'start' ? 'T00:00:00.000Z' : 'T23:59:59.999Z'}` : raw;
+            const date = new Date(value);
+            return Number.isNaN(date.getTime()) ? null : date.toISOString();
+        };
+        const after = sent_after === undefined ? undefined : parseBound(sent_after, 'start');
+        const before = sent_before === undefined ? undefined : parseBound(sent_before, 'end');
+        if (after === null)
+            return { content: [{ type: 'text', text: JSON.stringify({ error: `sent_after is not a date: ${sent_after}. Use ISO 8601, e.g. 2026-10-15.`, code: 'BAD_REQUEST' }, null, 2) }] };
+        if (before === null)
+            return { content: [{ type: 'text', text: JSON.stringify({ error: `sent_before is not a date: ${sent_before}. Use ISO 8601, e.g. 2026-10-15.`, code: 'BAD_REQUEST' }, null, 2) }] };
+        const pageSize = limit ?? 50;
+        const start = offset ?? 0;
+        const paged = offset !== undefined || after !== undefined || before !== undefined || campaign_id !== undefined || subject_contains !== undefined;
+        // Fetch one extra row to know whether another page exists.
         let q = db()
             .from('email_log')
-            .select('id, to_email, subject, status, sent_at, opened_at, clicked_at, bounced_at, site_id, campaign_id')
+            .select('id, to_email, from_email, subject, status, category, sent_at, delivered_at, opened_at, clicked_at, bounced_at, bounce_type, complained_at, error_message, site_id, campaign_id, created_at')
             .eq('project_id', getProjectId())
             .order('sent_at', { ascending: false })
-            .limit(limit ?? 50);
+            .order('id', { ascending: false })
+            .range(start, start + pageSize);
         if (site_id)
             q = q.eq('site_id', site_id);
         if (status)
             q = q.eq('status', status);
         if (contact_email)
             q = q.eq('to_email', contact_email);
+        if (campaign_id)
+            q = q.eq('campaign_id', campaign_id);
+        if (after)
+            q = q.gte('sent_at', after);
+        if (before)
+            q = q.lte('sent_at', before);
+        if (subject_contains)
+            q = q.ilike('subject', `%${subject_contains.replace(/[\\%_]/g, (c) => `\\${c}`)}%`);
         const { data, error } = await q;
         if (error)
             return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        const fetched = (data ?? []);
+        const hasMore = fetched.length > pageSize;
+        // source: where the email came from. A campaign id wins; otherwise the stored category (transactional, test, marketing).
+        const rows = fetched.slice(0, pageSize).map((row) => ({
+            ...row,
+            source: row.campaign_id ? 'campaign' : (row.category === 'transactional' ? 'transactional' : (row.category ?? 'other')),
+        }));
+        const body = paged ? { emails: rows, has_more: hasMore, next_offset: hasMore ? start + pageSize : null } : rows;
+        return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     });
     server.registerTool('list_suppressions', {
         title: 'List Suppressions',

package/build/tools/convert-imported.js

@@ -5,6 +5,7 @@ import { getProjectId } from '../project.js';
 import { checkPlanLimit } from '../plan-limits.js';
 import { validateTemplate } from '../lib/voice.js';
 import { logAudit } from '../audit.js';
+import { eventKeysFromHistory, contactPropertyKeys } from '../lib/content-sources.js';
 import { loadSet, previewOf, writeCampaignDrafts } from './campaign-sets.js';
 /**
  * convert_imported_campaigns (#3689): turns campaigns imported from another platform (Customer.io
@@ -30,51 +31,6 @@ const Conversion = z.object({
     event_keys: z.array(z.string()).optional().describe('Data keys the trigger event sends. Used to catch placeholders that would come out blank.'),
     send_class: z.enum(['broadcast', 'product']).optional().describe('product for account, trial and onboarding email; broadcast for marketing.'),
 });
-/** Data keys seen on an event in the project's history, or null when the lookup failed. */
-async function eventKeysFromHistory(projectId, eventName) {
-    const { data, error } = await db()
-        .from('contact_events')
-        .select('metadata')
-        .eq('project_id', projectId)
-        .eq('title', eventName)
-        .order('created_at', { ascending: false })
-        .limit(200);
-    if (error)
-        return null;
-    const keys = new Set();
-    for (const row of (data ?? [])) {
-        if (row.metadata && typeof row.metadata === 'object' && !Array.isArray(row.metadata))
-            for (const key of Object.keys(row.metadata))
-                keys.add(key);
-    }
-    return Array.from(keys);
-}
-const CONTACT_SAMPLE = 1000;
-/**
- * Contact property keys the project's contacts actually have, from the most recent contacts.
- * complete is true only when every contact was read. Null when the lookup failed.
- */
-async function contactPropertyKeys(projectId) {
-    const { data, count, error } = await db()
-        .from('subscribers')
-        .select('custom_properties', { count: 'exact' })
-        .eq('project_id', projectId)
-        .order('created_at', { ascending: false })
-        .limit(CONTACT_SAMPLE);
-    if (error)
-        return null;
-    const keys = new Set();
-    for (const row of (data ?? [])) {
-        const props = row.custom_properties;
-        if (props && typeof props === 'object' && !Array.isArray(props)) {
-            for (const [key, value] of Object.entries(props))
-                if (value !== null && value !== undefined && value !== '')
-                    keys.add(key);
-        }
-    }
-    const checked = (data ?? []).length;
-    return { keys: Array.from(keys), complete: typeof count === 'number' && count <= checked, checked };
-}
 function reviewView(plan) {
     return {
         source: { campaign_id: plan.source_campaign_id, name: plan.source_name },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.50",
+  "version": "1.0.52",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",