turbosmtp

Instructions

Implementation Reference

• mcp-turbosmtp-server.js:151-199 (handler)

  Main handler for executing the send_email tool. Validates input parameters, checks email formats, calls EmailService.sendEmail, and formats the success response.

  async handleSendEmail(args) {
    const { to, subject, text, html, from } = args;
  
    // Input validation
    if (!to || !Array.isArray(to) || to.length === 0) {
      throw new Error('The "to" field must be a non-empty array of email addresses');
    }
  
    if (!subject || typeof subject !== 'string') {
      throw new Error('The "subject" field is required and must be a string');
    }
  
    if (!text || typeof text !== 'string') {
      throw new Error('The "text" field is required and must be a string');
    }
  
    // Email validation
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    for (const email of to) {
      if (!emailRegex.test(email)) {
        throw new Error(`Invalid email address: ${email}`);
      }
    }
  
    if (from && !emailRegex.test(from)) {
      throw new Error(`Invalid sender email address: ${from}`);
    }
  
    try {
      const result = await EmailService.sendEmail({
        to,
        subject,
        text,
        html,
        from
      });
  
      return {
        content: [
          {
            type: 'text',
            text: `✅ Email sent successfully!\n\nRecipients: ${to.join(', ')}\nSubject: ${subject}\n\nDetails: ${JSON.stringify(result.data, null, 2)}`
          }
        ]
      };
    } catch (error) {
      throw new Error(`Error sending email: ${error.message}`);
    }
  }

• mcp-turbosmtp-server.js:35-61 (schema)

  Input schema defining the parameters for the send_email tool, including types, descriptions, and required fields.

  inputSchema: {
    type: 'object',
    properties: {
      to: {
        type: 'array',
        items: { type: 'string' },
        description: 'List of recipient email addresses'
      },
      subject: {
        type: 'string',
        description: 'Email subject'
      },
      text: {
        type: 'string',
        description: 'Text content of the email'
      },
      html: {
        type: 'string',
        description: 'HTML content of the email (optional)'
      },
      from: {
        type: 'string',
        description: 'Sender email address (optional, uses configured one if not specified)'
      }
    },
    required: ['to', 'subject', 'text']
  }

• mcp-turbosmtp-server.js:32-62 (registration)

  Registration of the send_email tool in the ListToolsRequestSchema handler, including name, description, and schema.

  {
    name: 'send_email',
    description: 'Send an email via TurboSMTP',
    inputSchema: {
      type: 'object',
      properties: {
        to: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of recipient email addresses'
        },
        subject: {
          type: 'string',
          description: 'Email subject'
        },
        text: {
          type: 'string',
          description: 'Text content of the email'
        },
        html: {
          type: 'string',
          description: 'HTML content of the email (optional)'
        },
        from: {
          type: 'string',
          description: 'Sender email address (optional, uses configured one if not specified)'
        }
      },
      required: ['to', 'subject', 'text']
    }
  },

• email-service.js:19-47 (helper)

  Core helper function in EmailService that constructs the payload and sends the email via TurboSMTP API using axios.

  async sendEmail({to, subject, text, html, from}) {
      try {
          const payload = {
              to: (Array.isArray(to) ? to : [to]).join(","),
              subject,
              content: text || '',
              html_content: html || '',
              from: from || process.env.TURBOSMTP_FROM_EMAIL
          };
  
          const response = await axios.post(
              `${this.sendApiUrl}/mail/send`,
              payload,
              {headers: this.headers}
          );
  
          return {
              success: true,
              message: 'Email sent successfully',
              data: response.data
          };
      } catch (error) {
          console.error('Error sending email:', error.response?.data || error.message);
          throw new Error(
              error.response?.data?.message ||
              'Error sending email: ' + error.message
          );
      }
  }