Email Verification in AI Agent Pipelines

# Client configuration — Claude Desktop, Cursor, or any
# MCP client that speaks Streamable HTTP
{
  "mcpServers": {
    "email-check": {
      "type": "http",
      "url": "https://api.email-check.app/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

# Tools your agent discovers after connecting:
# - account_whoami — free identity probe; confirms which
#   account the key resolves to before you spend credits
# - email_validate — full validation: format, MX, optional
#   SMTP mailbox probe, disposable/free detection, name
#   detection, and domain suggestions

{
  "email": "lead@example.com",   // required
  "verifyMx": true,              // check the domain has MX records
  "verifySmtp": true,            // probe the SMTP server for the
                                 // mailbox (slower)
  "detectName": true,            // probable first/last name from
                                 // the local part
  "suggestDomain": true,         // correction for common domain
                                 // typos
  "checkDomainAge": true,        // domain age in days
  "checkDomainRegistration": false, // domain registration data
  "smtpDebug": false,            // SMTP transcript summary
  "timeout": 2000                // per-check timeout in ms,
                                 // default 2000, max 10000
}

POST https://api.email-check.app/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "email_validate",
    "arguments": {
      "email": "lead@example.com",
      "verifyMx": true,
      "verifySmtp": true,
      "detectName": true,
      "suggestDomain": true,
      "timeout": 5000
    }
  }
}

# Response (abridged):
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "structuredContent": {
      "email": "lead@example.com",
      "validFormat": true,
      "validMx": true,
      "validSmtp": true,
      "isDisposable": false,
      "isFree": false,
      "detectedName": { "firstName": "Lead", "confidence": 0.62 },
      "domainSuggestion": null
    }
  }
}

// Registering the REST endpoint as a custom agent tool
const tools = [
  {
    name: "email_validate",
    description: "Validate an email address. Returns format, MX," +
      "SMTP mailbox, disposable and free-provider detection, name" +
      "detection, and domain typo suggestions.",
    parameters: {
      type: "object",
      properties: {
        email: {
          type: "string",
          format: "email",
          description: "Email to validate"
        }
      },
      required: ["email"]
    },
    execute: async ({ email }) => {
      const params = new URLSearchParams({
        email,
        verifyMx: "true",
        verifySmtp: "true",
        suggestDomain: "true"
      });
      const response = await fetch(
        `https://api.email-check.app/v1-get-email-details?${params}`,
        {
          headers: {
            "x-api-key": process.env.EMAIL_CHECK_API_KEY
          }
        }
      );
      return response.json();
    }
  }
];

// CRM hygiene agent — prompt template
const CRM_HYGIENE_PROMPT = `
You are a CRM data hygiene agent. Your task:

1. Fetch all contacts modified in the last 7 days from the CRM
   using the fetch_contacts tool.
2. For each contact with an email field, call email_validate
   with verifyMx and verifySmtp enabled.
3. Based on the result:
   - validFormat && validMx && validSmtp && !isDisposable:
     update email_status to "verified"
   - validFormat === false, or validSmtp === false after a
     retry: update email_status to "invalid", flag for removal
   - validSmtp === null (inconclusive): update email_status to
     "flagged", add a note with the reason, schedule one retry
   - domainSuggestion with a suggested domain: record the
     suggestion for manual review, do not rewrite silently
4. After processing, write a summary report:
   - Total contacts processed
   - Breakdown by outcome (verified / invalid / flagged)
   - Domains with highest failure rates
   - Contacts requiring manual review

Use the update_contact tool to modify CRM records.
Use the write_report tool to create the summary.`;

// Agent handles all logic autonomously — no pre-defined
// branching needed. If it encounters an edge case (e.g.,
// a catch-all domain with 100+ contacts — visible through
// smtpDebug.isCatchAll when requested), it can decide
// to flag it instead of processing each one individually.

// Signup fraud screening agent
const SIGNUP_SCREEN_PROMPT = `
You are a signup fraud screening agent. When a new signup
arrives:

1. Call email_validate with the signup email, verifyMx true,
   verifySmtp true, suggestDomain true, checkDomainAge true.
2. Apply these rules:
   - isDisposable === true -> BLOCK and log
   - validFormat === false -> BLOCK and request correction
   - validSmtp === false -> BLOCK and log
   - domainAge.ageInDays < 30 -> FLAG for manual review
     (brand-new domain)
   - isFree === true -> FLAG per your account policy
2b. A domainSuggestion (e.g. gmial.com -> gmail.com) means a
    likely typo: ask the user to confirm the corrected
    address, then validate the correction.
3. Track patterns: if 3+ signups from the same disposable
   domain appear in the last hour, escalate to the security
   team using the send_alert tool.

Use approve_signup, block_signup, or flag_signup tools.
Use the log_event tool for audit trail.`;

// The agent's advantage: it can correlate signals across
// multiple signups, adjust its thresholds based on traffic
// patterns, and provide natural-language explanations for
// each decision when audited.

// B2B lead enrichment agent
const LEAD_ENRICH_PROMPT = `
You are a B2B lead enrichment agent. Process the
provided prospect list:

1. For each prospect, call email_validate with verifyMx,
   verifySmtp, detectName, and suggestDomain enabled.
2. Classify each lead:
   Tier 1: validFormat && validMx && validSmtp
     && !isDisposable && !isFree
   Tier 2: validMx && validSmtp && !isDisposable
     (may include free providers)
   Tier 3: validSmtp === null or unknown outcome
   Reject: validFormat === false, validSmtp === false,
     or isDisposable === true
3. For Tier 1 leads: push to Salesforce using create_lead
   with email_verified = true. Attach detectedName when
   confidence is high.
4. For Tier 2 leads: push with email_verified = "partial"
   and add a note about the free-provider signal.
5. For Tier 3 leads: push with email_verified = "uncertain"
   and schedule re-verification in 7 days.
6. Reject leads: log to a separate rejected list.
7. Write a summary: total processed, tier distribution,
   domains with most Tier 1 leads, top rejections.`;

// Agent advantage over Clay/Zapier: the agent can
// re-prioritize leads mid-batch if it notices patterns
// (e.g., all emails from a specific domain are failing),
// and it can explain its decisions in a follow-up
// conversation.

// Pre-campaign verification agent
const PRE_CAMPAIGN_PROMPT = `
You are a pre-campaign verification agent. A campaign
is scheduled to send to N recipients. Your job:

1. Fetch the recipient list using fetch_campaign_list.
2. Validate every email using email_validate with
   verifyMx and verifySmtp enabled.
3. Segment results:
   - SEND: validFormat && validMx && validSmtp
     && !isDisposable
   - CORRECT_AND_SEND: domainSuggestion present — verify
     the corrected domain before sending
   - HOLD: validSmtp === null or smtpDebug.isCatchAll
     === true (accept-all evidence)
   - REMOVE: validFormat === false, validSmtp === false,
     or isDisposable === true
4. Apply corrections for the CORRECT_AND_SEND group.
5. Update the campaign list: add SEND group, hold the
   HOLD group, remove the REMOVE group.
6. Generate a deliverability report:
   - Original list size vs clean list size
   - % of emails corrected
   - Estimated bounce prevention
   - Recommendation: proceed / delay / abort

Use update_campaign_list and generate_report tools.`;

// The agent provides a recommendation, not just data.
// Marketing teams get an actionable assessment instead
// of a raw validation dump.

// Bulk processing helper — used by agent pipelines
const batchSize = 50;
const delayMs = 200;

async function validateBatch(emails) {
  const results = [];
  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);
    const promises = batch.map(email =>
      fetch(
        `https://api.email-check.app/v1-get-email-details?${new URLSearchParams({
          email,
          verifyMx: "true",
          verifySmtp: "true",
          suggestDomain: "true"
        })}`,
        {
          headers: {
            "x-api-key": process.env.EMAIL_CHECK_API_KEY
          }
        }
      ).then(r => r.json())
    );
    const batchResults = await Promise.all(promises);
    results.push(...batchResults);

    if (i + batchSize < emails.length) {
      await new Promise(r => setTimeout(r, delayMs));
    }
  }
  return results;
}

// Usage in agent: "Validate these 500 leads in batches."
// Agent calls this helper, gets results, then proceeds
// with classification and CRM updates.
// For very large lists, prefer the bulk CSV checker over
// per-address calls.

# MCP endpoint — JSON-RPC 2.0 over Streamable HTTP
POST https://api.email-check.app/mcp
Accept: application/json, text/event-stream
x-api-key: YOUR_API_KEY

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"email_validate",
  "arguments":{"email":"user@domain.com","verifyMx":true,
    "verifySmtp":true}
}}

# Direct REST equivalent
GET https://api.email-check.app/v1-get-email-details
  ?email=user@domain.com&verifyMx=true&verifySmtp=true
x-api-key: YOUR_API_KEY

# Response fields (both surfaces return the same shape):
{
  "email": "user@domain.com",
  "validFormat": true,   // address passes format rules
  "validMx": true,       // nullable: null = not requested/unknown
  "validSmtp": true,     // nullable: null = inconclusive probe
  "isDisposable": false, // true = temporary/throwaway provider
  "isFree": false,       // true = gmail.com, yahoo.com, etc.
  "detectedName": { "firstName": "User", "confidence": 0.7 },
  "domainSuggestion": null, // { original, suggested } on typos
  "domainAge": { "ageInDays": 3650, "isValid": true },
  "smtpDebug": { "responseCode": 250, "isCatchAll": false }
}

# Billing: 1 credit per tool call. account_whoami is free.
# HTTP 402 = out of credits -> https://email-check.app/pricing