A comprehensive, hands-on, 5-day training program for designing and building a production-ready bulk SMS sending system using the Telnyx SMPP interface and REST (Messaging v2) API, with full support for two-way (inbound + outbound) SMS.
⚠️ Verify before deploying: Telnyx pricing, throughput limits, SMPP contract minimums, and compliance requirements (10DLC, toll-free verification, short code) change over time and vary by account/region. This README defines the training structure and objectives. Confirm current specifics against Telnyx Developer Docs and the Telnyx Help Center before each cohort — see Additional Resources.
- Overview
- Learning Objectives
- Audience
- Prerequisites
- Lab Environment
- Training Schedule
- Repository Structure
- Getting Started
- Lab Exercises
- Assessment & Certification
- Reference Architecture
- Troubleshooting Guide
- Additional Resources
- Contributing
- License
This training module prepares engineering teams to build a production-grade bulk SMS platform on Telnyx, combining the REST Messaging API (v2) for application integration and two-way conversational messaging with the SMPP protocol for high-throughput bulk sending. The course covers the full lifecycle: account and number provisioning, messaging profile configuration, sending and receiving messages, building a queued/throttled bulk-send pipeline, handling inbound replies and opt-outs, and operating the system reliably and compliantly at scale.
By the end of this training, participants will be able to:
- Set up a Telnyx account, purchase SMS-capable numbers, and configure Messaging Profiles
- Send and receive SMS/MMS using the Telnyx REST Messaging API (
/v2/messages) - Configure and consume delivery receipts and inbound message webhooks for two-way messaging
- Understand the SMPP protocol fundamentals: binds (transmitter/receiver/transceiver), PDUs,
submit_sm,deliver_sm, and session management - Establish a TLS-secured SMPP bind to Telnyx's SMPP server and send messages at scale
- Design a bulk SMS sending architecture: message queueing, per-number/per-account throttling, retry logic, and long-message (concatenated SMS) handling
- Implement two-way SMS logic: auto-replies, keyword handling (HELP/STOP), and conversational routing
- Apply US messaging compliance requirements: 10DLC registration, toll-free verification, opt-in/opt-out handling, and TCPA considerations
- Monitor delivery, troubleshoot failed messages using Telnyx error codes, and build operational dashboards
- Choose correctly between REST API and SMPP for a given workload, and combine both in a single production system
- Backend/platform engineers building bulk messaging or notification systems
- DevOps/SRE teams responsible for operating a messaging pipeline at scale
- Product/engineering teams adding two-way SMS (support, alerts, marketing, OTP) to an application
- Technical leads evaluating REST API vs. SMPP for a high-volume SMS use case
Required:
- Working proficiency in at least one backend programming language (Python, Node.js, Java, or Go)
- Familiarity with REST APIs, JSON, and webhooks
- Basic command-line and networking familiarity (TCP sockets, TLS)
Recommended:
- Prior exposure to message queues (RabbitMQ, SQS, Kafka, or similar)
- Basic understanding of async/concurrent programming
- Familiarity with Docker for running lab services locally
Not required but helpful: Prior telecom/SMS gateway experience, familiarity with another SMPP-based provider
Each participant is provisioned with an isolated lab environment consisting of:
| Component | Specification |
|---|---|
| Dev Workstation | Cloud IDE (VS Code Server) with Python 3.11+/Node.js 20+ and an SMPP client library |
| Telnyx Sandbox | Lab Telnyx account/sub-account with test numbers (on-net Telnyx-to-Telnyx testing requires no carrier registration) |
| Message Queue | Redis or RabbitMQ instance for building the bulk-send queue |
| Webhook Endpoint | Public-facing tunnel (e.g., ngrok) or lab ingress for receiving delivery receipts and inbound messages |
| Supporting Services | PostgreSQL for message/contact/opt-out storage, Grafana/Prometheus for monitoring labs |
| Access | Browser-based terminal/IDE, Telnyx Mission Control Portal access scoped to the lab account |
💡 SMPP access on Telnyx is a contracted feature (minimum monthly commitment, provisioned by an account manager). The lab environment simulates SMPP binds against a local SMPP test server on Days 1–2 and (where available) connects to a real Telnyx SMPP sandbox bind on Day 3. See
/labs/environment-setupfor both paths.
Morning — Concepts
- SMS/MMS fundamentals: message flow (application → REST API/SMPP → SMSC → carrier → handset), delivery receipts, and reply paths
- Telnyx platform overview: Mission Control Portal, Numbers, Messaging Profiles, API Keys/Auth
- Number types and their throughput/use-case trade-offs: long code (10DLC), toll-free, short code, alphanumeric sender ID, number pools
- REST API vs. SMPP: when each is the right tool (throughput, latency, integration complexity, contractual requirements)
- US compliance landscape overview: 10DLC, toll-free verification, TCPA — why registration matters before bulk sending
Afternoon — Hands-on Labs
- Lab 1.1: Create a lab Telnyx account, verify it, and add a payment method
- Lab 1.2: Purchase two SMS-capable numbers and create a Messaging Profile (API v2)
- Lab 1.3: Assign numbers to the Messaging Profile and generate an API key
- Lab 1.4: Send a test message between the two lab numbers via the Mission Control Portal (Learn & Build) to confirm on-net messaging works
Deliverable: A configured Telnyx account with two messaging-enabled numbers and a working Messaging Profile, ready for API integration.
Morning — Concepts
- The Messaging API:
POST /v2/messages— required fields (from,to,text), E.164 number formatting, and MMSmedia_urls - Reading API responses: message IDs, status lifecycle, and error payloads
- Configuring webhooks on a Messaging Profile for delivery receipts and inbound messages
- Handling inbound messages: routing replies, detecting keywords, building conversational flows
- SDKs and tooling: Telnyx official SDKs vs. raw HTTP integration
Afternoon — Hands-on Labs
- Lab 2.1: Send your first SMS via
curl/SDK and inspect the JSON response - Lab 2.2: Stand up a webhook receiver (using ngrok or lab ingress) and register it on your Messaging Profile
- Lab 2.3: Capture and log delivery receipt events (
message.sent,message.finalized) for outbound messages - Lab 2.4: Build a simple two-way flow: receive an inbound message and send an automated reply
- Lab 2.5: Implement basic keyword handling (e.g.,
HELP,STOP,START) at the application layer
Deliverable: A working two-way SMS application: send via REST API, receive inbound messages via webhook, and respond automatically to keywords.
Morning — Concepts
- SMPP protocol fundamentals: ESME vs. SMSC roles, PDUs, and session lifecycle
- Bind types: Transmitter (TX), Receiver (RX), Transceiver (TRX) — and why TRX is generally preferred for two-way use
- Core PDU operations:
bind_transceiver,submit_sm,deliver_sm,enquire_link,unbind - Telnyx's SMPP offering: TLS-secured connection to Telnyx's SMPP server, credentials issued per Messaging Profile, and its status as a contracted/high-commitment feature
- Message segmentation: character limits (160 GSM-7 / 70 UCS-2), concatenated SMS (multipart headers), and Unicode/DCS considerations
- Per-number throughput characteristics (e.g., long code vs. toll-free) and why SMPP is chosen for sustained high-volume sending
Afternoon — Hands-on Labs
- Lab 3.1: Configure an SMPP client library and establish a
bind_transceiversession (lab SMPP test server; real Telnyx bind if lab account is provisioned) - Lab 3.2: Send a
submit_smPDU and confirm the response/message ID - Lab 3.3: Implement
enquire_linkkeep-alives and graceful reconnect/rebind logic - Lab 3.4: Handle
deliver_smPDUs for inbound messages and delivery receipts over the SMPP bind - Lab 3.5: Implement long-message segmentation and reassembly for messages over the single-segment character limit
Deliverable: A working SMPP client that binds, sends, receives, and correctly segments long messages, with keep-alive and reconnect handling.
Morning — Concepts
- Bulk-send architecture patterns: producer/consumer queues, worker pools, and idempotent send tracking
- Throttling strategy: respecting per-number and per-account rate limits, avoiding carrier filtering from burst sending
- Choosing REST API vs. SMPP per workload within the same system (e.g., transactional via REST, bulk campaign via SMPP)
- Contact list management: opt-in tracking, suppression/opt-out lists, and deduplication
- Two-way conversation state: correlating inbound replies to the right outbound campaign/contact/thread
- Failure handling: retries, dead-letter queues, and distinguishing permanent vs. transient errors using Telnyx error codes
Afternoon — Hands-on Labs
- Lab 4.1: Build a message queue (Redis/RabbitMQ) that ingests a CSV contact list and enqueues personalized messages
- Lab 4.2: Implement a worker pool that drains the queue via SMPP with configurable throughput throttling
- Lab 4.3: Add REST API fallback/routing for low-volume transactional sends alongside the SMPP bulk path
- Lab 4.4: Implement opt-out handling: STOP keyword detection updates a suppression list that the queue checks before every send
- Lab 4.5: Build conversation threading so inbound replies are correctly associated with the originating bulk campaign/contact
Deliverable: A functioning bulk SMS pipeline: CSV import → queue → throttled SMPP sending → inbound reply correlation → opt-out enforcement.
Morning — Concepts
- US compliance deep dive: 10DLC brand/campaign registration, toll-free verification, short code use cases, and why unregistered bulk sending gets filtered or blocked
- TCPA and consent: documenting opt-in, honoring STOP/HELP requirements, and message content restrictions
- Reliability patterns: SMPP bind failover, REST API retry/backoff, and monitoring bind health
- Observability: logging delivery status end-to-end, building dashboards for send volume/delivery rate/error rate
- Cost and throughput planning: estimating message segments, forecasting volume, and capacity planning for the sending pipeline
- Operational runbooks: rotating SMPP/API credentials, incident response for delivery failures, and scaling the worker pool
Afternoon — Hands-on Labs
- Lab 5.1: Walk through (or simulate) a 10DLC brand and campaign registration flow and map it to the lab Messaging Profile
- Lab 5.2: Implement bind failover/reconnect logic and a health-check endpoint for the SMPP worker
- Lab 5.3: Build a monitoring dashboard showing send volume, delivery rate, and error breakdown by Telnyx error code
- Lab 5.4: Draft a credential-rotation runbook for API keys and SMPP credentials
- Lab 5.5 (Capstone): Deploy the complete bulk SMS system end-to-end — contact import, compliance-aware sending (opt-out enforced), SMPP bulk path with REST fallback, inbound two-way handling, and a live monitoring dashboard
Deliverable (Capstone Project): A fully operational, documented, production-ready bulk SMS system with two-way messaging, compliance controls, throttled SMPP sending, and monitoring — plus a written operational runbook.
telnyx-sms-training/
├── README.md
├── slides/ # Day-by-day presentation decks
│ ├── day1-fundamentals-and-setup.pdf
│ ├── day2-rest-api-two-way.pdf
│ ├── day3-smpp-protocol.pdf
│ ├── day4-bulk-send-architecture.pdf
│ └── day5-compliance-and-operations.pdf
├── labs/
│ ├── environment-setup/ # Docker Compose bootstrap (Redis/RabbitMQ, Postgres, local SMPP test server)
│ ├── day1/
│ ├── day2/
│ ├── day3/
│ ├── day4/
│ └── day5/
├── app/
│ ├── rest-client/ # REST API send/receive reference implementation
│ ├── smpp-client/ # SMPP bind/submit_sm/deliver_sm reference implementation
│ ├── bulk-queue/ # Queue producer/consumer, throttling, retry logic
│ └── webhook-server/ # Inbound message + delivery receipt webhook handler
├── compliance/
│ ├── opt-out-suppression/ # STOP/HELP keyword handling and suppression list logic
│ └── 10dlc-checklist.md
├── monitoring/
│ └── dashboards/ # Grafana dashboard definitions
├── solutions/ # Reference solutions for each lab
└── docs/
├── troubleshooting.md
├── telnyx-error-codes.md
├── architecture-diagrams/
└── glossary.md
-
Clone this repository:
git clone https://github.com/<your-org>/telnyx-sms-training.git cd telnyx-sms-training
-
Provision your lab environment:
cd labs/environment-setup docker compose up -d -
Configure your credentials:
cp .env.example .env # Add TELNYX_API_KEY, TELNYX_MESSAGING_PROFILE_ID, and (Day 3+) SMPP system_id/password -
Verify prerequisites:
./labs/environment-setup/scripts/check-prereqs.sh
-
Start with Day 1:
cd labs/day1 cat README.md
Each day's lab folder (labs/dayN/) contains:
README.md— step-by-step instructions and success criteriastarter/— starting-point code and configshints.md— progressive hints for anyone who gets stuck- Corresponding reference solution in
solutions/dayN/
Labs build cumulatively: the REST integration from Day 2, the SMPP client from Day 3, and the queueing logic from Day 4 are all assembled into the Day 5 capstone system.
- Daily checkpoints: short knowledge checks at the end of each day
- Capstone project (Day 5): graded on functionality, throttling/compliance correctness, reliability handling, and monitoring completeness
- Certificate of completion issued to participants who complete all daily labs and the capstone project
The course builds toward the following bulk SMS system architecture:
┌────────────────┐ ┌───────────────────────┐
│ Contact List / │──────▶│ Import & Suppression │
│ CSV Upload │ │ Check (opt-outs) │
└────────────────┘ └───────────┬───────────┘
│
┌─────────▼─────────┐
│ Send Queue │
│ (Redis / RabbitMQ) │
└───┬─────────────┬──┘
│ │
┌──────────────▼──┐ ┌───────▼───────────┐
│ SMPP Worker Pool │ │ REST API Worker │
│ (bulk, throttled, │ │ (transactional, │
│ TRX bind, TLS) │ │ low-volume) │
└──────────┬─────────┘ └──────────┬─────────┘
│ │
┌──────────▼──────────────────────────▼─────────┐
│ Telnyx Platform │
│ (SMPP Server + Messaging API v2) │
└──────────────────────┬───────────────────────┘
│
Carrier Network / Handsets
│
Inbound replies & delivery receipts
│
┌──────────────────────▼───────────────────────┐
│ Webhook Server (REST) / deliver_sm (SMPP) │
│ → Conversation routing, keyword handling, │
│ opt-out list updates, DLR logging │
└──────────────────────────────────────────────┘
Cross-cutting: Message/Contact DB, Monitoring Dashboard, Error-code Alerting
See docs/architecture-diagrams/ for detailed diagrams per day.
Common issues and resolutions are documented in docs/troubleshooting.md and docs/telnyx-error-codes.md, covering:
- Messages stuck in "sent" with no finalized delivery receipt (carrier-dependent DLR support)
- SMPP bind rejected or dropped (credential/TLS/enquire_link timeout issues)
- Off-net messages filtered due to missing 10DLC/toll-free registration
- Throughput throttling and per-number rate limits causing queued delays
- Concatenated SMS displaying out of order or with header artifacts
- Inbound webhook not firing (Messaging Profile webhook misconfiguration)
Telnyx contract terms (e.g., SMPP minimum commitments), throughput limits, and compliance rules change — always confirm against current official sources before teaching or deploying.
- Telnyx Developer Documentation: https://developers.telnyx.com
- Telnyx Messaging API Reference: https://developers.telnyx.com/api/messaging/send-message
- Telnyx SMPP Set-up Guide: https://support.telnyx.com/en/articles/1667062-short-message-peer-to-peer-set-up-guide
- Telnyx SMS Guide (Help Center): https://support.telnyx.com/en/collections/133103-telnyx-sms-guide
- 10DLC Compliance Directory: https://support.telnyx.com (search "10DLC Compliance Directory")
- SMPP Protocol Specifications: https://smpp.org
Contributions to improve labs, fix errata, or add advanced modules are welcome. Please open an issue or submit a pull request following the guidelines in CONTRIBUTING.md.
This training material is released under the MIT License.
Questions or feedback? Open an issue in this repository or contact the training team.