From 16f650d85f4bd20322cbd9db52fe8d74abcd724a Mon Sep 17 00:00:00 2001 From: Deyner lopez Date: Thu, 14 May 2026 17:45:36 -0500 Subject: [PATCH] https://mobileaws.atlassian.net/browse/CLOUD-2744 --- README.md | 37 +++++++++++++ lib/ccai/client.rb | 6 ++- .../contact_validator_service.rb | 53 +++++++++++++++++++ lib/ccai/version.rb | 2 +- 4 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 lib/ccai/contact_validator/contact_validator_service.rb diff --git a/README.md b/README.md index 3e3b73b..a5c645d 100644 --- a/README.md +++ b/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}`) diff --git a/lib/ccai/client.rb b/lib/ccai/client.rb index 271876c..2496aff 100644 --- a/lib/ccai/client.rb +++ b/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 diff --git a/lib/ccai/contact_validator/contact_validator_service.rb b/lib/ccai/contact_validator/contact_validator_service.rb new file mode 100644 index 0000000..ddbcaac --- /dev/null +++ b/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] 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] 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 diff --git a/lib/ccai/version.rb b/lib/ccai/version.rb index db8d6af..f4f2f6d 100644 --- a/lib/ccai/version.rb +++ b/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