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 every US carrier (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. No SMS is sent.

Verify checks whether the account can actually send, not just whether the credentials authenticate:

Active account

Credentials work and the account can send. You're ready.

Trial account

Credentials work, but a trial account can only text numbers you've verified in the Twilio Console. Verify still passes — this is a heads-up, not a failure. Upgrade to reach any number.

Suspended or closed account

Verify fails even though the credentials are correct. A suspended account authenticates but can't send. Sort it out in the Twilio Console before you route live leads here.

Wrong Account SID or Auth Token

Verify fails with a rejected-credentials message. Re-copy both from the Console.

Credential handling

• LeadRails stores your Account SID + Auth Token (or API Key Secret) and reuses them on every send. Twilio has no OAuth or token-refresh flow for the REST API, so these are static credentials — there's nothing to renew on a schedule.
• When you rotate your Auth Token or revoke an API Key in Twilio, the old value stops working immediately. Update the destination config with the new value or sends start failing with a 401.
• Prefer a dedicated API Key + Secret over the account Auth Token. You can revoke a single key without rotating the token every other integration depends on.

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).