Twilio Error 30003, 30005, and 30006: Prevent SMS Delivery Failures with Phone Validation

API example: classify before sending SMS

Put validation between the form, CRM, or campaign export and your SMS provider. The example below returns a simple send decision your application can store next to the contact record.

type PhoneCheckResult = {
  carrier?: string;
  line_type?: 'mobile' | 'landline' | 'fixed_voip' | 'non_fixed_voip' | 'toll_free';
  normalized_phone?: string;
  risk_score?: number;
  timezone?: string;
  valid: boolean;
};

type SmsDecision = {
  allowSms: boolean;
  reason: string;
  normalizedPhone?: string;
};

export async function classifyBeforeSms(phoneNumber: string): Promise<SmsDecision> {
  const url = new URL('https://api.phone-check.app/v1-get-phone-details');
  url.searchParams.set('phone', phoneNumber);

  const response = await fetch(url, {
    headers: {
      accept: 'application/json',
      'x-api-key': process.env.PHONE_CHECK_API_KEY ?? '',
    },
  });

  if (!response.ok) {
    return { allowSms: false, reason: 'validation_unavailable' };
  }

  const result = (await response.json()) as PhoneCheckResult;

  if (!result.valid) {
    return { allowSms: false, reason: 'invalid_or_inactive_number' };
  }

  if (result.line_type === 'landline' || result.line_type === 'toll_free') {
    return { allowSms: false, reason: 'not_sms_capable' };
  }

  if (result.line_type === 'non_fixed_voip' || (result.risk_score ?? 0) >= 70) {
    return { allowSms: false, reason: 'high_risk_or_disposable_number' };
  }

  return {
    allowSms: true,
    normalizedPhone: result.normalized_phone,
    reason: 'valid_mobile_or_reviewed_fixed_voip',
  };
}

The exact endpoint shape depends on your account configuration, but the rule should stay stable: no valid mobile signal, no automatic SMS. High-value exceptions can move to review instead of suppression.

FAQ