https://mobileaws.atlassian.net/browse/CLOUD-2744

README.md

@@ -138,6 +138,42 @@ client.contact.set_do_not_text(false, phone: '+15551234567')
 client.contact.set_do_not_text(true, contact_id: 'contact-abc-123')
 ```
 
+### Contact Validator
+
+Validate email addresses and phone numbers.
+
+> Bulk endpoints accept up to 50 contacts per request and are processed server-side in chunks.
+
+```ruby
+require 'ccai'
+
+# Initialize the client
+client = CCAI.new(
+  client_id: 'YOUR-CLIENT-ID',
+  api_key: 'YOUR-API-KEY'
+)
+
+# Validate a single email
+email_result = client.contact_validator.validate_email('user@example.com')
+puts "Status: #{email_result['status']}" # "valid" | "invalid" | "risky"
+
+# Validate multiple emails (up to 50, processed server-side in chunks)
+bulk_emails = client.contact_validator.validate_emails(['user@example.com', 'bad@invalid.xyz'])
+puts "Total: #{bulk_emails['summary']['total']}" # 2
+puts "Valid: #{bulk_emails['summary']['valid']}"  # 1
+
+# Validate a single phone number
+phone_result = client.contact_validator.validate_phone('+15551234567', country_code: 'US')
+puts "Status: #{phone_result['status']}" # "valid" | "invalid" | "landline"
+
+# Validate multiple phone numbers (up to 50, processed server-side in chunks)
+bulk_phones = client.contact_validator.validate_phones([
+  { phone: '+15551234567' },
+  { phone: '+15559876543', countryCode: 'US' }
+])
+puts "Landline: #{bulk_phones['summary']['landline']}" # 1
+```
+
 ### Webhooks
 
 ```ruby
@@ -356,6 +392,7 @@ ccai --type email --client-id YOUR-CLIENT-ID --api-key YOUR-API-KEY \
 - Send MMS messages with images (automatic S3 upload)
 - Send email campaigns with HTML content
 - Manage contact opt-out preferences (set_do_not_text)
+- Validate email addresses (valid/invalid/risky) and phone numbers (valid/invalid/landline)
 - Manage webhooks: register, list, update, delete
 - Webhook signature verification (HMAC-SHA256 with Base64 encoding)
 - Template variable substitution (`${firstName}`, `${lastName}`)

lib/ccai/client.rb

@@ -10,6 +10,7 @@
 require 'ccai/email/email_service'
 require 'ccai/webhook/webhook_service'
 require 'ccai/contact/contact_service'
+require 'ccai/contact_validator/contact_validator_service'
 
 module CCAI
   # Configuration for the CCAI client
@@ -56,7 +57,7 @@ def initialize(client_id:, api_key:, use_test_environment: false, base_url: nil,
 
   # Main client for interacting with the CloudContactAI API
   class Client
-    attr_reader :config, :sms, :mms, :email, :webhook, :contact
+    attr_reader :config, :sms, :mms, :email, :webhook, :contact, :contact_validator
 
     # Create a new CCAI client instance
     #
@@ -88,6 +89,9 @@ def initialize(config)
 
       # Initialize the Contact service
       @contact = Contact::ContactService.new(self)
+
+      # Initialize the ContactValidator service
+      @contact_validator = ContactValidator::ContactValidatorService.new(self)
     end
 
     # Get the client ID

lib/ccai/contact_validator/contact_validator_service.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 CloudContactAI LLC
+# Licensed under the MIT License. See LICENSE in the project root for license information.
+
+module CCAI
+  module ContactValidator
+    # Service for validating email addresses and phone numbers
+    class ContactValidatorService
+      # Create a new ContactValidatorService instance
+      #
+      # @param client [CCAI::Client] The parent CCAI client
+      def initialize(client)
+        @client = client
+      end
+
+      # Validate a single email address
+      #
+      # @param email [String] Email address to validate
+      # @return [Hash] Validation result with contactField, type, status and metadata
+      def validate_email(email)
+        @client.request(:post, '/v1/contact-validator/email', { email: email })
+      end
+
+      # Validate multiple email addresses (up to 50)
+      #
+      # @param emails [Array<String>] List of email addresses to validate
+      # @return [Hash] Bulk validation results with summary
+      def validate_emails(emails)
+        @client.request(:post, '/v1/contact-validator/emails', { emails: emails })
+      end
+
+      # Validate a single phone number
+      #
+      # @param phone [String] Phone number in E.164 format (e.g. +15551234567)
+      # @param country_code [String, nil] Optional ISO 3166-1 alpha-2 country code (e.g. "US")
+      # @return [Hash] Validation result with contactField, type, status and metadata
+      def validate_phone(phone, country_code: nil)
+        payload = { phone: phone }
+        payload[:countryCode] = country_code if country_code
+        @client.request(:post, '/v1/contact-validator/phone', payload)
+      end
+
+      # Validate multiple phone numbers (up to 50)
+      #
+      # @param phones [Array<Hash>] List of phone inputs with :phone and optional :countryCode
+      # @return [Hash] Bulk validation results with summary
+      def validate_phones(phones)
+        @client.request(:post, '/v1/contact-validator/phones', { phones: phones })
+      end
+    end
+  end
+end

lib/ccai/version.rb

@@ -5,5 +5,5 @@
 
 module CCAI
   # Current version of the CCAI Ruby client
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end