Skip to main content

Best Practices

A short, opinionated checklist for running the Agile Telecom SMS API in production.

Throughput and Rate Limiting​

  • REST sustained throughput — Plan for a few hundred submissions per second per API key by default. For higher volumes, ask the wholesale team to lift the limit or move to SMPP.
  • SMPP for high volume — A single SMPP TRX bind reliably sustains thousands of TPS. Combine up to four binds per account; see the SMPP reference.
  • Back-off on 429 — Implement exponential back-off with jitter when you receive 429 Too Many Requests. Don't retry tighter than the headers tell you to.
  • Batch in one call — When you have many destinations with the same body, send them as a single request with multiple destinations rather than one request per number.

Retries​

  • Idempotency — Set a stable globalId on the request and stable ids per message. If a request fails before you can read the response, you can retry safely if your application checks for an existing globalId.
  • Retryable codes — 408, 429, 5xx. Anything else is a permanent failure for that send.
  • Cap retries — At most 3 attempts with back-off. Beyond that, alert and stop — the issue is usually upstream.

Opt-out Compliance​

  • Always implement opt-out for marketing traffic. The minimum is STOP / STOP ALL keywords on inbound (see Inbound SMS).
  • Persist opt-out state in your own database, keyed by phone number, and consult it before every send.
  • One-click STOP language — Include Reply STOP to opt out (or local equivalent) in marketing SMS. Some countries make it mandatory.
  • Quiet hours — Respect local quiet-hour rules (typically 21:00 → 09:00 local time).

Number Hygiene​

  • Validate before sending — Use MNP lookup to detect invalid or ported numbers; saves money and improves deliverability stats.
  • Reject obvious garbage early — Empty, too-short, non-international numbers.
  • Credit check — Use the credit-check endpoint for large campaigns to detect "you'll run out at message 47k" before you start.

Encoding and Length​

  • Choose GSM-7 when you can — A non-GSM character (an emoji, a stray «) flips the whole message to UCS-2 and roughly halves the per-part length. Strip or replace if you don't need it.
  • Keep transactional under one part — 160 GSM-7 characters or 70 UCS-2. Two-part transactional SMS doubles cost without value for OTPs and confirmations.
  • Sender ID — Pre-register alphanumeric sender IDs where local regulations require it (Italy, India, France, UAE, etc.). Otherwise messages may be silently rewritten or dropped.

Observability​

  • Log every submission with globalId, id, destination and timestamp.
  • Wire DLRs to the same record — Match the id you logged on submission with the DLR that arrives later.
  • Track these KPIs:
    • Submission accepted rate (should be near 100%).
    • DLR DELIVERED rate per operator and country.
    • Average time submit → DLR final state.
    • REJECTED and UNDELIVERABLE rates (anomalies often mean sender-ID issues).

Security​

  • API keys in env vars only, never in client code or repos.
  • Rotate keys every 90 days in high-traffic accounts.
  • IP whitelist your backend's outbound IP at the platform.
  • HTTPS only — From January 15th, 2026 plain HTTP is rejected. Audit any legacy clients now.

Operational Playbook​

  1. Define a single, owned SMS service in your architecture — every team calls it, not the platform directly.
  2. Cache opt-out state, sender ID configuration and DLR records there.
  3. Expose metrics so on-call sees deliverability dipping before users do.
  4. Simulate before launch — Use simulation: true on send to dry-run your payload at scale.

Next Steps​