MCP Mailtrap Server

Instructions

Implementation Reference

• src/tools/sendEmail/sendEmail.ts:8-111 (handler)

  The main handler function for the 'send-email' tool. It constructs and sends an email using the Mailtrap client, handling normalization of recipients, CC/BCC, and error cases.

  async function sendEmail({
    from,
    to,
    subject,
    text,
    cc,
    bcc,
    category,
    html,
  }: SendMailToolRequest): Promise<{ content: any[]; isError?: boolean }> {
    try {
      if (!client) {
        throw new Error("MAILTRAP_API_TOKEN environment variable is required");
      }
  
      if (!html && !text) {
        throw new Error("Either HTML or TEXT body is required");
      }
  
      const fromEmail = from ?? DEFAULT_FROM_EMAIL;
  
      if (!fromEmail) {
        throw new Error(
          "No 'from' email provided and no 'DEFAULT_FROM_EMAIL' email set"
        );
      }
  
      const fromAddress: Address = {
        email: fromEmail,
      };
  
      // Handle both single email and array of emails
      // Normalize inputs: convert to array, trim each email, filter empty strings
      const normalizedToEmails = (Array.isArray(to) ? to : [to])
        .map((email) => email.trim())
        .filter((email) => email.length > 0);
  
      // Validate that we have at least one valid recipient after normalization
      if (normalizedToEmails.length === 0) {
        throw new Error(
          "No valid recipients provided in 'to' field after normalization"
        );
      }
  
      const toAddresses: Address[] = normalizedToEmails.map((email) => ({
        email,
      }));
  
      const emailData: Mail = {
        from: fromAddress,
        to: toAddresses,
        subject,
        text,
        html,
        category,
      };
  
      if (cc && cc.length > 0) {
        const normalizedCcEmails = cc
          .map((email) => email.trim())
          .filter((email) => email.length > 0);
        if (normalizedCcEmails.length > 0) {
          emailData.cc = normalizedCcEmails.map((email) => ({ email }));
        }
      }
      if (bcc && bcc.length > 0) {
        const normalizedBccEmails = bcc
          .map((email) => email.trim())
          .filter((email) => email.length > 0);
        if (normalizedBccEmails.length > 0) {
          emailData.bcc = normalizedBccEmails.map((email) => ({ email }));
        }
      }
  
      const response = await client.send(emailData);
  
      return {
        content: [
          {
            type: "text",
            text: `Email sent successfully to ${toAddresses
              .map((addr) => addr.email)
              .join(", ")}.\nMessage IDs: ${response.message_ids}\nStatus: ${
              response.success ? "Success" : "Failed"
            }`,
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
  
      return {
        content: [
          {
            type: "text",
            text: `Failed to send email: ${errorMessage}`,
          },
        ],
        isError: true,
      };
    }
  }
  
  export default sendEmail;

• src/tools/sendEmail/schema.ts:1-76 (schema)

  Input schema for the 'send-email' tool, defining properties like to, subject, category (required), from (optional if default set), text/html body, cc/bcc. Dynamically adjusts 'from' required status based on env var.

  const hasDefaultFromEmail = !!process.env.DEFAULT_FROM_EMAIL;
  
  const sendEmailSchema = {
    type: "object",
    properties: {
      from: {
        type: "string",
        format: "email",
        description: hasDefaultFromEmail
          ? "Email address of the sender (optional with default)"
          : "Email address of the sender",
      },
      to: {
        oneOf: [
          {
            type: "string",
            format: "email",
            description: "Single email address",
          },
          {
            type: "array",
            items: {
              type: "string",
              format: "email",
            },
            description: "Array of email addresses",
          },
        ],
        description:
          "Email address(es) of the recipient(s) - can be a single email or array of emails",
      },
      subject: {
        type: "string",
        description: "Email subject line",
      },
      cc: {
        type: "array",
        items: {
          type: "string",
          format: "email",
        },
        description: "Optional CC recipients",
      },
      bcc: {
        type: "array",
        items: {
          type: "string",
          format: "email",
        },
        description: "Optional BCC recipients",
      },
      category: {
        type: "string",
        description: "Email category for tracking",
      },
      text: {
        type: "string",
        description: "Email body text",
      },
      html: {
        type: "string",
        description: "Optional HTML version of the email body",
      },
    },
    required: ["to", "subject", "category"],
    additionalProperties: false,
  };
  
  if (hasDefaultFromEmail) {
    // Make from optional when default is available
    sendEmailSchema.required = sendEmailSchema.required.filter(
      (field: string) => field !== "from"
    );
  }
  
  export default sendEmailSchema;

• src/server.ts:36-45 (registration)

  Registration of the 'send-email' tool in the tools registry array used by the MCP server, linking the schema and handler, with destructive annotation.

  {
    name: "send-email",
    description:
      "Send an email to your recipient email address using Mailtrap Email API. You can send emails to multiple recipients at once.",
    inputSchema: sendEmailSchema,
    handler: sendEmail,
    annotations: {
      destructiveHint: true,
    },
  },