/**
* Instantly MCP Server - Campaign Service
*
* Business logic and helper functions for campaign management.
*/
import { getAllAccounts, getEligibleSenderAccounts } from './account-service.js';
import { DEFAULT_TIMEZONE } from '../timezone-config.js';
/**
* Gather campaign prerequisites and validate requirements
*
* This function analyzes the current state of accounts and campaign parameters
* to provide comprehensive guidance for campaign creation.
*
* @param args - Campaign creation arguments
* @param apiKey - Instantly.ai API key
* @returns Prerequisite analysis and guidance
*/
export async function gatherCampaignPrerequisites(args: any, apiKey?: string): Promise<any> {
console.error('[Instantly MCP] 🔍 Gathering campaign prerequisites...');
// Step 1: Fetch and analyze available accounts
let accounts: any[] = [];
let eligibleAccounts: any[] = [];
let accountAnalysis: any = {};
try {
const accountsResult = await getAllAccounts(apiKey);
// FIX: getAllAccounts returns { data: [...], metadata: {...} }, not an array directly
accounts = accountsResult.data || accountsResult;
if (!accounts || !Array.isArray(accounts) || accounts.length === 0) {
return {
stage: 'prerequisite_check',
status: 'no_accounts_found',
error: 'No accounts found in your workspace',
required_action: {
step: 1,
action: 'add_accounts',
description: 'You need to add at least one email account before creating campaigns',
instructions: [
'Go to your Instantly dashboard',
'Navigate to Accounts section',
'Add and verify email accounts',
'Complete warmup process for each account',
'Then retry campaign creation'
]
}
};
}
// Analyze account eligibility
eligibleAccounts = accounts.filter(account =>
account.status === 1 &&
!account.setup_pending &&
account.warmup_status === 1
);
const ineligibleAccounts = accounts.filter(account =>
account.status !== 1 ||
account.setup_pending ||
account.warmup_status !== 1
);
accountAnalysis = {
total_accounts: accounts.length,
eligible_accounts: eligibleAccounts.length,
ineligible_accounts: ineligibleAccounts.length,
eligible_emails: eligibleAccounts.map(acc => ({
email: acc.email,
warmup_score: acc.warmup_score || 0,
status: 'ready'
})),
ineligible_emails: ineligibleAccounts.map(acc => ({
email: acc.email,
issues: [
...(acc.status !== 1 ? ['Account not active'] : []),
...(acc.setup_pending ? ['Setup pending'] : []),
...(acc.warmup_status !== 1 ? ['Warmup not complete'] : [])
]
}))
};
} catch (error: any) {
return {
stage: 'prerequisite_check',
status: 'account_fetch_failed',
error: `Failed to fetch accounts: ${error.message}`,
suggestion: 'Please check your API key and try again, or call list_accounts directly to troubleshoot'
};
}
// Step 2: Analyze provided campaign data
const providedFields: Record<string, any> = {
name: args?.name || null,
subject: args?.subject || null,
body: args?.body || null,
email_list: args?.email_list || null,
campaign_schedule: args?.campaign_schedule || null,
sequences: args?.sequences || null
};
// Determine required fields based on campaign type
const hasComplexStructure = args?.campaign_schedule && args?.sequences;
const requiredFields = hasComplexStructure
? ['name', 'email_list'] // Complex campaigns only need name and email_list
: ['name', 'subject', 'body', 'email_list']; // Simple campaigns need all fields
const missingFields = requiredFields.filter(field => !providedFields[field]);
const hasAllRequired = missingFields.length === 0;
// Step 3: Validate email_list if provided
let emailValidation: any = null;
if (args?.email_list && Array.isArray(args.email_list)) {
const eligibleEmailSet = new Set(eligibleAccounts.map(acc => acc.email.toLowerCase()));
const invalidEmails = args.email_list.filter((email: string) =>
!eligibleEmailSet.has(email.toLowerCase())
);
emailValidation = {
provided_emails: args.email_list,
valid_emails: args.email_list.filter((email: string) =>
eligibleEmailSet.has(email.toLowerCase())
),
invalid_emails: invalidEmails,
validation_passed: invalidEmails.length === 0
};
}
// Step 4: Generate comprehensive guidance
const guidance = {
next_steps: [] as any[],
field_requirements: {
name: {
required: true,
description: 'Campaign name for identification',
example: 'Q4 Product Launch Campaign',
provided: !!args?.name
},
subject: {
required: true,
description: 'Email subject line',
example: 'Introducing our new product line',
formatting_tips: [
'Keep under 50 characters for better deliverability',
'Avoid spam trigger words',
'Use personalization: {{firstName}} or {{companyName}}'
],
provided: !!args?.subject
},
body: {
required: true,
description: 'Email body content',
formatting_requirements: [
'Use plain text with \\n for line breaks',
'Personalization variables: {{firstName}}, {{lastName}}, {{companyName}}',
'Only <p>, <br>, and <br/> HTML tags are allowed',
'Avoid escaped characters like \\" or \\t'
],
example: 'Hi {{firstName}},\\n\\nI hope this email finds you well.\\n\\nBest regards,\\nYour Name',
provided: !!args?.body
},
email_list: {
required: true,
description: 'Array of sender email addresses (must be from your verified accounts)',
constraint: 'Only one sender email per campaign creation call',
available_options: eligibleAccounts.map(acc => acc.email),
example: ['john@yourcompany.com'],
provided: !!args?.email_list,
validation_status: emailValidation
}
},
optional_settings: {
tracking: {
track_opens: {
default: false,
description: 'Track when recipients open emails (disabled by default)',
why_disabled: 'Email tracking can hurt deliverability and raises privacy concerns. Many email clients now block tracking pixels.'
},
track_clicks: {
default: false,
description: 'Track when recipients click links (disabled by default)',
why_disabled: 'Link tracking can trigger spam filters and reduces trust. Enable only if analytics are critical.'
}
},
scheduling: {
timezone: { default: DEFAULT_TIMEZONE, description: 'Timezone for sending schedule (verified working timezone)' },
timing_from: { default: '09:00', description: 'Start time for sending (24h format)' },
timing_to: { default: '17:00', description: 'End time for sending (24h format)' },
days: {
default: 'Monday-Friday',
description: 'Days of week for sending',
format: 'Object with boolean values for each day'
}
},
limits: {
daily_limit: {
default: 30,
description: 'Maximum emails per day per account (30 for cold email compliance)',
compliance_note: 'Higher limits may trigger spam filters and hurt deliverability. 30/day is the recommended maximum for cold outreach.'
},
email_gap: { default: 10, description: 'Minutes between emails from same account (1-1440 minutes)' }
}
}
};
// Add specific next steps based on current state
if (eligibleAccounts.length === 0) {
guidance.next_steps.push({
priority: 'critical',
action: 'fix_account_issues',
description: 'Resolve account eligibility issues before proceeding',
details: accountAnalysis.ineligible_emails
});
} else {
guidance.next_steps.push({
priority: 'recommended',
action: 'review_available_accounts',
description: `You have ${eligibleAccounts.length} eligible sending accounts available`,
accounts: accountAnalysis.eligible_emails
});
}
if (missingFields.length > 0) {
guidance.next_steps.push({
priority: 'required',
action: 'provide_missing_fields',
description: `Provide the following required fields: ${missingFields.join(', ')}`,
missing_fields: missingFields
});
}
if (emailValidation && !emailValidation.validation_passed) {
guidance.next_steps.push({
priority: 'critical',
action: 'fix_email_list',
description: 'Email list contains invalid addresses',
invalid_emails: emailValidation.invalid_emails,
suggestion: 'Use only emails from your eligible accounts listed above'
});
}
// Include comprehensive guidance for users
const fullGuidance = generateCampaignGuidance();
return {
stage: 'prerequisite_check',
status: hasAllRequired && eligibleAccounts.length > 0 && (!emailValidation || emailValidation.validation_passed)
? 'ready_for_creation'
: 'missing_requirements',
message: hasAllRequired
? 'All required fields provided. Ready to create campaign.'
: `Missing required information. Please provide: ${missingFields.join(', ')}`,
account_analysis: accountAnalysis,
field_analysis: providedFields,
validation_results: emailValidation,
step_by_step_guidance: guidance,
comprehensive_guide: fullGuidance,
ready_for_next_stage: hasAllRequired && eligibleAccounts.length > 0 && (!emailValidation || emailValidation.validation_passed)
};
}
/**
* Generate comprehensive campaign creation guidance
*
* @returns Detailed guidance object with best practices and examples
*/
export function generateCampaignGuidance(): any {
return {
getting_started: {
title: 'Campaign Creation Quick Start Guide',
overview: 'Creating successful email campaigns requires proper setup and understanding of key requirements.',
essential_first_step: {
action: 'Call list_accounts first',
reason: 'You need to see which email accounts are available and eligible for sending',
command: 'list_accounts {"get_all": true}'
}
},
required_fields: {
name: {
description: 'Campaign identifier for your reference',
examples: ['Q4 Product Launch Campaign', 'Holiday Sales Outreach', 'Partnership Inquiry - SaaS Companies'],
tips: ['Be descriptive but concise', 'Include target audience or purpose', 'Use consistent naming convention']
},
subject: {
description: 'Email subject line that recipients see',
best_practices: [
'Keep under 50 characters for better open rates',
'Personalize with {{firstName}} or {{companyName}}',
'Be specific and relevant to recipient',
'Avoid spam trigger words (FREE, URGENT, etc.)'
],
examples: [
'{{firstName}}, quick question about {{companyName}}',
'Helping {{companyName}} with [specific problem]',
'{{firstName}}, saw your recent [achievement/news]'
]
},
body: {
description: 'Main email content',
formatting_rules: [
'Use plain text with \\n for line breaks - they will be automatically converted to <br /> tags for HTML email rendering',
'Double line breaks (\\n\\n) create new paragraphs with <p> tags',
'Single line breaks (\\n) become <br /> tags within paragraphs',
'Personalize with {{firstName}}, {{lastName}}, {{companyName}}',
'Avoid escaped characters like \\" or \\t',
'The tool automatically handles HTML conversion - just use \\n in your input'
],
structure_template: 'Hi {{firstName}},\\n\\n[Opening line referencing something specific about them/their company]\\n\\n[Your value proposition or question]\\n\\n[Clear call to action]\\n\\nBest regards,\\n[Your name]',
example: 'Hi {{firstName}},\\n\\nI noticed {{companyName}} recently expanded into the European market. Congratulations!\\n\\nI help companies like yours streamline their international operations. Would you be open to a brief conversation about how we could support your expansion?\\n\\nBest regards,\\nJohn Smith',
html_conversion_note: 'This example will be automatically converted to proper HTML with <p> tags for paragraphs and <br /> tags for line breaks'
},
email_list: {
description: 'Sender email addresses from your verified accounts',
constraints: [
'Must use emails from your verified Instantly accounts',
'Only one sender email per campaign creation call',
'Accounts must be active (status=1) and warmed up (warmup_status=1)'
],
how_to_find: 'Call list_accounts to see available options',
example: ['john@yourcompany.com']
}
},
optional_settings_explained: {
tracking: {
track_opens: 'Tracks when recipients open your emails (recommended: true)',
track_clicks: 'Tracks when recipients click links in your emails (recommended: true)'
},
scheduling: {
timezone: `Timezone for sending schedule (default: ${DEFAULT_TIMEZONE} - verified working timezone)`,
timing_from: 'Start time for sending in 24h format (default: 09:00)',
timing_to: 'End time for sending in 24h format (default: 17:00)',
days: 'Days of week for sending (default: Monday-Friday only)'
},
limits: {
daily_limit: 'Maximum emails per day per account (default: 30 for cold email compliance)',
email_gap: 'Minutes between emails from same account (default: 10) - API v2 parameter'
},
behavior: {
stop_on_reply: 'Stop campaign when recipient replies (default: true)',
stop_on_auto_reply: 'Stop on auto-replies like out-of-office (default: true)'
},
sequences: {
sequence_steps: 'Number of emails in the sequence (default: 1 for single email, max: 10)',
step_delay_days: 'Days to wait AFTER sending each step before sending the next step (default: 3 days). CRITICAL: This delay applies to ALL steps including Step 1. Example with 2-day delay: Step 1 sends → Wait 2 days → Step 2 sends → Wait 2 days → Step 3 sends.',
sequence_bodies: 'Optional custom email content for each step (array of strings)',
sequence_subjects: 'Optional custom subject lines for each step (array of strings)',
when_to_use: 'Multi-step sequences are effective for cold outreach, nurturing leads, and following up on proposals',
best_practices: [
'Start with 2-3 steps for cold outreach',
'Increase value with each follow-up',
'Reference previous emails in follow-ups',
'Space follow-ups 2-7 days apart (step_delay_days parameter)',
'Personalize each step differently',
'CRITICAL: The delay applies to ALL steps - Step 1 will wait before Step 2, Step 2 will wait before Step 3, etc.'
]
}
},
common_mistakes: [
{
mistake: 'Not calling list_accounts first',
consequence: 'Using invalid email addresses that cause campaign creation to fail',
solution: 'Always call list_accounts to see available sender emails'
},
{
mistake: 'Using escaped characters in email body',
consequence: 'Email body appears with literal \\n instead of line breaks',
solution: 'Use plain \\n characters - they will be automatically converted to <br /> tags for HTML rendering'
},
{
mistake: 'Subject lines too long',
consequence: 'Poor open rates due to truncated subjects',
solution: 'Keep subjects under 50 characters'
},
{
mistake: 'Setting daily limits too high',
consequence: 'Triggers spam filters and hurts deliverability',
solution: 'Use maximum 30 emails per day for cold outreach compliance'
},
{
mistake: 'Enabling email tracking',
consequence: 'Reduced deliverability and privacy compliance issues',
solution: 'Keep tracking disabled unless analytics are absolutely necessary'
},
{
mistake: 'Generic, non-personalized content',
consequence: 'Low response rates and potential spam classification',
solution: 'Use personalization variables and specific, relevant content'
}
],
success_checklist: [
'✓ Called list_accounts to verify available sender emails',
'✓ Campaign name is descriptive and follows your naming convention',
'✓ Subject line is under 50 characters and personalized',
'✓ Email body uses \\n for line breaks (automatically converted to HTML)',
'✓ Content is personalized and relevant to recipients',
'✓ Sender email is from verified, warmed-up account',
'✓ Daily limit set to 30 or less for cold email compliance',
'✓ Email tracking disabled for better deliverability',
'✓ Sending schedule matches your target audience timezone',
'✓ Multi-step sequences configured appropriately (if using)'
]
};
}
