Recommended message record
- Provider message ID and your request ID
- Recipient in normalized E.164 format
- Country, sender, route and template reference
- Segment count and submission timestamp
- Latest status, status time and failure category
Developer guide
Build a production-ready SMS API integration
Use this public guide to design authentication, sending, status tracking, retries and webhook processing. Your authenticated account documentation remains the source of truth for the exact base URL, endpoint paths, request fields, credentials and limits assigned to your account.
Quickstart architecture
From API key to final delivery status
Keep synchronous request handling short. Store the returned message identifier, then treat delivery reports as the final operational signal.
1. AuthorizeCreate and protect a key
2. ValidateNormalize recipient and text
3. SubmitSend one idempotent request
4. PersistStore message ID and context
5. ReceiveProcess status callbacks
6. ObserveMeasure delivery and latency
Request pattern
Keep credentials on your server
Never expose a secret API key in browser code, mobile applications, public repositories, screenshots or support messages.
Illustrative cURL patternUse account-specific URL and fields
curl -X POST "<BASE_URL><SEND_ENDPOINT>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
-d '{
"to": "+14155550123",
"message": "Your verification code is 482913"
}'Contract notice: Header names, endpoint paths and JSON fields above illustrate a safe client pattern; they are not a substitute for the exact contract displayed in your account API reference.
Response handling
Persist the identifier returned by the API
Store enough context to trace a request through delivery, support and reconciliation without logging message content or secrets unnecessarily.
Illustrative normalized responseExact fields may differ
{
"messageId": "provider-message-id",
"status": "accepted"
}Message lifecycle
API acceptance is not handset delivery
| Stage | Meaning | Application behavior |
|---|---|---|
| Accepted | The platform accepted the request for processing. | Persist the message ID; do not mark the SMS delivered. |
| Queued / processing | The message is awaiting or undergoing route submission. | Keep the state non-final and monitor latency. |
| Sent / submitted | The message was submitted downstream. | Wait for a final delivery report where available. |
| Delivered | A final delivery signal reports successful handset delivery. | Record delivery time and calculate end-to-end latency. |
| Failed / rejected / expired | A final signal indicates non-delivery or rejection. | Store the reason, classify it and retry only when the failure is retryable. |
Reliability rules
Design for retries without duplicate messages
Timeouts
Use explicit connection and response timeouts. An unknown client result does not prove the provider rejected the request.
Idempotency
Assign a unique request key and store it before submission so a retry cannot silently create a second user message.
Backoff
Retry transient failures with exponential backoff and jitter. Cap attempts and send persistent errors to an operational queue.
Rate limits
Queue work, respect the assigned limit and reduce concurrency after throttling instead of immediately retrying every request.
Secrets
Use separate keys by environment, restrict access, rotate keys and remove sensitive values from application logs.
Observability
Track request success, final delivery, p50/p95 latency, retry rate, webhook lag and failures by country and carrier.
Client behavior
Classify errors before retrying
Use the exact codes in your account reference. The categories below describe safe HTTP client behavior rather than claiming a platform-specific response contract.
| Response class | Typical interpretation | Recommended action |
|---|---|---|
| 2xx | Request accepted or processed according to the endpoint contract. | Parse and store the response; continue status tracking. |
| 400 / 422 | Invalid number, field, template or request shape. | Do not retry unchanged; validate and correct the request. |
| 401 / 403 | Credential, permission or policy problem. | Stop retries, protect the key and investigate access. |
| 429 | Assigned request rate exceeded. | Honor retry guidance, reduce concurrency and use backoff. |
| 5xx / network failure | Potential transient provider or network issue. | Retry with idempotency, backoff, jitter and a maximum attempt count. |
Webhooks
Treat callbacks as untrusted, repeatable events
At the edge
- Require HTTPS
- Verify the documented signature or authentication method
- Reject stale requests when timestamps are available
- Limit body size and parse defensively
- Acknowledge quickly after durable receipt
In processing
- Deduplicate by event or message identity
- Handle duplicate and out-of-order callbacks
- Use monotonic status rules for final states
- Queue business logic away from the HTTP handler
- Log outcome and latency without exposing secrets
Release discipline
Separate environments and plan for contract changes
An integration is easier to operate when test traffic, production traffic and API changes are visible and independently controlled.
Environment isolation
Use separate credentials, webhook endpoints, recipient allowlists and monitoring for development, staging and production. Never test failure handling by sending uncontrolled traffic from a production account.
Contract tests
Validate required response fields, status mappings and signature verification in automated tests. Preserve representative redacted payloads so a parser change can be tested without exposing recipient data or API secrets.
Change management
Track the documented API version and changelog, review deprecation notices, deploy compatible clients before a deadline and keep a rollback path. Do not infer compatibility from one successful request.
Developer documentation map
API integration questions
Where do I find the exact TextPulse endpoint and fields?
Use the authenticated account API reference. It should be treated as authoritative for your base URL, endpoint paths, authentication headers, request fields, responses and assigned limits.
Should I send SMS directly from browser JavaScript?
No. A browser cannot safely keep a secret API key. Send requests from a trusted backend and expose only the minimum application endpoint your client needs.
When should my application retry?
Retry only transient network, throttling or server failures, using idempotency and bounded exponential backoff. Do not retry an unchanged validation or authorization failure.
How do I know whether a message was delivered?
Store the message identifier and process the documented delivery report or status-query result. A synchronous accepted response is not the final handset-delivery result.
Start with the exact account contract
Use this architecture guide for production safety, then copy the assigned endpoints and fields from your authenticated reference.