Role-Based Email Detection: Why B2B Campaigns Fail (And How to Fix It)

// Real-time role-based email detection
import { EmailCheckValidator } from '@email-check/app-js-sdk';

const validator = new EmailCheckValidator({
  apiKey: 'your-api-key',
  roleBasedDetection: {
    enabled: true,
    action: 'separate', // Options: 'block', 'separate', 'flag'
    includePattern: true, // Return the detected role pattern
    customPatterns: ['team-', 'group-', 'dept-'] // Add custom patterns
  }
});

// Validate email and check for role-based
document.getElementById('email').addEventListener('blur', async (e) => {
  const result = await validator.validate(e.target.value);

  if (result.isRoleBased) {
    handleRoleBasedEmail({
      email: result.email,
      pattern: result.rolePattern, // e.g., 'info@', 'sales@'
      recommendation: result.recommendation,
      severity: result.roleSeverity // 'high', 'medium', 'low'
    });
  } else if (result.isValid) {
    showSuccess('Valid individual email address');
  }
});

// Handle role-based email detection
function handleRoleBasedEmail(roleInfo) {
  if (roleInfo.severity === 'high') {
    // High-risk role emails (abuse@, noreply@, etc.)
    showWarning(`
      This is a role-based email (${roleInfo.pattern}).
      These addresses have 73% lower engagement rates.
      Consider requesting an individual contact instead.
    `);
  } else {
    // Lower-risk role emails (sales@, info@, etc.)
    showInfo(`
      You entered a departmental email (${roleInfo.pattern}).
      For best results, ask for your contact's direct email.
    `);
  }
}

import requests
from typing import Dict, List, Optional

class RoleBasedEmailDetector:
    # Comprehensive list of role-based patterns
    ROLE_PATTERNS = {
        # High severity (never convert)
        'abuse', 'complaint', 'spam', 'security', 'noreply', 'no-reply',
        'donotreply', 'do-not-reply', 'postmaster', 'hostmaster', 'webmaster',

        # Medium severity (low engagement)
        'admin', 'administrator', 'info', 'contact', 'inquiry', 'inquiries',
        'office', 'support', 'help', 'service', 'billing',

        # Low severity (departmental)
        'sales', 'marketing', 'hr', 'jobs', 'careers', 'finance',
        'legal', 'compliance', 'press', 'media', 'partnerships',

        # Technical/Operations
        'tech', 'technical', 'ops', 'operations', 'it', 'dev',
        'engineering', 'systems', 'network', 'dns'
    }

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://api.email-check.app/v1'

    def detect_role_based(self, email: str) -> Dict:
        """Detect if email is role-based and return severity"""

        local_part = email.split('@')[0].lower()

        # Check for direct pattern matches
        for pattern in self.ROLE_PATTERNS:
            if local_part == pattern or local_part.startswith(f'{pattern}.'):
                severity = self._get_severity(pattern)
                return {
                    'isRoleBased': True,
                    'pattern': pattern,
                    'severity': severity,
                    'recommendation': self._get_recommendation(severity)
                }

        # Check for compound patterns (e.g., 'sales-team', 'hr-dept')
        for pattern in self.ROLE_PATTERNS:
            if pattern in local_part:
                severity = self._get_severity(pattern)
                return {
                    'isRoleBased': True,
                    'pattern': pattern,
                    'severity': severity,
                    'recommendation': self._get_recommendation(severity),
                    'matchType': 'compound'
                }

        return {
            'isRoleBased': False,
            'pattern': None,
            'severity': None
        }

    def _get_severity(self, pattern: str) -> str:
        """Determine severity level for role pattern"""
        high_severity = {'abuse', 'noreply', 'spam', 'complaint', 'security'}
        medium_severity = {'admin', 'info', 'contact', 'support', 'billing'}

        if pattern in high_severity:
            return 'high'
        elif pattern in medium_severity:
            return 'medium'
        else:
            return 'low'

    def _get_recommendation(self, severity: str) -> str:
        """Get action recommendation based on severity"""
        if severity == 'high':
            return 'block'
        elif severity == 'medium':
            return 'separate'
        else:
            return 'flag'

    def validate_with_role_detection(self, email: str) -> Dict:
        """Validate email and include role-based detection"""

        # Check for role-based pattern
        role_check = self.detect_role_based(email)

        # Validate the email normally
        response = requests.post(
            f'{self.base_url}/validate',
            headers={'Authorization': f'Bearer {self.api_key}'},
            json={'email': email},
            timeout=5
        )

        validation = response.json()

        # Combine results
        return {
            **validation,
            'roleBased': role_check,
            'recommendedAction': self._get_recommended_action(role_check, validation)
        }

    def _get_recommended_action(self, role_check: Dict, validation: Dict) -> str:
        """Determine recommended action based on role detection"""
        if not role_check['isRoleBased']:
            return 'accept'

        severity = role_check['severity']

        if severity == 'high':
            return 'reject'
        elif severity == 'medium':
            return 'segment'
        else:
            return 'accept_with_flag'

# Usage example
detector = RoleBasedEmailDetector('your-api-key')

# Check individual email
result = detector.detect_role_based('abuse@company.com')
print(f"Role-based: {result['isRoleBased']}")
print(f"Pattern: {result.get('pattern')}")
print(f"Severity: {result.get('severity')}")
print(f"Recommendation: {result.get('recommendation')}")

# Validate with role detection
full_result = detector.validate_with_role_detection('info@prospect.com')
print(f"Valid: {full_result.get('isValid')}")
print(f"Action: {full_result.get('recommendedAction')}")