SMS via Twilio

About 10DLC and A2P SMS (US senders, read this)

• If you're sending SMS to US numbers, you MUST register your brand + campaign with The Campaign Registry (TCR) for "A2P 10DLC" compliance. Unregistered traffic gets throttled to ~5 messages/day across the entire US carrier ecosystem (essentially undeliverable).
• Carriers (Verizon, T-Mobile, AT&T) enforced this in 2023. Twilio walks you through the registration in their console, but YOU are the brand of record — Twilio is just the carrier of record.
• Registration costs ~$4/month for brand + ~$10/month per campaign, plus per-message carrier fees on top of Twilio's base rates.
• International SMS varies — UK + EU have their own compliance regimes. Lighter than US 10DLC for transactional, stricter for marketing.

What you can NOT do

• Share a single Twilio number across multiple customers' messages. STOP/HELP keywords route to the number-owner, recipients can't tell who actually sent the message, and carriers will throttle "high-distinct-recipient" patterns. Each customer needs their own number + campaign.
• Send marketing content via a campaign registered as "transactional" — that's a TCR violation and your registration gets revoked.

Twilio setup

1. Visit https://twilio.com → sign up (free trial gives you a verified test number with $15 credit).
2. Verify your email + phone — required before you can send SMS.
3. From Twilio Console: Phone Numbers → Buy a Number.
4. Pick a 10-digit US number (~$1/month) with SMS capability.
5. Now the compliance dance:
   • Console → Messaging → Compliance → "10DLC".
   • Step 1: Register your Brand (business name, EIN, address, vertical) — Twilio submits to TCR, takes 24-48h for low-volume brands.
   • Step 2: Create a Campaign (use case: "Lead Notifications" — describes what your messages will say + sample content).
   • Step 3: Attach your phone number(s) to the campaign.
6. Wait for "Approved" status. Until then, traffic is throttled.

Get your Twilio credentials

1. Console → Account → API Keys & Tokens.
2. Account SID: at the top of the Console dashboard — starts with AC followed by 32 hex chars.
3. Auth Token: in the same dashboard area, click "Show" to reveal — treat like a password.
4. Optionally generate a separate API Key + Secret instead of using the Auth Token (better for security: revocable per-integration).

Set up your destination in LeadRails

1. Sign in → Destinations → New.
2. Adapter type: SMS — Twilio.
3. Account SID: paste your AC... value.
4. Auth token: paste your Auth Token (or API Key Secret if using a separate API Key).
5. From number: your 10DLC-registered Twilio number in E.164 format (e.g. +15555550100).
6. Recipient template: {{phone}} (uses the lead's phone in E.164).
7. Message body template: e.g. Hi {{name}}, thanks for your interest. We'll reach out at {{email}}. Reply STOP to opt out. (NOTE: include opt-out language for compliance.)
8. Messaging Service SID (optional): paste your MG... Messaging Service ID if you've configured one in Twilio. Recommended for 10DLC — Twilio uses the service's pool of numbers + handles failover. If set, this OVERRIDES the From number.
9. Click Create.

Phone numbers MUST be E.164

• E.164 format: + then country code then number, no spaces or dashes. Examples:
  • US: +15555550100
  • UK: +447700900100
  • Australia: +61400000000
• Recipient template like {{phone}} resolves from the lead's normalized phone field — make sure your intake form / upstream source produces E.164. Twilio rejects non-E.164 with error_code: 21211.

Verify connection

1. Open the destination → Advanced → Verify connection.
2. LeadRails hits Twilio's /Accounts/<SID> endpoint with your credentials.
3. 200 = creds work; 401 = invalid.

Send a test SMS

1. Sources → your source → Settings → ensure a route exists to your Twilio destination.
2. Click "Send test event" — uses a sample lead payload with phone +15555550100.
3. Twilio's Console → Messaging → Logs shows the outbound message + status (queued / sent / delivered / undelivered).

Troubleshooting

401

Account SID or Auth Token wrong.

400 + error_code 21211 ("Invalid 'To' Phone Number")

Recipient not E.164. Normalize upstream.

400 + error_code 21610 ("Recipient unsubscribed")

Recipient sent STOP previously. Twilio enforces opt-outs. They're on the suppression list.

400 + error_code 21408 ("Permission to send to this number is not enabled")

International destination not enabled in your Twilio account. Settings → Geo Permissions.

403 + error_code 30007 ("Message filtered")

Carrier filtered the message. Common causes: unregistered 10DLC, message content tripped carrier spam heuristics, missing opt-out language. LeadRails surfaces this as destination_config_failed.

Throttling

Sub-5 messages/day = unregistered 10DLC. Register your brand + campaign in Twilio Console.

Long delays before delivery

Carrier filtering on first messages from a new number is common. Wait 24-48h for "warming" to complete.

What's yours, what's ours

Your responsibilities

• Brand + Campaign registration with TCR (via Twilio Console).
• Consent collection (TCPA — recipients must have opted in to receiving SMS from you).
• STOP / HELP keyword handling (Twilio auto-handles STOP by default; you can configure HELP responses in Console).
• Message content compliance (avoid prohibited content categories: SHAFT — sex, hate, alcohol, firearms, tobacco — without proper registration).
• Quiet hours (TCPA prohibits SMS 9pm-8am recipient local time).
• Frequency caps (no more than what you disclosed at opt-in).

LeadRails's responsibilities

• Deliver your message to Twilio reliably (retries, dead-letter, audit log).
• Surface delivery failures in your Jobs page + Alerts inbox.
• Mask credentials in the UI.
• Re-check SSRF guards (N/A for SMS — Twilio is a fixed endpoint).