n8n-nodes-contact-validator 1.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sinch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Chris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,525 @@
+# Contact Validator for n8n
+
+[![NPM Version](https://img.shields.io/npm/v/n8n-nodes-contact-validator)](https://www.npmjs.com/package/n8n-nodes-contact-validator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **Omnichannel Quality & Continuity for n8n Workflows**
+> 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
+
+### Three Powerful n8n Nodes
+
+1. **[Number Lookup](#number-lookup-node)** - Validate and enrich phone number data
+2. **[Email Validation](#email-validation-node)** - Validate email addresses
+3. **[Voice](#voice-node)** - Execute voice calls with text-to-speech
+
+### Three Production-Ready Workflow Templates
+
+1. **[Smart Multi-Channel Campaign](#workflow-1-smart-multi-channel-campaign)** - Intelligent outreach with quality gates and voice escalation
+2. **[Event Registration Quality Control](#workflow-2-event-registration-quality-control)** - Real-time validation and automated event reminders
+3. **[Support Ticket Escalation](#workflow-3-support-ticket-escalation)** - Priority-based contact escalation with continuity guarantee
+
+## Quick Start
+
+### Installation
+
+```bash
+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](https://dashboard.sinch.com/signup)
+  - Project ID
+  - API Key & Secret
+  - Service Plan ID (for Voice API)
+
+- **Mailgun Account** - [Sign up here](https://signup.mailgun.com/)
+  - 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
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+---
+
+### 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
+
+```json
+{
+  "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
+
+The workflow templates are included with this package. After installing `n8n-nodes-contact-validator`, you can find them at:
+
+**Location:** `node_modules/n8n-nodes-contact-validator/workflows/templates/`
+
+**To import a template:**
+
+1. Navigate to the template file location above
+2. Open the desired `.json` file and copy its contents
+3. In n8n, click the **"+"** button in the top right
+4. Select **"Import from File"** or **"Import from URL"**
+5. Paste the JSON content
+6. Click **"Import"**
+7. Configure your credentials in the imported workflow nodes
+
+**Available Templates:**
+- `multi-channel-campaign.json`
+- `event-registration-quality.json`
+- `support-escalation-continuity.json`
+
+---
+
+### 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
+
+
+## Examples
+
+### Example 1: Validate Phone Before Sending SMS
+
+```json
+{
+  "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
+
+```json
+{
+  "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
+
+```json
+{
+  "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](LICENSE) file for details.
+
+---
+
+**Built with ❤️**

package/dist/credentials/SinchApi.credentials.d.ts

@@ -0,0 +1,9 @@
+import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class SinchApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/SinchApi.credentials.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SinchApi = void 0;
+class SinchApi {
+    constructor() {
+        this.name = 'sinchApi';
+        this.displayName = 'Sinch API';
+        this.documentationUrl = 'https://developers.sinch.com/docs/numbers/';
+        this.properties = [
+            {
+                displayName: 'Project ID',
+                name: 'projectId',
+                type: 'string',
+                default: '',
+                required: true,
+                description: 'Your Sinch Project ID',
+            },
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your Sinch API Key (Key ID)',
+            },
+            {
+                displayName: 'API Secret',
+                name: 'apiSecret',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your Sinch API Secret (Key Secret)',
+            },
+            {
+                displayName: 'Service Plan ID',
+                name: 'servicePlanId',
+                type: 'string',
+                default: '',
+                description: 'Your Sinch Service Plan ID (optional, for Voice API)',
+            },
+            {
+                displayName: 'Region',
+                name: 'region',
+                type: 'options',
+                options: [
+                    {
+                        name: 'United States',
+                        value: 'us',
+                    },
+                    {
+                        name: 'Europe',
+                        value: 'eu',
+                    },
+                    {
+                        name: 'Asia Pacific',
+                        value: 'ap',
+                    },
+                ],
+                default: 'us',
+                description: 'The region for your Sinch API endpoint',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                auth: {
+                    username: '={{$credentials.apiKey}}',
+                    password: '={{$credentials.apiSecret}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '=https://numbers.api.sinch.com/v1/projects/{{$credentials.projectId}}',
+                url: '/availableNumbers',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.SinchApi = SinchApi;

package/dist/credentials/SinchMailgunApi.credentials.d.ts

@@ -0,0 +1,9 @@
+import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class SinchMailgunApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}