turbosmtp

Instructions

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
          );
      }
  }