abstractapi-mcp-server

Instructions

Implementation Reference

• server.py:219-364 (handler)

  The core handler function decorated with @mcp.tool(), which registers and implements the check_email_reputation tool. It validates the presence of the API key, constructs the API request to Abstract API's Email Reputation endpoint, fetches and returns the reputation data as a dictionary, with comprehensive error handling.
  @mcp.tool() async def check_email_reputation(email: str) -> dict[str, Any]: """ Analyzes email reputation using Abstract API's Email Reputation service. This function provides comprehensive email reputation analysis including deliverability, quality scoring, sender information, domain details, risk assessment, and breach history. It's designed to help improve delivery rates, clean email lists, and block fraudulent users. Args: email (str): The email address to analyze for reputation. Returns: dict[str, Any]: A dictionary containing comprehensive reputation analysis. The dictionary includes the following main sections: - "email_address" (str): The email address that was analyzed. - "email_deliverability" (dict): Deliverability information. - "status" (str): "deliverable", "undeliverable", or "unknown". - "status_detail" (str): Additional detail (e.g., "valid_email", "invalid_format"). - "is_format_valid" (bool): True if email follows correct format. - "is_smtp_valid" (bool): True if SMTP check was successful. - "is_mx_valid" (bool): True if domain has valid MX records. - "mx_records" (list): List of MX records for the domain. - "email_quality" (dict): Quality assessment information. - "score" (float): Confidence score between 0.01 and 0.99. - "is_free_email" (bool): True if from free provider (Gmail, Yahoo, etc.). - "is_username_suspicious" (bool): True if username appears auto-generated. - "is_disposable" (bool): True if from disposable email provider. - "is_catchall" (bool): True if domain accepts all emails. - "is_subaddress" (bool): True if uses subaddressing (user+label@domain.com). - "is_role" (bool): True if role-based address (info@, support@, etc.). - "is_dmarc_enforced" (bool): True if strict DMARC policy enforced. - "is_spf_strict" (bool): True if domain enforces strict SPF policy. - "minimum_age" (int|null): Estimated age of email address in days. - "email_sender" (dict): Sender information if available. - "first_name" (str|null): First name associated with email. - "last_name" (str|null): Last name associated with email. - "email_provider_name" (str|null): Email provider name (e.g., "Google"). - "organization_name" (str|null): Organization linked to email/domain. - "organization_type" (str|null): Type of organization (e.g., "company"). - "email_domain" (dict): Domain information. - "domain" (str): Domain part of the email. - "domain_age" (int|null): Age of domain in days. - "is_live_site" (bool|null): True if domain has active website. - "registrar" (str|null): Domain registrar name. - "registrar_url" (str|null): Registrar website URL. - "date_registered" (str|null): Domain registration date. - "date_last_renewed" (str|null): Last renewal date. - "date_expires" (str|null): Domain expiration date. - "is_risky_tld" (bool|null): True if top-level domain is considered risky. - "email_risk" (dict): Risk assessment. - "address_risk_status" (str): Risk level for the email address. - "domain_risk_status" (str): Risk level for the domain. - "email_breaches" (dict): Data breach information. - "total_breaches" (int|null): Number of known breaches. - "date_first_breached" (str|null): Date of first known breach. - "date_last_breached" (str|null): Date of most recent breach. - "breached_domains" (list): List of breached domains with dates. Example: >>> await check_email_reputation("benjamin.richard@abstractapi.com") { "email_address": "benjamin.richard@abstractapi.com", "email_deliverability": { "status": "deliverable", "status_detail": "valid_email", "is_format_valid": true, "is_smtp_valid": true, "is_mx_valid": true, "mx_records": ["gmail-smtp-in.l.google.com", ...] }, "email_quality": { "score": 0.8, "is_free_email": false, "is_username_suspicious": false, "is_disposable": false, "is_catchall": true, "is_subaddress": false, "is_role": false, "is_dmarc_enforced": true, "is_spf_strict": true, "minimum_age": 1418 }, "email_sender": { "first_name": "Benjamin", "last_name": "Richard", "email_provider_name": "Google", "organization_name": "Abstract API", "organization_type": "company" }, "email_domain": { "domain": "abstractapi.com", "domain_age": 1418, "is_live_site": true, "registrar": "NAMECHEAP INC", "registrar_url": "http://www.namecheap.com", "date_registered": "2020-05-13", "date_last_renewed": "2024-04-13", "date_expires": "2025-05-13", "is_risky_tld": false }, "email_risk": { "address_risk_status": "low", "domain_risk_status": "low" }, "email_breaches": { "total_breaches": 2, "date_first_breached": "2018-07-23T14:30:00Z", "date_last_breached": "2019-05-24T14:30:00Z", "breached_domains": [ {"domain": "apollo.io", "date_breached": "2018-07-23T14:30:00Z"}, {"domain": "canva.com", "date_breached": "2019-05-24T14:30:00Z"} ] } } Raises: ValueError: If the API key is not found in the environment variables. requests.exceptions.HTTPError: If the API request fails (e.g., 4xx or 5xx error). Exception: For any other unexpected errors. """ # Check if the API key is available if not ABSTRACT_API_KEY: raise ValueError("API key not found in environment variables.") # Construct the API URL api_url = f"{EMAIL_REPUTATION_API_URL}?api_key={ABSTRACT_API_KEY}&email={email}" try: # Make the API request (ignoring SSL verification) response = requests.get(api_url, verify=False) response.raise_for_status() # Raise an error for bad responses (4xx, 5xx) # Parse the JSON response result = response.json() # Return the reputation analysis results return result except requests.exceptions.HTTPError as http_err: # Handle HTTP errors (e.g., 4xx, 5xx) raise requests.exceptions.HTTPError(f"HTTP error occurred: {http_err}") except Exception as err: # Handle any other errors raise Exception(f"An error occurred: {err}")
• server.py:219-219 (registration)

  The @mcp.tool() decorator registers the check_email_reputation function as an MCP tool.
  @mcp.tool()
• server.py:220-339 (schema)

  The function signature provides type hints for input (email: str) and output (dict[str, Any]). The extensive docstring details the expected output structure including email_deliverability, email_quality, email_sender, email_domain, email_risk, and email_breaches sections.
  async def check_email_reputation(email: str) -> dict[str, Any]: """ Analyzes email reputation using Abstract API's Email Reputation service. This function provides comprehensive email reputation analysis including deliverability, quality scoring, sender information, domain details, risk assessment, and breach history. It's designed to help improve delivery rates, clean email lists, and block fraudulent users. Args: email (str): The email address to analyze for reputation. Returns: dict[str, Any]: A dictionary containing comprehensive reputation analysis. The dictionary includes the following main sections: - "email_address" (str): The email address that was analyzed. - "email_deliverability" (dict): Deliverability information. - "status" (str): "deliverable", "undeliverable", or "unknown". - "status_detail" (str): Additional detail (e.g., "valid_email", "invalid_format"). - "is_format_valid" (bool): True if email follows correct format. - "is_smtp_valid" (bool): True if SMTP check was successful. - "is_mx_valid" (bool): True if domain has valid MX records. - "mx_records" (list): List of MX records for the domain. - "email_quality" (dict): Quality assessment information. - "score" (float): Confidence score between 0.01 and 0.99. - "is_free_email" (bool): True if from free provider (Gmail, Yahoo, etc.). - "is_username_suspicious" (bool): True if username appears auto-generated. - "is_disposable" (bool): True if from disposable email provider. - "is_catchall" (bool): True if domain accepts all emails. - "is_subaddress" (bool): True if uses subaddressing (user+label@domain.com). - "is_role" (bool): True if role-based address (info@, support@, etc.). - "is_dmarc_enforced" (bool): True if strict DMARC policy enforced. - "is_spf_strict" (bool): True if domain enforces strict SPF policy. - "minimum_age" (int|null): Estimated age of email address in days. - "email_sender" (dict): Sender information if available. - "first_name" (str|null): First name associated with email. - "last_name" (str|null): Last name associated with email. - "email_provider_name" (str|null): Email provider name (e.g., "Google"). - "organization_name" (str|null): Organization linked to email/domain. - "organization_type" (str|null): Type of organization (e.g., "company"). - "email_domain" (dict): Domain information. - "domain" (str): Domain part of the email. - "domain_age" (int|null): Age of domain in days. - "is_live_site" (bool|null): True if domain has active website. - "registrar" (str|null): Domain registrar name. - "registrar_url" (str|null): Registrar website URL. - "date_registered" (str|null): Domain registration date. - "date_last_renewed" (str|null): Last renewal date. - "date_expires" (str|null): Domain expiration date. - "is_risky_tld" (bool|null): True if top-level domain is considered risky. - "email_risk" (dict): Risk assessment. - "address_risk_status" (str): Risk level for the email address. - "domain_risk_status" (str): Risk level for the domain. - "email_breaches" (dict): Data breach information. - "total_breaches" (int|null): Number of known breaches. - "date_first_breached" (str|null): Date of first known breach. - "date_last_breached" (str|null): Date of most recent breach. - "breached_domains" (list): List of breached domains with dates. Example: >>> await check_email_reputation("benjamin.richard@abstractapi.com") { "email_address": "benjamin.richard@abstractapi.com", "email_deliverability": { "status": "deliverable", "status_detail": "valid_email", "is_format_valid": true, "is_smtp_valid": true, "is_mx_valid": true, "mx_records": ["gmail-smtp-in.l.google.com", ...] }, "email_quality": { "score": 0.8, "is_free_email": false, "is_username_suspicious": false, "is_disposable": false, "is_catchall": true, "is_subaddress": false, "is_role": false, "is_dmarc_enforced": true, "is_spf_strict": true, "minimum_age": 1418 }, "email_sender": { "first_name": "Benjamin", "last_name": "Richard", "email_provider_name": "Google", "organization_name": "Abstract API", "organization_type": "company" }, "email_domain": { "domain": "abstractapi.com", "domain_age": 1418, "is_live_site": true, "registrar": "NAMECHEAP INC", "registrar_url": "http://www.namecheap.com", "date_registered": "2020-05-13", "date_last_renewed": "2024-04-13", "date_expires": "2025-05-13", "is_risky_tld": false }, "email_risk": { "address_risk_status": "low", "domain_risk_status": "low" }, "email_breaches": { "total_breaches": 2, "date_first_breached": "2018-07-23T14:30:00Z", "date_last_breached": "2019-05-24T14:30:00Z", "breached_domains": [ {"domain": "apollo.io", "date_breached": "2018-07-23T14:30:00Z"}, {"domain": "canva.com", "date_breached": "2019-05-24T14:30:00Z"} ] } } Raises: ValueError: If the API key is not found in the environment variables. requests.exceptions.HTTPError: If the API request fails (e.g., 4xx or 5xx error). Exception: For any other unexpected errors. """
• server.py:16-19 (helper)

  Constants used by the tool: API endpoint URL and API key loaded from environment.
  ABSTRACT_API_KEY = os.getenv("ABSTRACT_API_KEY", "your_api_key_here") ABSTRACT_API_URL = "https://emailvalidation.abstractapi.com/v1/" PHONE_VALIDATION_API_URL = "https://phonevalidation.abstractapi.com/v1/" EMAIL_REPUTATION_API_URL = "https://emailreputation.abstractapi.com/v1/"