check_free_email

Instructions

Implementation Reference

• src/index.ts:260-305 (handler)

  The handler function for 'check_free_email' tool. It takes an emailAddress, calls the MailboxValidator /email/free API, formats the response, and returns text content. Handles errors by catching them.

  async ({ emailAddress }) => {
    try {
      const params = new URLSearchParams({
        email: emailAddress,
        key: apiKey,
        format: "json",
      });
  
      const freeUrl = `${MBV_API_BASE}/email/free?${params.toString()}`;
      const freeData = await makeMBVRequest<FreeResponse>(freeUrl);
  
      if (freeData.error) {
        return {
          content: [
            {
              type: "text",
              text: `MailboxValidator API error ${freeData.error.error_code ?? ""}: ${freeData.error.error_message ?? "Unknown error"}`,
            },
          ],
        };
      }
  
      const formattedFree = formatFree(freeData);
      const freeText = `Free email result for ${emailAddress}:\n\n${formattedFree}`;
  
      return {
        content: [
          {
            type: "text",
            text: freeText,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to retrieve free email data: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/index.ts:254-258 (schema)

  Input schema for 'check_free_email'. Defines a single required parameter 'emailAddress' validated as a Zod email string.

  {
    description: "Checks if an email address is a free email using MailboxValidator.",
    inputSchema: {
      emailAddress: z.string().email().describe("Email address to check."),
    },

• src/index.ts:252-306 (registration)

  Registration of the 'check_free_email' tool via server.registerTool(). Includes description, inputSchema, and the async handler.

  server.registerTool(
    "check_free_email",
    {
      description: "Checks if an email address is a free email using MailboxValidator.",
      inputSchema: {
        emailAddress: z.string().email().describe("Email address to check."),
      },
    },
    async ({ emailAddress }) => {
      try {
        const params = new URLSearchParams({
          email: emailAddress,
          key: apiKey,
          format: "json",
        });
  
        const freeUrl = `${MBV_API_BASE}/email/free?${params.toString()}`;
        const freeData = await makeMBVRequest<FreeResponse>(freeUrl);
  
        if (freeData.error) {
          return {
            content: [
              {
                type: "text",
                text: `MailboxValidator API error ${freeData.error.error_code ?? ""}: ${freeData.error.error_message ?? "Unknown error"}`,
              },
            ],
          };
        }
  
        const formattedFree = formatFree(freeData);
        const freeText = `Free email result for ${emailAddress}:\n\n${formattedFree}`;
  
        return {
          content: [
            {
              type: "text",
              text: freeText,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Failed to retrieve free email data: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
        };
      }
    }
  );

• src/index.ts:131-137 (helper)

  formatFree helper function that formats the FreeResponse data (email_address, is_free, credits_available) into a display string.

  function formatFree(data: FreeResponse): string {
    return [
      `Email Address: ${formatValue(data.email_address)}`,
      `Is Free: ${formatValue(data.is_free)}`,
      `Credits Available: ${formatValue(data.credits_available)}`,
    ].join("\n");
  }

• src/index.ts:60-68 (helper)

  FreeResponse interface defining the shape of the API response for the free email check.

  interface FreeResponse {
    email_address?: string;
    is_free?: boolean | null;
    credits_available?: number;
    error?: {
      error_code?: number;
      error_message?: string;
    };
  }