get_analytics_data
Retrieve email analytics data from TurboSMTP within a specified date range. Use start and end dates, optional filters, pagination, and timezone settings to extract precise insights.
Instructions
Retrieve analytics data from TurboSMTP for a specific date range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter for analytics data (optional) | |
| from | Yes | Start date for analytics (format: YYYY-MM-DD) | |
| limit | No | Number of results per page (optional) | |
| page | No | Page number (optional) | |
| to | Yes | End date for analytics (format: YYYY-MM-DD) | |
| tz | No | Timezone (optional, e.g., "Europe/Rome", "America/New_York") |
Implementation Reference
- mcp-turbosmtp-server.js:229-293 (handler)The MCP tool handler function 'handleGetAnalyticsData' that performs input validation specific to the tool, delegates to EmailService, formats the output nicely, and returns in MCP content format.
async handleGetAnalyticsData(args) { const { from, to, page, limit, tz, filter } = args; // Date format validation const dateRegex = /^\d{4}-\d{2}-\d{2}$/; if (!from || !dateRegex.test(from)) { throw new Error('The "from" parameter is required and must be in YYYY-MM-DD format'); } if (!to || !dateRegex.test(to)) { throw new Error('The "to" parameter is required and must be in YYYY-MM-DD format'); } // Validate date logic const fromDate = new Date(from); const toDate = new Date(to); if (fromDate > toDate) { throw new Error('The "from" date must be before or equal to the "to" date'); } // Validate optional parameters if (page !== undefined && (!Number.isInteger(page) || page < 1)) { throw new Error('The "page" parameter must be a positive integer'); } if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 100)) { throw new Error('The "limit" parameter must be an integer between 1 and 100'); } try { const result = await EmailService.getAnalyticsData({ from, to, page, limit, tz, filter }); // Format the analytics data for better readability let formattedOutput = `š Analytics Data Retrieved Successfully!\n\n`; formattedOutput += `Date Range: ${from} to ${to}\n`; if (page) formattedOutput += `Page: ${page}\n`; if (limit) formattedOutput += `Results per page: ${limit}\n`; if (tz) formattedOutput += `Timezone: ${tz}\n`; if (filter) formattedOutput += `Filter: ${filter}\n`; formattedOutput += `\nš Analytics Summary:\n`; formattedOutput += `${JSON.stringify(result.data, null, 2)}`; return { content: [ { type: 'text', text: formattedOutput } ] }; } catch (error) { throw new Error(`Error retrieving analytics data: ${error.message}`); } } - mcp-turbosmtp-server.js:66-100 (schema)Input schema for the get_analytics_data tool, defining the expected parameters, types, descriptions, patterns, and required fields.
inputSchema: { type: 'object', properties: { from: { type: 'string', description: 'Start date for analytics (format: YYYY-MM-DD)', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }, to: { type: 'string', description: 'End date for analytics (format: YYYY-MM-DD)', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }, page: { type: 'number', description: 'Page number (optional)', minimum: 1 }, limit: { type: 'number', description: 'Number of results per page (optional)', minimum: 1, maximum: 100 }, tz: { type: 'string', description: 'Timezone (optional, e.g., "Europe/Rome", "America/New_York")' }, filter: { type: 'string', description: 'Filter for analytics data (optional)' } }, required: ['from', 'to'] } - mcp-turbosmtp-server.js:63-101 (registration)Tool registration in the ListTools handler, specifying name, description, and linking to input schema.
{ name: 'get_analytics_data', description: 'Retrieve analytics data from TurboSMTP for a specific date range', inputSchema: { type: 'object', properties: { from: { type: 'string', description: 'Start date for analytics (format: YYYY-MM-DD)', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }, to: { type: 'string', description: 'End date for analytics (format: YYYY-MM-DD)', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }, page: { type: 'number', description: 'Page number (optional)', minimum: 1 }, limit: { type: 'number', description: 'Number of results per page (optional)', minimum: 1, maximum: 100 }, tz: { type: 'string', description: 'Timezone (optional, e.g., "Europe/Rome", "America/New_York")' }, filter: { type: 'string', description: 'Filter for analytics data (optional)' } }, required: ['from', 'to'] } }, - email-service.js:67-110 (helper)Supporting helper function in EmailService that performs the actual HTTP request to TurboSMTP API for analytics data, including parameter construction and error handling.
async getAnalyticsData({from, to, page, limit, tz, filter}) { // Utility function to validate date format. const isValidDate = (dateString) => /^\d{4}-\d{2}-\d{2}$/.test(dateString); // Validation of 'from' and 'to' parameters. if (!from || !isValidDate(from)) { throw new Error('The "from" parameter is required and must be in YYYY-MM-DD format.'); } if (!to || !isValidDate(to)) { throw new Error('The "to" parameter is required and must be in YYYY-MM-DD format.'); } try { // Construction of query parameters. const queryParams = new URLSearchParams({from, to}); if (page) queryParams.append('page', page); if (limit) queryParams.append('limit', limit); if (tz) queryParams.append('tz', tz); if (filter) queryParams.append('filter', filter); // Execution of the GET request to the /analytics endpoint. // The API key is included in the 'Authorization' header. const response = await axios.get( `${this.apiUrl}/analytics?${queryParams.toString()}`, { headers: this.headers } ); // Returning response data on success. return { success: true, message: 'Analytics data successfully retrieved', data: response.data }; } catch (error) { // Handling HTTP request errors. console.error('Error retrieving analytics data:', error.response?.data || error.message); throw new Error( error.response?.data?.message || 'Error retrieving analytics data: ' + error.message ); } }