New: HTTP API Gateway for SMS Delivery

Product Update November 5, 2025 MOBITELSMS Engineering

Why HTTP API Matters Alongside SMPP

SMPP has been the backbone of A2P messaging for decades, and for good reason: it is a purpose-built, binary, session-oriented protocol designed for high-throughput SMS delivery. But the modern messaging ecosystem does not run on SMPP alone. A growing number of SMS aggregators, cloud communication providers, and regional carriers expose only HTTP-based REST APIs for message submission. If your routing engine only speaks SMPP, you cannot reach them without building middleware.

The new HTTP API Gateway adapter solves this by sitting natively inside the MOBITELSMS routing engine as a first-class gateway type, right alongside SMPP and SS7. When the SMS routing algorithm selects an HTTP API gateway as the termination point, the adapter translates the internal message structure into a JSON POST request, handles authentication, manages retries, and processes the provider's response -- all without any external process or queuing layer.

This matters for practical reasons. REST APIs are accessible from any language and toolchain. They use standard HTTP semantics that load balancers, CDNs, and observability tools already understand. Webhook-based delivery receipts integrate naturally with event-driven architectures. And for operators who want to use providers like Twilio, Vonage, Infobip, or MessageBird as termination endpoints, HTTP is the only option those providers offer.

Architecture: Where the Adapter Lives

The HTTP API adapter is implemented as a native gateway type within the core routing engine. In the database, SMS gateways now support an HTTP_API type alongside the existing SMPP, SS7, EIMS, and other types. When the routing engine evaluates dial peers and selects a gateway of type HTTP_API, the adapter takes over message delivery.

Internally, the adapter maintains a persistent libcurl handle pool per gateway, with connection keep-alive enabled and DNS caching to minimize latency on repeated requests. Each gateway configuration includes a base URL, authentication headers, a request template, and response parsing rules. The adapter formats the outbound JSON payload, signs it if required, sends the HTTP POST, and maps the provider's response code back to a standard SMPP-equivalent status for CDR generation and error handling.

This design means no separate process, no message queue hop, and no additional latency beyond the HTTP round-trip itself. The adapter participates directly in the routing engine's failover logic: if an HTTP API gateway returns a 5xx error or times out, the engine proceeds to the next termination point in the routing table, exactly as it would for a failed SMPP delivery attempt.

Configuration and Authentication

Each HTTP API gateway is configured through the admin dashboard with the following parameters:

Base URL -- the provider's message submission endpoint (e.g., https://api.provider.com/v2/sms/send)
Auth type -- Bearer token, API key header, or HTTP Basic authentication
Custom headers -- arbitrary key-value pairs appended to every request (useful for account IDs, API versions, or correlation tokens)
Retry policy -- maximum retry count, backoff interval, and which HTTP status codes should trigger a retry vs. a permanent failure
TPS limit -- per-gateway transactions-per-second cap with automatic throttling and queuing
Request timeout -- maximum wait time per HTTP request before marking the attempt as failed

The adapter sends messages as JSON POST requests with a straightforward structure:

{
  "to": "+14155551234",
  "from": "+18005559876",
  "message": "Your verification code is 482901",
  "encoding": "GSM-7",
  "callback_url": "https://your-platform.com/dlr/webhook"
}

The response from the provider is parsed for a message ID, delivery status, and any error details. Standard HTTP status codes are mapped to internal result codes: 200/201/202 indicate acceptance, 400-series indicate permanent rejection (bad number, invalid content), and 500-series trigger retry logic.

Health Monitoring and Uptime Tracking

Reliable routing depends on knowing which gateways are actually reachable. The HTTP API adapter runs periodic health checks against each configured gateway, using a lightweight probe request (typically a GET to the provider's status endpoint, or a HEAD request to the submission URL). The results are written to our distributed cache with a 120-second TTL:

// Gateway health status (stored with auto-expiring TTL)
{
  "gateway_id": 42,
  "status": "online",
  "latency_ms": 42,
  "last_check": "2025-11-05T14:32:01Z",
  "uptime_pct": 99.87,
  "consecutive_failures": 0
}

The routing engine reads this health data when building the termination candidate list. A gateway with consecutive failures above a configurable threshold is temporarily removed from routing, preventing message loss during provider outages. When health checks resume successfully, the gateway is automatically re-added.

Balance Tracking

Many third-party SMS providers expose a balance or credits endpoint. The adapter supports optional balance polling, hitting a configurable URL at regular intervals and parsing the remaining balance from the JSON response. This balance appears in the admin dashboard alongside the gateway's connection status, giving operators a single view of both reachability and remaining capacity.

Balance thresholds can trigger alerts: when a provider account drops below a configured minimum, the system logs a warning and can optionally deprioritize that gateway in routing decisions, shifting traffic to better-funded termination paths before the provider account runs dry.

Rate Limiting and Throughput Control

Each HTTP API gateway has an independent TPS (transactions per second) limit. The adapter uses a token-bucket algorithm to enforce this cap, smoothing traffic spikes without dropping messages. When the submission rate exceeds the gateway's TPS limit, excess messages are held in a short internal buffer and released as capacity becomes available.

This is critical for third-party providers that enforce strict rate limits at the API level. Exceeding a provider's rate limit typically results in 429 responses and temporary blocks. The adapter's client-side throttling prevents this by never exceeding the configured ceiling, regardless of how much inbound traffic the routing engine sends to that gateway.

The current TPS for each gateway is visible in the admin dashboard as a real-time meter, alongside the configured maximum. Operators can adjust TPS limits without restarting the service -- changes take effect on the next health check cycle.

CDR Generation

The adapter generates CDR (Call Detail Record) entries only on confirmed delivery acceptance -- that is, when the provider returns a success status code. This prevents phantom CDR records for messages that were never actually accepted by the downstream provider. Each CDR includes the gateway ID, provider message ID, submission timestamp, HTTP response code, round-trip latency, and the calculated billing price based on the configured SMS rate and segment count.

For providers that support delivery receipts via webhook callbacks, inbound DLR updates are matched to the original CDR by provider message ID and update the final delivery status (delivered, failed, expired, rejected). This gives operators end-to-end visibility into message lifecycle, from initial submission through final handset delivery.

Use Case: Third-Party Termination

The most immediate use case is connecting to third-party SMS APIs as termination endpoints. Consider an operator who has direct SMPP interconnects with three carriers but also wants to route overflow traffic through Twilio or Vonage. Previously, this required a separate middleware application to bridge the protocol gap. With the HTTP API adapter, the operator simply adds a new gateway of type HTTP_API, configures the provider's credentials and endpoint, assigns it to the appropriate dial peers, and the routing engine handles the rest -- including failover, rate limiting, and CDR reconciliation.

This pattern is especially valuable for geographic redundancy. An operator might use direct SMPP for domestic traffic (lower latency, lower cost) while routing international messages through HTTP API providers that have better reach in specific regions. The routing engine's LCR and quality-based algorithms work identically across gateway types, making protocol differences invisible to the routing logic.

Getting Started

The HTTP API gateway type is available now in all MOBITELSMS plans. To add your first HTTP API gateway, navigate to SMS Gateways in the admin dashboard, click Add Gateway, and select HTTP API as the gateway type. Configure the provider's base URL, authentication, and TPS limit, then assign the gateway to your routing rules. Health monitoring and balance tracking activate automatically once the gateway is saved.

For detailed configuration instructions and API response mapping examples, see the HTTP API Gateway section in the platform documentation, or reach out to our engineering team for guidance on connecting specific providers.