Contact Validator for n8n

Validate contacts, intelligently route messages, and ensure critical communications reach your customers through the best available channel.

Overview

Contact Validator brings enterprise-grade contact validation and intelligent multi-channel communication to n8n automation workflows. This package includes three powerful nodes and three ready-to-use workflow templates that help you:

• Validate phone numbers before sending SMS or making calls
• Verify email addresses to reduce bounce rates and improve deliverability
• Execute voice calls for critical notifications and escalations
• Intelligently route messages based on contact quality and channel availability
• Ensure message delivery through automatic channel escalation

What's Included

Four Powerful n8n Nodes

1. Number Lookup - Validate and enrich phone number data
2. Email Validation - Validate email addresses
3. SMS - Send SMS messages via Sinch Conversations API
4. Voice - Execute voice calls with text-to-speech

Three Production-Ready Workflow Templates

1. Smart Multi-Channel Campaign - Intelligent outreach with quality gates and voice escalation
2. Event Registration Quality Control - Real-time validation and automated event reminders
3. Support Ticket Escalation - Priority-based contact escalation with continuity guarantee

Quick Start

🚀 Quick Access to Templates

Fastest way to get started:

1. Install the package (see Installation below)
2. Import a template directly in n8n:
   • Click "+" → "Import from URL"
   • Use GitHub raw URLs (see WORKFLOW_TEMPLATES.md)
3. Configure credentials and start using!

📘 Full template guide: WORKFLOW_TEMPLATES.md

Installation

npm install n8n-nodes-contact-validator

Or install directly in n8n:

1. Go to Settings → Community Nodes
2. Search for n8n-nodes-contact-validator
3. Click Install

Prerequisites

You'll need the following API credentials:

• Sinch Account - Sign up here

  • Project ID
  • API Key & Secret
  • Service Plan ID (for Voice API)

• Mailgun Account - Sign up here

  • API Key
  • Domain

Configuration

1. Add API Credentials

1. In n8n, go to Credentials → New
2. Select Sinch API (for Number Lookup and Voice nodes)
3. Enter your credentials:
   • Project ID
   • API Key (Key ID)
   • API Secret (Key Secret)
   • Service Plan ID (optional, for Voice)
   • Region (US/EU/AP)
4. Click Save

2. Add Mailgun API Credentials

1. In n8n, go to Credentials → New
2. Select Mailgun API (for Email Validation node)
3. Enter your credentials:
   • API Key
   • Domain
   • Region (US/EU)
4. Click Save

Node Documentation

Number Lookup Node

Validate and enrich phone numbers with intelligence about reachability, line type, carrier, and risk factors.

Operations

Number Lookup

• Validate phone number format and active status
• Retrieve carrier information
• Determine line type (mobile, landline, VoIP, toll-free)
• Country and region identification
• Porting status

Reachability Check

• Real-time reachability assessment
• SMS capability detection
• Voice capability detection
• Risk scoring

Bulk Lookup

• Process multiple numbers in batch
• Return aggregated results

Example Output

{
  "phoneNumber": "+14155551234",
  "countryCode": "US",
  "numberType": "mobile",
  "carrier": "T-Mobile USA",
  "reachable": true,
  "smsCapable": true,
  "voiceCapable": true,
  "riskScore": 0.12,
  "ported": false,
  "validation": {
    "valid": true,
    "formatted": "+14155551234"
  }
}

Use Cases

• Pre-send validation for SMS campaigns
• Contact list hygiene and cleanup
• Phone number enrichment for CRM
• Fraud detection and risk assessment

---

Email Validation Node

Validate email addresses, assess deliverability risk, and prevent sending to invalid or risky addresses.

Operations

Single Email Validation

• Format validation (RFC 5322)
• Domain verification (MX records, DNS)
• Mailbox verification
• Risk assessment (disposable, role-based, catch-all)
• Deliverability score
• Typo suggestions

Bulk Email Validation

• Process lists of emails
• Return aggregated risk metrics

Domain Validation

• Check domain reputation
• Verify domain configuration
• MX record validation

Example Output

{
  "email": "user@example.com",
  "valid": true,
  "mailboxVerified": true,
  "disposable": false,
  "roleBasedAddress": false,
  "catchAll": false,
  "didYouMean": null,
  "riskScore": 0.08,
  "deliverabilityScore": 0.95,
  "domainReputation": "high",
  "reasons": [],
  "flagged": false
}

Use Cases

• Pre-send validation for email campaigns
• Form validation and real-time feedback
• Email list cleaning and verification
• Reduce bounce rates and improve sender reputation

---

SMS Node

Send SMS messages via Sinch Conversations API for notifications, alerts, and two-way communication.

Operations

Send SMS

• Send text messages to phone numbers
• Support for E.164 phone number format
• Delivery status tracking
• Message templates

Example Output

{
  "messageId": "msg-1234567890",
  "to": "+14155551234",
  "status": "sent",
  "timestamp": "2025-01-13T10:30:00Z"
}

Use Cases

• Transactional notifications
• Two-factor authentication codes
• Appointment reminders
• Marketing campaigns
• Customer support messages

---

Voice Node

Execute voice calls for escalation, notification, and continuity scenarios.

Operations

Make Call

• Outbound call to number
• Custom audio file playback
• Call recording

Text-to-Speech Call

• Convert text to speech
• Multiple voice options and languages
• Dynamic message generation

Conference Call

• Create conference room
• Add participants dynamically

Check Call Status

• Query call status
• Retrieve call logs and recordings

Example Output

{
  "callId": "1ce0ffee-ca11-ca11-ca11-abcdef123456",
  "to": "+14155551234",
  "from": "+14155556789",
  "status": "completed",
  "duration": 42,
  "startTime": "2025-01-13T10:30:00Z",
  "endTime": "2025-01-13T10:30:42Z",
  "recordingUrl": "https://...",
  "cost": 0.012
}

Use Cases

• Critical alert notifications
• Two-factor authentication via voice
• Appointment reminders
• Support ticket escalation
• Emergency communications

Workflow Templates

How to Import Workflow Templates

⭐ Recommended: Import from GitHub URL

The easiest way is to import directly from GitHub:

1. In n8n, click the "+" button (top right)
2. Select "Import from URL"
3. Paste one of these URLs (replace YOUR_USERNAME with your GitHub username):

Multi-Channel Campaign:

https://raw.githubusercontent.com/YOUR_USERNAME/sinch-quality-continuity-suite-n8n/main/workflows/templates/multi-channel-campaign.json

Event Registration Quality:

https://raw.githubusercontent.com/YOUR_USERNAME/sinch-quality-continuity-suite-n8n/main/workflows/templates/event-registration-quality.json

Support Escalation Continuity:

https://raw.githubusercontent.com/YOUR_USERNAME/sinch-quality-continuity-suite-n8n/main/workflows/templates/support-escalation-continuity.json

Alternative: Download and Import

1. Download the template from GitHub (click "Raw" button)
2. In n8n, click "+" → "Import from File"
3. Select the downloaded JSON file
4. Click "Import"

After Importing

1. Configure credentials in each node (Sinch API, Mailgun API, etc.)
2. Set environment variables if needed (SINCH_FROM_NUMBER, etc.)
3. Customize message templates and timing
4. Test the workflow with sample data

📘 Full guide: See WORKFLOW_TEMPLATES.md for detailed instructions

Available Templates:

• multi-channel-campaign.json - Intelligent outreach with quality gates
• event-registration-quality.json - Event management with automated reminders
• support-escalation-continuity.json - Priority-based support escalation

---

Workflow 1: Smart Multi-Channel Campaign

Use Case: Validate contacts before sending, intelligently route messages based on channel capability, and escalate to voice when critical messages aren't engaged.

How It Works:

1. Contact Validation - Validates both phone and email in parallel
2. Quality Gate - Routes based on validation results:
   • Route A: High quality (valid email + SMS-capable mobile)
   • Route B: Email only (invalid/landline phone)
   • Route C: Phone only (invalid email)
   • Route D: Suppress (both invalid)
3. Progressive Engagement (Route A):
   • Send email → Wait 24h
   • If not opened → Send SMS → Wait 48h
   • If still no engagement → Voice call
4. CRM Update - Track validation results and engagement

Benefits:

• Reduce wasted messaging costs by 30-50%
• Improve engagement rates through channel optimization
• Automatic escalation ensures critical messages are seen
• Complete audit trail of contact attempts

---

Workflow 2: Event Registration Quality Control

Use Case: Enhance event registration with real-time validation and automated continuity to ensure attendees receive critical updates.

How It Works:

1. Real-Time Validation - Validates contact info at registration
2. Quality Check - Accepts valid registrations or requests correction
3. Confirmation - Sends email + SMS confirmation
4. Reminder Sequence:
   • Day -7: Email reminder
   • Day -3: SMS reminder
   • Day -1: Email + SMS
   • Day 0 (2h before): Voice call if no check-in
5. Post-Event Follow-up - Survey and engagement tracking

Benefits:

• Prevent no-shows with multi-channel reminders
• Ensure all attendees receive event updates
• Improve data quality for future events
• Higher attendance and engagement rates

---

Workflow 3: Support Ticket Escalation

Use Case: Automatically escalate high-priority support tickets through the most reliable channels with continuity guarantee.

How It Works:

1. Contact Validation - Validates customer contact methods
2. Priority Assessment - Routes based on ticket priority

P0/P1 Immediate Escalation:

• Attempt 1: Voice call → Wait 5min
• Attempt 2: SMS + Email → Wait 15min
• Attempt 3: Call alternate contact + Page on-call team

P2/P3 Standard Flow:

• Email → Wait 2h
• If no response → SMS → Wait 4h
• If no response → Voice call

3. Tracking - Log all attempts and update customer profile
4. Feedback Loop - Track which channels lead to fastest response

Benefits:

• Guaranteed contact for critical issues
• Reduced resolution time
• Improved customer satisfaction
• Optimized support team efficiency

Best Practices

Phone Number Validation

1. Always use E.164 format - International format with country code (e.g., +14155551234)
2. Validate before sending - Check SMS capability before sending SMS
3. Handle errors gracefully - Use "Continue on Error" for bulk operations
4. Cache results - Store validation results in your CRM to avoid repeated lookups

Email Validation

1. Set appropriate risk thresholds - 0.5 is recommended for marketing, 0.7 for transactional
2. Use suggestions - Present "Did you mean?" suggestions to users for typos
3. Validate at collection - Validate emails when users submit forms
4. Suppress high-risk emails - Don't send to disposable or high-risk addresses

Voice Calls

1. Keep messages concise - 30-60 seconds maximum
2. Use appropriate voice - Match voice to your brand and audience
3. Record important calls - Enable recording for compliance and quality
4. Set reasonable timeouts - Don't let calls run indefinitely
5. Provide callback options - Always include a callback number

Workflow Design

1. Fail gracefully - Use "Continue on Error" to prevent workflow failures
2. Log everything - Track all contact attempts in your CRM
3. Respect preferences - Honor customer channel preferences
4. Test thoroughly - Use sandbox credentials for testing
5. Monitor costs - Track API usage and set budget alerts

API Rate Limits

• Number Lookup: 100 requests/second
• Email Validation: 100 requests/hour (free tier), higher on paid plans
• Voice: 10 calls/second per account

Consider implementing rate limiting and queueing for bulk operations.

Troubleshooting

Common Issues

"Invalid credentials" error

• Verify your API Key and Secret are correct
• Check that you've selected the correct region
• Ensure credentials are saved in n8n

"Phone number invalid" error

• Use E.164 format (+country code + number)
• Remove spaces, hyphens, and parentheses
• Ensure country code is included

"Email validation failed" error

• Check that the email address is properly formatted
• Verify your Mailgun domain is verified
• Check your Mailgun API key is active

Voice calls not connecting

• Verify your Service Plan ID is correct
• Ensure the "from" number is a valid phone number from your provider
• Check that the "to" number can receive calls

Package not loading after update

• Clear n8n cache: Remove node_modules/n8n-nodes-contact-validator from ~/.n8n/custom
• Clear npm cache: npm cache clean --force
• Reinstall: npm install n8n-nodes-contact-validator@latest
• Restart n8n

Examples

Example 1: Validate Phone Before Sending SMS

{
  "nodes": [
    {
      "name": "Number Lookup",
      "type": "numberLookup",
      "parameters": {
        "operation": "reachability",
        "phoneNumber": "={{ $json.phone }}",
        "checkSms": true
      }
    },
    {
      "name": "IF SMS Capable",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "boolean": [{"value1": "={{ $json.smsCapable }}", "value2": true}]
        }
      }
    },
    {
      "name": "Send SMS",
      "type": "n8n-nodes-base.twilio",
      "parameters": {
        "operation": "send",
        "toNumber": "={{ $json.phoneNumber }}",
        "message": "Your verification code is 123456"
      }
    }
  ]
}

Example 2: Email Validation with Suggestions

{
  "nodes": [
    {
      "name": "Email Validation",
      "type": "emailValidation",
      "parameters": {
        "operation": "validate",
        "emailAddress": "={{ $json.email }}",
        "returnSuggestions": true,
        "riskThreshold": 0.6
      }
    },
    {
      "name": "Check Valid",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "boolean": [{"value1": "={{ $json.valid }}", "value2": true}]
        }
      }
    },
    {
      "name": "Send to Valid",
      "type": "n8n-nodes-base.emailSend"
    },
    {
      "name": "Suggest Correction",
      "type": "n8n-nodes-base.webhook",
      "parameters": {
        "responseData": "={{ {suggestion: $json.didYouMean} }}"
      }
    }
  ]
}

Example 3: Progressive Voice Escalation

{
  "nodes": [
    {
      "name": "Send Email",
      "type": "n8n-nodes-base.emailSend"
    },
    {
      "name": "Wait 1 Hour",
      "type": "n8n-nodes-base.wait",
      "parameters": {"amount": 1, "unit": "hours"}
    },
    {
      "name": "Check Opened",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "boolean": [{"value1": "={{ $json.opened }}", "value2": false}]
        }
      }
    },
    {
      "name": "Voice Call",
      "type": "programmableVoice",
      "parameters": {
        "operation": "ttsCall",
        "toNumber": "={{ $json.phone }}",
        "message": "This is an urgent notification. Please check your email.",
        "voice": "en-US-female"
      }
    }
  ]
}

License

MIT License - see LICENSE file for details.

---

Built with ❤️