This guide shows you how to complete 10DLC (10-Digit Long Code) registration using the Telnyx CLI, from brand creation through campaign approval.
Why 10DLC?
US carriers require 10DLC registration for Application-to-Person (A2P) messaging from local phone numbers. Without it, your messages may be blocked or throttled. Registration establishes your business identity with carriers and unlocks higher throughput based on your trust score.
For a deeper explanation of 10DLC, trust scores, and carrier requirements, see Understanding 10DLC. Prerequisites
- Telnyx account with verified status
- Telnyx CLI installed
TELNYX_API_KEY environment variable set- Business information ready (EIN, address, website)
- At least one US phone number
Registration Steps
Step 1: Create a Brand
A brand represents your business identity for 10DLC registration.
Standard Business
telnyx messaging-10dlc:brand create \
--entity-type PRIVATE_PROFIT \
--display-name "Acme Corp" \
--company-name "Acme Corporation Inc" \
--ein 12-3456789 \
--phone +15551234567 \
--street "123 Main Street" \
--city "San Francisco" \
--state CA \
--postal-code 94102 \
--country US \
--vertical TECHNOLOGY \
--website https://acme.com
Sole Proprietor
For sole proprietors, additional SMS OTP verification is required:
# Create sole proprietor brand
telnyx messaging-10dlc:brand create \
--entity-type SOLE_PROPRIETOR \
--display-name "John's Plumbing" \
--phone +15551234567 \
--email john@example.com
# Trigger SMS OTP
telnyx messaging-10dlc:brand trigger-sms-otp --brand-id <brand-id>
# Verify with OTP code received via SMS
telnyx messaging-10dlc:brand verify-sms-otp --brand-id <brand-id> --otp 123456
PRIVATE_PROFIT - Private companyPUBLIC_PROFIT - Publicly traded companyNON_PROFIT - Non-profit organizationGOVERNMENT - Government entitySOLE_PROPRIETOR - Individual / sole proprietor
Step 2: Check Brand Status
# List all brands
telnyx messaging-10dlc:brand list
# Get specific brand details
telnyx messaging-10dlc:brand retrieve --brand-id <brand-id>
# Get feedback if brand was rejected
telnyx messaging-10dlc:brand get-feedback --brand-id <brand-id>
Step 3: Create a Campaign
Once your brand is approved, create a campaign to define your messaging use case:
# First, list available use cases
telnyx messaging-10dlc:campaign:usecase list
# Create the campaign (via Portal or API - see note below)
Campaign creation is done via the Telnyx Portal or the API. The CLI supports retrieving and managing existing campaigns. Step 4: Manage Campaigns
# List campaigns for a brand
telnyx messaging-10dlc:campaign list --brand-id <brand-id>
# Get campaign details
telnyx messaging-10dlc:campaign retrieve --campaign-id <campaign-id>
# Check MNO (Mobile Network Operator) status
telnyx messaging-10dlc:campaign get-mno-metadata --campaign-id <campaign-id>
# Check operation status at carrier level
telnyx messaging-10dlc:campaign get-operation-status --campaign-id <campaign-id>
Step 5: Phone Number Assignment
Check phone number campaign assignments:
# List phone number campaign assignments
telnyx messaging-10dlc:phone-number-campaigns list
# Get assignment for specific number
telnyx messaging-10dlc:phone-number-campaigns retrieve --phone-number +15551234567
Step 6: Verify Setup
# Check brand status
telnyx messaging-10dlc:brand list --format json | jq '.data[] | {id, display_name, status}'
# Check campaign status
telnyx messaging-10dlc:campaign list --brand-id <brand-id> --format json | jq '.data[] | {id, usecase, status}'
# Verify number is assigned
telnyx messaging-10dlc:phone-number-campaigns retrieve --phone-number +15551234567
Campaign Approval
After submission, campaigns go through carrier approval:
| Status | Meaning |
|---|
PENDING | Awaiting review |
APPROVED | Ready to send messages |
REJECTED | Review feedback and resubmit |
Campaign approval can take 1-7 business days. Do not send A2P messages until approved.
Appeal Rejected Campaigns
If your campaign was rejected, you can submit an appeal:
telnyx messaging-10dlc:campaign submit-appeal --campaign-id <campaign-id>
Deactivate a Campaign
telnyx messaging-10dlc:campaign deactivate --campaign-id <campaign-id>
Once deactivated, a campaign cannot be restored.
Best Practices
Sample Messages
Your sample messages should:
- Represent actual messages you’ll send
- Include opt-out language (“Reply STOP to unsubscribe”)
- Match your stated use case
- Not contain placeholder text
Throughput
10DLC throughput depends on your trust score:
| Trust Score | Messages/Second |
|---|
| Low | 0.2 |
| Medium | 1 |
| High | 10+ |
- Verified business information
- Good messaging practices
- Low spam/complaint rates
Troubleshooting
”Brand verification failed”
- Double-check EIN matches IRS records exactly
- Verify business address is current
- Ensure phone number is associated with business
Check feedback:
telnyx messaging-10dlc:brand get-feedback --brand-id <brand-id>
“Campaign rejected”
Common reasons:
- Sample messages don’t match use case
- Missing opt-out language
- Vague or generic description
Solution: Review feedback, update campaign via Portal, and resubmit.
Revet a Brand
If your brand information has changed or was rejected, you can revet (resubmit):
telnyx messaging-10dlc:brand revet --brand-id <brand-id>
Revetting is allowed once after successful registration, then limited to once every 3 months.
Complete Script Example
#!/bin/bash
# 10dlc-check.sh - Check 10DLC registration status
set -e
echo "=== Brands ==="
telnyx messaging-10dlc:brand list --format json | \
jq -r '.data[] | "\(.display_name): \(.status)"'
echo ""
echo "=== Campaigns ==="
# Get first brand ID
BRAND_ID=$(telnyx messaging-10dlc:brand list --format json | jq -r '.data[0].id')
if [ "$BRAND_ID" != "null" ]; then
telnyx messaging-10dlc:campaign list --brand-id "$BRAND_ID" --format json | \
jq -r '.data[] | "\(.usecase): \(.status)"'
else
echo "No brands found"
fi
echo ""
echo "=== Phone Number Assignments ==="
telnyx messaging-10dlc:phone-number-campaigns list --format json | \
jq -r '.data[] | "\(.phone_number): \(.campaign_id)"' | head -10
Next Steps
