MCP Mailtrap Server

Instructions

Implementation Reference

• src/tools/sandbox/sendSandboxEmail.ts:7-106 (handler)

  The handler function for send-sandbox-email tool. Sends an email using Mailtrap sandbox client to a test inbox.

  async function sendSandboxEmail({
    from,
    to,
    subject,
    text,
    cc,
    bcc,
    category,
    html,
  }: SendSandboxEmailRequest): Promise<{ content: any[]; isError?: boolean }> {
    try {
      const { MAILTRAP_TEST_INBOX_ID } = process.env;
  
      if (!MAILTRAP_TEST_INBOX_ID) {
        throw new Error(
          "MAILTRAP_TEST_INBOX_ID environment variable is required for sandbox mode"
        );
      }
  
      if (!html && !text) {
        throw new Error("Either HTML or TEXT body is required");
      }
  
      // Use provided 'from' email or fall back to DEFAULT_FROM_EMAIL
      const fromEmail = from || DEFAULT_FROM_EMAIL;
  
      if (!fromEmail) {
        throw new Error(
          "No 'from' email provided and no 'DEFAULT_FROM_EMAIL' email set"
        );
      }
  
      // Check if sandbox client is available
      if (!sandboxClient) {
        throw new Error(
          "Sandbox client is not available. Please set MAILTRAP_TEST_INBOX_ID environment variable."
        );
      }
  
      const fromAddress: Address = {
        email: fromEmail,
      };
  
      // Parse and validate email addresses from the 'to' string
      const toEmails = to
        .split(",")
        .map((email) => email.trim())
        .filter((email) => email.length > 0)
        .filter((email) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email));
  
      if (toEmails.length === 0) {
        throw new Error("No valid email addresses provided in 'to' field");
      }
  
      const toAddresses: Address[] = toEmails.map((email) => ({ email }));
  
      const emailData: Mail = {
        from: fromAddress,
        to: toAddresses,
        subject,
        text,
        html,
        category,
      };
  
      if (cc && cc.length > 0) emailData.cc = cc.map((email) => ({ email }));
      if (bcc && bcc.length > 0) emailData.bcc = bcc.map((email) => ({ email }));
  
      const response = await sandboxClient.send(emailData);
  
      return {
        content: [
          {
            type: "text",
            text: `Sandbox email sent successfully to ${toEmails.join(
              ", "
            )}.\nMessage IDs: ${response.message_ids.join(", ")}\nStatus: ${
              response.success ? "Success" : "Failed"
            }`,
          },
        ],
      };
    } catch (error) {
      console.error("Error sending sandbox email:", error);
  
      const errorMessage = error instanceof Error ? error.message : String(error);
  
      return {
        content: [
          {
            type: "text",
            text: `Failed to send sandbox email: ${errorMessage}`,
          },
        ],
        isError: true,
      };
    }
  }
  
  export default sendSandboxEmail;

• src/tools/sandbox/schemas/sendSandboxEmail.ts:1-51 (schema)

  Input schema definition for the send-sandbox-email tool parameters.

  const sendSandboxEmailSchema = {
    type: "object",
    properties: {
      from: {
        type: "string",
        format: "email",
        description: "Email address of the sender",
      },
      to: {
        type: "string",
        minLength: 1,
        description: "Email addresses (comma-separated or single)",
      },
      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: "Optional email category for tracking",
      },
      text: {
        type: "string",
        description: "Email body text",
      },
      html: {
        type: "string",
        description: "Optional HTML version of the email body",
      },
    },
    required: ["from", "to", "subject"],
    additionalProperties: false,
  };
  
  export default sendSandboxEmailSchema;

• src/server.ts:82-91 (registration)

  Registration of the send-sandbox-email tool in the tools array, linking schema and handler.

  {
    name: "send-sandbox-email",
    description:
      "Send an email in sandbox mode to a test inbox without delivering to your recipients",
    inputSchema: sendSandboxEmailSchema,
    handler: sendSandboxEmail,
    annotations: {
      destructiveHint: false,
    },
  },