Phone Number Validation & Formatting

Reduce SMS delivery failures by implementing robust Kenyan phone number validation and E.164 normalization.

Guides / Phone Number Validation

Why Validation Matters

Invalid phone numbers are the #1 cause of SMS delivery failures in Kenya. Each failed send wastes credits, degrades your sender reputation, and frustrates customers. Proper validation before sending ensures:

  • Cost Savings: Eliminate wasted credits on undeliverable numbers
  • Higher Delivery Rates: Clean lists achieve 95%+ delivery vs 70-80% for unvalidated lists
  • Better Analytics: Accurate metrics when failures aren't masked by format errors
  • Carrier Compliance: Networks reject malformed numbers at gateway level
  • User Experience: Catch typos during signup rather than after critical messages fail

Cost Impact

A typical business list has 8-12% invalid numbers. For 10,000 monthly sends at KES 0.75/SMS, that's KES 600-900 wasted monthly - over KES 10,000 annually.

Accepted Formats

MacraSMS accepts multiple input formats but normalizes all to E.164 standard internally:

Input Format Example Normalized To Status
E.164 International 254708138498 254708138498 ✅ Preferred
Local with leading 0 0708138498 254708138498 ✅ Accepted
9-digit local 708138498 254708138498 ✅ Accepted
With + prefix +254708138498 254708138498 ⚠️ Auto-stripped
With spaces/dashes 0708-138-498 254708138498 ⚠️ Auto-cleaned
Wrong country code 255708138498 Rejected ❌ Invalid
Too short/long 70813849 Rejected Invalid

Normalization Logic

Implement this step-by-step normalization process before sending to our API:

  1. Strip Non-Digits: Remove all characters except 0-9 using regex /[^0-9]/g
  2. Remove Leading +: If string starts with "+", remove it
  3. Check Length: Valid Kenyan numbers are 9, 10, or 12 digits after stripping
  4. Apply Prefix Rules:
    • If 12 digits and starts with "254" → valid as-is
    • If 10 digits and starts with "0" → prepend "254"
    • If 9 digits → prepend "254"
    • Otherwise → reject as invalid
  5. Validate Carrier Prefix: Ensure second digit after 254 is 7, 1, or 5 (valid mobile prefixes)
  6. Return Normalized: Output should always be exactly 12 digits starting with 254
// JavaScript normalization example function normalizeKenyanNumber(raw) { // Strip non-digits let cleaned = raw.replace(/[^0-9]/g, ''); // Remove leading + if (cleaned.startsWith('+')) cleaned = cleaned.substring(1); // Apply prefix rules if (cleaned.length === 12 && cleaned.startsWith('254')) { return cleaned; } else if (cleaned.length === 10 && cleaned.startsWith('0')) { return '254' + cleaned.substring(1); } else if (cleaned.length === 9) { return '254' + cleaned; } return null; // Invalid }

Regex Patterns

Use these validated regex patterns for different validation stages:

Purpose Pattern Matches
Basic digit extraction /[^0-9]/g Strips all non-numeric characters
Valid normalized format ^254[157]\d{8}$ 254 + valid prefix + 8 digits
Raw input acceptance ^(\+?254|0)?[157]\d{8}$ All accepted input variations
Safaricom specific ^2547\d{8}$ 2547XXXXXXXXX only
Airtel/Telkom specific ^254[15]\d{8}$ 2541/2545XXXXXXXXX only

Pro Tip

Always validate AFTER normalization, not before. Raw input validation misses edge cases like "+254 708 138 498" that normalize correctly.

Common Invalid Numbers

Watch for these frequently encountered invalid patterns:

  • Placeholder Numbers: 254700000000, 254711111111, 254722222222 - often used in test data
  • Sequential Digits: 254701234567, 254798765432 - obvious fakes
  • Wrong Country Codes: 255... (Tanzania), 256... (Uganda), 250... (Rwanda)
  • Landline Formats: 25420... (Nairobi landlines cannot receive SMS)
  • Short Codes: Any number under 9 digits after country code
  • Duplicate Entries: Same number appearing multiple times in bulk uploads

Bulk Upload Tips

When processing CSV/Excel uploads with thousands of numbers:

  1. Pre-validate Client-Side: Show real-time feedback during file upload before server processing
  2. Deduplicate First: Remove duplicates BEFORE validation to avoid double-charging
  3. Batch Processing: Validate in batches of 1000 to avoid timeout issues
  4. Error Reporting: Return detailed error report showing which rows failed and why
  5. Partial Success: Allow sending to valid numbers while quarantining invalid ones
  6. Preview Mode: Show validation results before deducting credits

Critical Warning

Never assume uploaded numbers are valid. Even "verified" databases contain 5-8% invalid entries due to porting, disconnections, and user errors.

API Integration

MacraSMS API performs server-side validation, but client-side validation improves UX:

  • Client-Side: Use regex above for instant form feedback during data entry
  • Server-Side: Our API validates and normalizes all numbers before processing
  • Error Responses: API returns specific error codes for invalid numbers vs other failures
  • Bulk Endpoint: Returns per-number status in response array for batch operations
  • Webhook Updates: Delivery reports include normalized number format for reconciliation

Testing Your Validation

Verify your implementation with these test cases:

Test Input Expected Output Purpose
254708138498 254708138498 Already normalized
0708138498 254708138498 Local format conversion
708138498 254708138498 9-digit conversion
+254 708-138-498 254708138498 Special character stripping
255708138498 null / error Wrong country code rejection
25470813849 null / error Too short rejection
254201234567 null / error Landline prefix rejection
abc123 null / error Non-numeric rejection

Need Help With Validation?

Our SDKs include built-in Kenyan number validation. Download the library for your language today.

View API Documentation