How to Switch SMS Providers: The Complete Migration Checklist

Step 1: Audit your current usage

Before switching, gather your current provider's data. You need to know exactly what you are migrating:

• Destination countries and volumes. Export 3 months of SMS logs. Identify your top 10 destination countries and the percentage of traffic each represents. This tells you where pricing matters most.
• Sender IDs in use. List every sender ID (alphanumeric, long code, shortcode) currently configured. Each country has different sender ID registration requirements — confirm the new provider supports your sender types in each destination country.
• Webhook endpoints. List every DLR (delivery receipt) webhook and inbound SMS webhook URL. These will need to point to the new provider's callback infrastructure.
• API integration points. Find every place in your codebase that calls the SMS API. Search for your current provider's base URL, SDK imports, or API key references.
• Current monthly spend. Get your average monthly bill for the last 3 months. This is your baseline for cost comparison.

Step 2: Set up the new provider in parallel

Do not turn off the old provider until the new one is fully tested. Run both in parallel during migration.

1. Create an account with the new provider. If migrating to SMSRoute, sign up with an email and deposit crypto (or use the $5 free credit). No KYC required — you will have an API key in under 60 seconds.
2. Configure sender IDs. Register or verify your sender IDs with the new provider. SMSRoute supports alphanumeric sender IDs in most countries; long codes and shortcodes are not offered (SMS-only, no phone number rental).
3. Generate test API keys. Create separate test and production API keys. Route your test environment to the new provider first.
4. Verify country coverage. Send test messages to your top 10 destination countries. Confirm delivery rates and latency meet your requirements. Compare against the delivery benchmarks.

Step 3: Migrate your send logic

The heavy lifting is in the code. Most SMS APIs follow similar REST patterns, so migration is primarily a string-replacement exercise:

Python (migrating from Twilio to SMSRoute):

# Before (Twilio)
from twilio.rest import Client
client = Client(ACCOUNT_SID, AUTH_TOKEN)
message = client.messages.create(
    to="+1234567890",
    from_="+0987654321",
    body="Your OTP: 847291"
)

# After (SMSRoute)
import requests
response = requests.post(
    "https://log.hashlock.tech/api/sms/send",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"to": "+1234567890", "from": "MyApp", "message": "Your OTP: 847291"}
)

Node.js:

// Before (Twilio)
const client = require('twilio')(ACCOUNT_SID, AUTH_TOKEN);
await client.messages.create({
  to: '+1234567890', from: '+0987654321', body: 'Your OTP: 847291'
});

// After (SMSRoute)
await fetch('https://log.hashlock.tech/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '+1234567890', from: 'MyApp', message: 'Your OTP: 847291' })
});

Key differences to handle:

• Authentication: Twilio uses Account SID and Auth Token (Basic Auth). SMSRoute uses a Bearer token in the Authorization header.
• Payload keys: Twilio uses To, From, Body. SMSRoute uses lowercase to, from, message.
• Base URL: Swap api.twilio.com for log.hashlock.tech.

For a complete migration guide, see the Twilio to SMSRoute migration page.

Step 4: Reconfigure DLR webhooks

Delivery receipt callbacks are the most commonly broken part of an SMS migration. Each provider formats DLR payloads differently:

• Update your webhook handler to accept the new provider's DLR format. SMSRoute sends DLRs as JSON POST requests with messageId, status (delivered, failed, buffered), to, deliveredAt, and errorCode fields.
• Set the webhook URL in the new provider's dashboard. SMSRoute lets you configure a global DLR webhook or pass a per-message webhookUrl in the send request.
• Test with real messages. Send 10-20 test messages and verify you receive DLRs for each one. Check the status field — a delivered DLR confirms end-to-end integration.
• Handle retries. SMSRoute retries failed DLR webhooks with exponential backoff (1s, 5s, 25s, 125s) for up to 24 hours. Ensure your webhook endpoint is idempotent — the same DLR may be delivered more than once.

Step 5: Cut over and validate

Once the new provider passes all tests in your staging environment:

1. Deploy to production with a feature flag. Route 1% of production traffic to the new provider. Monitor delivery rates, latency, and DLR webhook success for 24 hours.
2. Ramp to 10%, then 50%, then 100%. Increase traffic share over 3-7 days. Compare delivery rates between old and new providers at each stage.
3. Keep the old provider active for 7 days after cutover. Some messages may still be in flight. Do not cancel your old account until all in-flight messages have received final DLRs.
4. Export and archive old provider data. Download message logs, DLRs, and billing history before closing the account. You may need this for compliance or billing audits.
5. Verify your first bill. Compare the new provider's first full-month bill against your baseline from Step 1. Confirm the expected savings materialized.

FAQ