smartlead-mcp-by-leadmagic
Version:
💜 The Premier Model Context Protocol Server for SmartLead's Cold Email Automation Platform - Complete API coverage with 116+ tools for campaign management, lead tracking, smart delivery, and analytics. Beautiful purple-gradient installer, zero-config set
579 lines • 16.7 kB
TypeScript
/**
* SmartLead MCP Server - API Client
*
* A robust HTTP client for the SmartLead API with comprehensive error handling,
* retry logic, rate limiting, and type safety. This client provides a clean
* interface to all SmartLead API endpoints with production-ready features.
*
* Features:
* - Exponential backoff retry logic
* - Rate limiting and request queuing
* - Comprehensive error handling and classification
* - Request/response logging and debugging
* - Type-safe parameter validation
* - Connection testing and health checks
*
* @author LeadMagic Team
* @version 1.0.0
*/
import type { SmartLeadConfig } from './types.js';
/**
* Custom error class for SmartLead API errors
* Provides detailed error information and classification
*/
export declare class SmartLeadError extends Error {
readonly code: string;
readonly status: number;
readonly response?: unknown;
readonly isRetryable: boolean;
constructor(message: string, code?: string, status?: number, response?: unknown, isRetryable?: boolean);
/**
* Check if this is a client error (4xx status codes)
*/
isClientError(): boolean;
/**
* Check if this is a server error (5xx status codes)
*/
isServerError(): boolean;
/**
* Check if this is a network error
*/
isNetworkError(): boolean;
/**
* Check if this error should trigger a retry
*/
shouldRetry(): boolean;
}
/**
* SmartLead API Client
*
* Provides a comprehensive interface to the SmartLead API with robust error handling,
* retry logic, and type safety. All methods return properly typed responses and
* handle errors gracefully.
*/
export declare class SmartLeadClient {
private readonly apiClient;
private readonly config;
private requestCount;
private rateLimitResetTime;
/**
* Creates a new SmartLead API client
*
* @param config - Client configuration including API key and optional settings
* @throws {SmartLeadError} If configuration is invalid
*/
constructor(config: SmartLeadConfig);
/**
* Rate limiting: Check if we can make a request now
* @private
*/
private checkRateLimit;
/**
* Parse rate limit info from response headers
* @private
*/
private parseRateLimitHeaders;
/**
* Sets up Axios interceptors for request/response handling
* @private
*/
private setupInterceptors;
/**
* Handles Axios errors and converts them to SmartLeadError instances
* @private
*/
private handleAxiosError;
/**
* Implements exponential backoff retry logic
* @private
*/
private delay;
/**
* Executes a request with retry logic
* @private
*/
private withRetry;
/**
* Get campaigns with analytics - Combined endpoint for efficiency
* Fetches campaigns and their analytics in one call to reduce API usage
*
* @param options - Filtering and pagination options
* @returns Promise resolving to campaigns with analytics data
*/
getCampaignsWithAnalytics(options?: {
client_id?: string;
status?: 'ACTIVE' | 'PAUSED' | 'COMPLETED' | 'DRAFT';
limit?: number;
offset?: number;
start_date?: string;
end_date?: string;
}): Promise<any>;
/**
* Create a new campaign
*/
createCampaign(params: {
name: string;
client_id?: number;
}): Promise<any>;
/**
* Update campaign schedule
*/
updateCampaignSchedule(campaignId: number, params: any): Promise<any>;
/**
* Update campaign settings
*/
updateCampaignSettings(campaignId: number, params: any): Promise<any>;
/**
* Update campaign status
*/
updateCampaignStatus(campaignId: number, status: string): Promise<any>;
/**
* Get campaign details
*/
getCampaign(campaignId: number): Promise<any>;
/**
* List campaigns
*/
listCampaigns(params?: any): Promise<any>;
/**
* Save campaign sequence
*/
saveCampaignSequence(campaignId: number, sequence: any[]): Promise<any>;
/**
* Get campaign sequence
*/
getCampaignSequence(campaignId: number): Promise<any>;
/**
* List leads with filtering options
*/
listLeads(params?: any): Promise<any>;
/**
* Get lead details by ID
*/
getLead(leadId: number): Promise<any>;
/**
* Add a lead to campaign
*/
addLeadToCampaign(campaignId: number, leadData: any): Promise<any>;
/**
* Update lead information
*/
updateLead(leadId: number, leadData: any): Promise<any>;
/**
* Update lead status
*/
updateLeadStatus(leadId: number, status: string): Promise<any>;
/**
* Bulk import leads to campaign
*/
bulkImportLeads(campaignId: number, leads: any[]): Promise<any>;
/**
* Delete a lead
*/
deleteLead(leadId: number): Promise<any>;
/**
* Get campaign analytics by date range
*/
getCampaignAnalyticsByDate(campaignId: number, startDate: string, endDate: string): Promise<any>;
/**
* Get campaign statistics
*/
getCampaignStatistics(campaignId: number, params?: any): Promise<any>;
/**
* Get warmup stats by email
*/
getWarmupStatsByEmail(emailAccountId: number): Promise<any>;
/**
* Get campaign top level analytics
*/
getCampaignTopLevelAnalytics(campaignId: number): Promise<any>;
/**
* Get campaign lead statistics
*/
getCampaignLeadStatistics(campaignId: number, params?: any): Promise<any>;
/**
* Get campaign mailbox statistics
*/
getCampaignMailboxStatistics(campaignId: number, params?: any): Promise<any>;
/**
* Fetch webhooks by campaign
*/
fetchWebhooksByCampaign(campaignId: string): Promise<any>;
/**
* Upsert campaign webhook
*/
upsertCampaignWebhook(campaignId: string, webhookData: any): Promise<any>;
/**
* Delete campaign webhook
*/
deleteCampaignWebhook(campaignId: string, webhookId: number): Promise<any>;
/**
* Get webhook publish summary
*/
getWebhookPublishSummary(campaignId: string, params?: any): Promise<any>;
/**
* Retrigger failed webhook events
*/
retriggerFailedEvents(campaignId: string, fromTime: string, toTime: string): Promise<any>;
/**
* Get region wise providers
*/
getRegionWiseProviders(): Promise<any>;
/**
* Create manual placement test
*/
createManualPlacementTest(testData: any): Promise<any>;
/**
* Create automated placement test
*/
createAutomatedPlacementTest(testData: any): Promise<any>;
/**
* Get spam test details
*/
getSpamTestDetails(spamTestId: number): Promise<any>;
/**
* Delete smart delivery tests
*/
deleteSmartDeliveryTests(spamTestIds: number[]): Promise<any>;
/**
* List all tests
*/
listAllTests(testType: string, params?: any): Promise<any>;
/**
* Create folder
*/
createFolder(name: string): Promise<any>;
/**
* Get folder by ID
*/
getFolderById(folderId: number): Promise<any>;
/**
* Delete folder
*/
deleteFolder(folderId: number): Promise<any>;
/**
* Get all folders
*/
getAllFolders(params?: any): Promise<any>;
/**
* Stop automated test
*/
stopAutomatedTest(spamTestId: number): Promise<any>;
/**
* Get provider wise report
*/
getProviderWiseReport(spamTestId: number): Promise<any>;
/**
* Get group wise report
*/
getGroupWiseReport(spamTestId: number): Promise<any>;
/**
* Get sender account wise report
*/
getSenderAccountWiseReport(spamTestId: number): Promise<any>;
/**
* Get spam filter details
*/
getSpamFilterDetails(spamTestId: number): Promise<any>;
/**
* Get DKIM details
*/
getDkimDetails(spamTestId: number): Promise<any>;
/**
* Get SPF details
*/
getSpfDetails(spamTestId: number): Promise<any>;
/**
* Get rDNS details
*/
getRdnsDetails(spamTestId: number): Promise<any>;
/**
* Get sender accounts for spam test
*/
getSenderAccounts(spamTestId: number): Promise<any>;
/**
* Get blacklist information
*/
getBlacklist(spamTestId: number): Promise<any>;
/**
* Get email content
*/
getEmailContent(spamTestId: number): Promise<any>;
/**
* Get IP analytics
*/
getIpAnalytics(spamTestId: number): Promise<any>;
/**
* Get email headers
*/
getEmailHeaders(spamTestId: number, replyId: number): Promise<any>;
/**
* Get schedule history
*/
getScheduleHistory(spamTestId: number): Promise<any>;
/**
* Get IP details
*/
getIpDetails(spamTestId: number, replyId: number): Promise<any>;
/**
* Get mailbox summary
*/
getMailboxSummary(params?: any): Promise<any>;
/**
* Get mailbox count
*/
getMailboxCount(): Promise<any>;
/**
* List leads by campaign ID
*/
listLeadsByCampaign(campaignId: number, params?: any): Promise<any>;
/**
* Fetch lead categories
*/
fetchLeadCategories(): Promise<any>;
/**
* Fetch lead by email address
*/
fetchLeadByEmail(email: string): Promise<any>;
/**
* Add leads to campaign
*/
addLeadsToCampaign(campaignId: number, leads: any[]): Promise<any>;
/**
* Resume lead by campaign ID
*/
resumeLeadByCampaign(campaignId: number, leadId: number): Promise<any>;
/**
* Pause lead by campaign ID
*/
pauseLeadByCampaign(campaignId: number, leadId: number): Promise<any>;
/**
* Delete lead by campaign ID
*/
deleteLeadByCampaign(campaignId: number, leadId: number): Promise<any>;
/**
* Unsubscribe/Pause lead from campaign
*/
unsubscribeLeadFromCampaign(campaignId: number, leadId: number): Promise<any>;
/**
* Unsubscribe lead from all campaigns
*/
unsubscribeLeadFromAllCampaigns(leadId: number): Promise<any>;
/**
* Add lead/domain to global block list
*/
addLeadToGlobalBlocklist(email: string): Promise<any>;
/**
* Fetch all leads from entire account
*/
fetchAllLeadsFromAccount(params?: any): Promise<any>;
/**
* Fetch leads from global block list
*/
fetchLeadsFromGlobalBlocklist(params?: any): Promise<any>;
/**
* Update lead using lead ID
*/
updateLeadById(leadId: number, leadData: any): Promise<any>;
/**
* Update lead's category based on their campaign
*/
updateLeadCategory(campaignId: number, leadId: number, category: string): Promise<any>;
/**
* Fetch lead message history based on campaign
*/
fetchLeadMessageHistory(campaignId: number, leadId: number): Promise<any>;
/**
* Reply to lead from master inbox via API
*/
replyToLeadFromMasterInbox(campaignId: number, leadId: number, replyData: any): Promise<any>;
/**
* Forward a reply
*/
forwardReply(campaignId: number, leadId: number, forwardData: any): Promise<any>;
/**
* List all email accounts per campaign
*/
listEmailAccountsPerCampaign(campaignId: number): Promise<any>;
/**
* Add email account to campaign
*/
addEmailAccountToCampaign(campaignId: number, emailAccountId: number): Promise<any>;
/**
* Remove email account from campaign
*/
removeEmailAccountFromCampaign(campaignId: number, emailAccountId: number): Promise<any>;
/**
* Fetch all email accounts associated to a user
*/
fetchAllEmailAccounts(): Promise<any>;
/**
* Create an email account
*/
createEmailAccount(emailAccountData: any): Promise<any>;
/**
* Update email account
*/
updateEmailAccount(emailAccountId: number, emailAccountData: any): Promise<any>;
/**
* Fetch email account by ID
*/
fetchEmailAccountById(emailAccountId: number): Promise<any>;
/**
* Add/Update warmup to email account
*/
addUpdateWarmupToEmailAccount(emailAccountId: number, warmupData: any): Promise<any>;
/**
* Reconnect failed email accounts
*/
reconnectFailedEmailAccounts(emailAccountIds: number[]): Promise<any>;
/**
* Update email account tag
*/
updateEmailAccountTag(emailAccountId: number, tag: string): Promise<any>;
/**
* Add client
*/
addClient(clientData: any): Promise<any>;
/**
* Fetch all clients
*/
fetchAllClients(): Promise<any>;
/**
* Create new client API key
*/
createNewClientApiKey(clientId: number, keyData: any): Promise<any>;
/**
* Get client's API keys
*/
getClientsApiKeys(clientId: number): Promise<any>;
/**
* Delete client API key
*/
deleteClientApiKey(clientId: number, keyId: number): Promise<any>;
/**
* Reset client API key
*/
resetClientApiKey(clientId: number, keyId: number): Promise<any>;
/**
* Get vendors
*/
getVendors(): Promise<any>;
/**
* Search domain
*/
searchDomain(domainName: string, vendorId: number): Promise<any>;
/**
* Auto generate mailboxes
*/
autoGenerateMailboxes(data: any): Promise<any>;
/**
* Place order for mailboxes
*/
placeOrderMailboxes(data: any): Promise<any>;
/**
* Get domain list
*/
getDomainList(): Promise<any>;
/**
* Download campaign data (supports CSV format)
*/
downloadCampaignData(campaignId: number, downloadType: string, format?: 'json' | 'csv', userId?: string): Promise<any>;
/**
* View download statistics
*/
viewDownloadStatistics(timePeriod?: string, groupBy?: string): Promise<any>;
/**
* Get campaign list for analytics
*/
getAnalyticsCampaignList(params?: any): Promise<any>;
/**
* Get client list for analytics
*/
getAnalyticsClientList(params?: any): Promise<any>;
/**
* Get month-wise client count
*/
getAnalyticsClientMonthWiseCount(params?: any): Promise<any>;
/**
* Get overall stats v2
*/
getAnalyticsOverallStatsV2(params?: any): Promise<any>;
/**
* Get day-wise overall stats
*/
getAnalyticsDayWiseOverallStats(params?: any): Promise<any>;
/**
* Get day-wise positive reply stats
*/
getAnalyticsDayWisePositiveReplyStats(params?: any): Promise<any>;
/**
* Get campaign overall stats
*/
getAnalyticsCampaignOverallStats(params?: any): Promise<any>;
/**
* Get client overall stats
*/
getAnalyticsClientOverallStats(params?: any): Promise<any>;
/**
* Get email-id-wise health metrics
*/
getAnalyticsMailboxNameWiseHealthMetrics(params?: any): Promise<any>;
/**
* Get domain-wise health metrics
*/
getAnalyticsMailboxDomainWiseHealthMetrics(params?: any): Promise<any>;
/**
* Get provider-wise overall performance
*/
getAnalyticsMailboxProviderWiseOverallPerformance(params?: any): Promise<any>;
/**
* Get team board overall stats
*/
getAnalyticsTeamBoardOverallStats(params?: any): Promise<any>;
/**
* Get lead overall stats
*/
getAnalyticsLeadOverallStats(params?: any): Promise<any>;
/**
* Get lead category-wise response
*/
getAnalyticsLeadCategoryWiseResponse(params?: any): Promise<any>;
/**
* Get leads take for first reply
*/
getAnalyticsCampaignLeadsTakeForFirstReply(params?: any): Promise<any>;
/**
* Get follow-up reply rate
*/
getAnalyticsCampaignFollowUpReplyRate(params?: any): Promise<any>;
/**
* Get lead to reply time
*/
getAnalyticsCampaignLeadToReplyTime(params?: any): Promise<any>;
/**
* Get campaign response stats
*/
getAnalyticsCampaignResponseStats(params?: any): Promise<any>;
/**
* Get campaign status stats
*/
getAnalyticsCampaignStatusStats(params?: any): Promise<any>;
/**
* Get mailbox overall stats
*/
getAnalyticsMailboxOverallStats(params?: any): Promise<any>;
/**
* Test the API connection and validate credentials
*/
testConnection(): Promise<{
success: boolean;
message?: string;
error?: string;
}>;
/**
* Get client configuration (excluding sensitive data)
*/
getConfig(): Partial<SmartLeadConfig>;
}
//# sourceMappingURL=client.d.ts.map