Email Verification in AI Agent Pipelines

// MCP server tool definition — email verification
{
  "name": "verify_email",
  "description": "Validate an email address for deliverability, " +
    "disposable status, risk score, and typo suggestions. " +
    "Returns a structured result with a recommendation " +
    "(ACCEPT, REJECT, REVIEW, CORRECT).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "email": {
        "type": "string",
        "format": "email",
        "description": "The email address to validate"
      }
    },
    "required": ["email"]
  }
}

// MCP server handler (TypeScript)
async function handleVerifyEmail(args: { email: string }) {
  const response = await fetch(
    'https://api.email-check.app/v1/validate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.EMAIL_CHECK_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ email: args.email })
    }
  );

  const result = await response.json();
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        email: result.email,
        status: result.status,
        disposable: result.disposable,
        roleBased: result.roleBased,
        freeProvider: result.freeProvider,
        riskScore: result.riskScore,
        suggestion: result.suggestion,
        recommendation: classifyResult(result)
      }, null, 2)
    }]
  };
}

function classifyResult(result) {
  if (result.disposable) return 'REJECT: disposable email';
  if (result.status === 'undeliverable') return 'REJECT: invalid mailbox';
  if (result.riskScore > 80) return 'REVIEW: high risk score';
  if (result.roleBased) return 'REVIEW: role-based address';
  if (result.suggestion) return `CORRECT: ${result.suggestion}`;
  if (result.status === 'deliverable') return 'ACCEPT: verified';
  return 'REVIEW: uncertain status';
}

// Agent framework tool registration
const tools = [
  {
    name: "verify_email",
    description: "Validate an email address. Returns " +
      "deliverability, disposable detection, risk score, " +
      "and typo correction suggestions.",
    parameters: {
      type: "object",
      properties: {
        email: {
          type: "string",
          format: "email",
          description: "Email to validate"
        }
      },
      required: ["email"]
    },
    execute: async ({ email }) => {
      const res = await fetch(
        'https://api.email-check.app/v1/validate',
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${process.env.EMAIL_CHECK_API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ email })
        }
      );
      return res.json();
    }
  }
];

// Agent receives this tool and decides when to call it.
// Example prompt: "Review these 50 leads. Flag invalid
// emails, correct typos, and add verified contacts to
// Salesforce. Skip disposable addresses."
//
// The agent will:
// 1. Parse the email from each lead record
// 2. Call verify_email for each one
// 3. Read the recommendation (ACCEPT/REJECT/REVIEW/CORRECT)
// 4. Take the appropriate action based on the result

// 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 verify_email.
3. Based on the result:
   - ACCEPT (deliverable, low risk): update email_status to
     "verified", set email_risk_score
   - REJECT (undeliverable or disposable): update email_status
     to "invalid", flag for removal
   - REVIEW (high risk or uncertain): update email_status to
     "flagged", add a note with the reason
   - CORRECT (typo detected): apply the suggestion, verify
     the corrected email, then update
4. After processing, write a summary report:
   - Total contacts processed
   - Breakdown by recommendation type
   - 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), 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 verify_email with the signup email.
2. Apply these rules:
   - disposable == true  → BLOCK and log
   - status == "undeliverable" → BLOCK and log
   - riskScore > 80 → FLAG for manual review
   - freeProvider && riskScore > 50 → FLAG for review
   - roleBased → FLAG (legitimate but not a person)
3. If the email has a suggestion (typo), verify the
   suggested correction. If valid, auto-correct the
   email and approve the signup with the corrected address.
4. 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 risk threshold 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 verify_email.
2. Classify each lead:
   Tier 1: deliverable + !roleBased + !freeProvider
           + riskScore < 30
   Tier 2: deliverable + riskScore < 50
           (may include roleBased or freeProvider)
   Tier 3: accept_all or unknown status
   Reject: undeliverable or disposable
3. For Tier 1 leads: push to Salesforce using
   create_lead with email_verified=true.
4. For Tier 2 leads: push with email_verified="partial"
   and add a note about the risk 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 verify_email.
3. Segment results:
   - SEND: deliverable, riskScore < 50, not disposable
   - CORRECT_AND_SEND: deliverable with typo suggestion,
     verify the correction first
   - HOLD: riskScore >= 50 or status uncertain
   - REMOVE: undeliverable or disposable
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 verifyBatch(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/validate', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.EMAIL_CHECK_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ email })
      }).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.

# Email Verification API — used by all agent pipelines
POST https://api.email-check.app/v1/validate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"email": "user@domain.com"}

# Response:
{
  "email": "user@domain.com",
  "status": "deliverable",     // deliverable | undeliverable | unknown | accept_all
  "disposable": false,         // true = temporary/throwaway email
  "roleBased": false,          // true = info@, sales@, admin@
  "freeProvider": false,       // true = gmail.com, yahoo.com, etc.
  "riskScore": 12,             // 0-100, lower = safer
  "suggestion": null           // "corrected@domain.com" or null (typo)
}