SMS API Integration: Acceptance, Delivery Receipts and Retries

Messaging integrations rarely fail because a developer could not format a request. They fail on the semantics: what a successful response actually promised, which status values are final, what a duplicate callback means, and what to do when the connection drops after the request was sent.

This article is an integration checklist, not API documentation. MessageTrade's core gateway supports SMPP and HTTP, and the connection method, endpoint, throughput and enabled functions are agreed for each customer during solution design and onboarding — so the exact specification comes from that process, not from a public reference page. If you are scoping that work, start with a managed SMS gateway for SaaS applications service.

Acceptance is a receipt, not a delivery

The single most consequential misunderstanding in messaging integrations is treating a successful submission response as delivery. Acceptance means the message was taken for onward handling. Delivery is a later, separate event that may or may not arrive. Provider platforms publish their own status vocabularies — one public example lists several intermediate and final states — and those vocabularies differ, so the mapping between your provider's statuses and your own internal states must be written down explicitly rather than inferred.

• List every status you can receive and mark each one as intermediate or final.
• Decide which internal state each maps to, and which ones your product should surface to a user.
• Decide which are safe to retry and which are permanent, and record why.
• Keep an 'unknown status' branch that logs and alerts instead of guessing, because vocabularies change.

Correlation and callback handling

Every message needs an identifier that your system generates and stores before submission, alongside whichever reference the platform returns. A locally generated key makes local correlation and investigation possible when a response never arrives; reconciling that submission on the provider side depends on the correlation and status functions supported by your agreed integration, not on your own key alone.

• Store your own request key first, then the returned reference when you have it.
• Expect callbacks out of order: a final status can arrive before an intermediate one.
• Expect duplicates, and make callback processing safe to repeat so a redelivered status does not double-count or re-trigger a side effect.
• Ignore transitions backwards from a final state rather than overwriting a terminal outcome.
• Return your response quickly and process asynchronously, so a slow internal step does not cause callback retries.
• Handle your own callback outage: when the endpoint was down, reconcile afterwards using the supported status lookup or agreed reporting rather than resending traffic.

The timeout question

A timeout is the hardest case because the request may have succeeded. The AWS Builders' Library guidance on idempotent APIs sets out the general principle: a retry is only safe when the receiving side can recognise the same request identity and avoid repeating the effect. In messaging that support is specific to whatever is agreed for your integration, so do not assume deduplication exists — confirm it. Where it is not available, reconcile first and resend only when you have established that nothing was sent.

Bound your retries: a maximum attempt count, backoff with jitter, an overall validity window after which the message is no longer useful, and a spend ceiling. An unbounded retry loop against a degraded path is an outage amplifier and a cost event at the same time.

Authentication, limits and abuse

Authentication for the integration is agreed as part of onboarding; treat those credentials as production secrets, keep them out of application logs and client-side code, and plan rotation before you need it. Rate limiting deserves the same attention on your own send-triggering endpoints: as OWASP notes in its guidance on unrestricted resource consumption, missing limits on operations that send messages can turn into a direct cost problem. Per-user, per-number and per-tenant limits, plus spend alerting, belong in the first release rather than the third.

Before-launch checklist

These checks prepare an integration for failures that a basic send test does not exercise.