Achieving high message delivery rates requires understanding the technical nuances of each channel. In this guide, we'll explore advanced optimization strategies used by Zavu to maximize deliverability.
Understanding Delivery Challenges
Message delivery can fail for various reasons:
- Invalid phone numbers - Numbers that don't exist or are incorrectly formatted
- Carrier filtering - Messages blocked by carrier spam filters
- Channel unavailability - WhatsApp not installed, phone off, etc.
- Rate limiting - Exceeding carrier or platform limits
- Content issues - Spam triggers or policy violations
Phone Number Validation
Validate phone numbers before sending:
TypeScriptimport Zavudev from '@zavudev/sdk' const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY }) async function validateAndSend(phoneNumber: string) { // POST /v1/introspect/phone const validation = await zavu.introspect.validatePhone({ phoneNumber }) if (!validation.validNumber) { console.error('Invalid number:', phoneNumber) return } // Get detailed information console.log({ phoneNumber: validation.phoneNumber, // E.164 format countryCode: validation.countryCode, // US, GB, etc. nationalFormat: validation.nationalFormat, // (312) 945-7420 carrier: validation.carrier?.name, // carrier name, when known lineType: validation.lineType, // mobile, landline, voip, toll_free, unknown availableChannels: validation.availableChannels }) // Only send to valid mobile numbers if (validation.lineType === 'mobile') { await zavu.messages.send({ to: validation.phoneNumber, text: 'Your verification code is 123456' }) } }
Channel Selection
With channel: 'auto' (the default when you omit channel), Zavu picks the channel from what the sender can send on and what the recipient is:
TypeScript// Let Zavu choose the channel const { message } = await zavu.messages.send({ to: '+1234567890', channel: 'auto', text: 'Your package is out for delivery!' }) console.log('Selected channel:', message.channel) console.log('Status:', message.status) // queued, then sent / delivered / failed
Implementing Fallback
A failed WhatsApp text or template message can be retried over SMS, when the sender also has SMS. It is on by default with channel: 'auto', and off when you set a channel explicitly unless you pass fallbackEnabled: true:
TypeScriptconst { message } = await zavu.messages.send({ to: '+1234567890', channel: 'whatsapp', text: 'Important: Your appointment is tomorrow at 2 PM', fallbackEnabled: true // retry over SMS if the WhatsApp send fails }) // Follow the outcome with GET /v1/messages/{messageId} or the message.* webhooks const latest = await zavu.messages.retrieve(message.id) console.log(latest.message.channel, latest.message.status, latest.message.errorCode)
Media, buttons, lists and other WhatsApp-only types never fall back. Email is not part of the fallback: send it as its own message if you need it.
Content Optimization
Avoid spam filters: no all-caps, no stacks of exclamation marks, no URL shorteners, and name your business in the message. Zavu checks every SMS before it goes out, and a message the check refuses is answered with 422 sms_compliance_blocked, which tells you what to fix:
TypeScripttry { await zavu.messages.send({ to: '+1234567890', channel: 'sms', text: 'URGENT!!! Click here to claim your FREE prize NOW!!!' }) } catch (err) { if (err instanceof Zavudev.UnprocessableEntityError) { // { code: 'sms_compliance_blocked', message, details: { riskScore, complianceFailures, requiredFixes, suggestedCompliantVersion? } } const body = err.error as { code?: string; details?: Record<string, unknown> } console.log('Blocked:', body.code) console.log('Required fixes:', body.details?.requiredFixes) console.log('Suggested rewrite:', body.details?.suggestedCompliantVersion) } else { throw err } }
URLs in SMS must also be verified: submit them ahead of time with POST /v1/urls.
Monitoring Delivery
Delivery metrics are in the dashboard under Monitoring. To compute your own, list messages and count by status:
TypeScript// Count recent outbound SMS by status const counts: Record<string, number> = {} for await (const message of zavu.messages.list({ channel: 'sms', limit: 100 })) { if (message.direction !== 'outbound') continue counts[message.status] = (counts[message.status] ?? 0) + 1 } const sent = Object.values(counts).reduce((a, b) => a + b, 0) console.log(counts) // { delivered: 4850, failed: 150, ... } console.log('Delivery rate:', (counts.delivered ?? 0) / sent)
For real-time tracking, subscribe your sender's webhook to message.delivered and message.failed.
What to Measure
Track these before and after every change:
| Metric | How to measure |
|---|---|
| SMS delivery rate | delivered / outbound SMS, from GET /v1/messages |
| WhatsApp delivery rate | delivered + read / outbound WhatsApp |
| Failure reasons | errorCode on failed messages |
| Cost per message | costTotal on each message |
Conclusion
Optimizing message delivery is an ongoing process. Use the dashboard's Monitoring screen and the message webhooks to keep watching your delivery rates.
Need help optimizing your message delivery? Contact us or join our Discord community for support and updates.