Smarter SMS Routing with XConnect NPQ in SMPP Router

SMPP Router
1

XConnect-50pc
XConnect-50pc1600×1200 38.5 KB

As mobile number portability has become widespread, traditional SMS routing methods have been challenged. Routing decisions based solely on number prefixes no longer guarantee delivery to the correct mobile network, resulting in failed deliveries, increased retries, unnecessary operational costs, and customer complaints.

To meet this challenge, Melrose Labs SMPP Router now includes native support for XConnect’s Number Portability Query (NPQ) service. This integration brings real-time, accurate network intelligence into the routing engine - enabling you to deliver SMS messages more reliably and cost-effectively.

The Problem with Prefix-Based Routing

Mobile Number Portability (MNP) allows users to switch network providers while retaining their original phone numbers. This breaks the long-held assumption that the number prefix indicates the mobile network. The effects of this on SMS delivery can be significant:

  • SMS messages are routed to the wrong operator.
  • Delivery attempts fail or are delayed.
  • Systems retry messages or escalate errors.
  • Messages incur billing or interconnect costs.

To maintain routing accuracy in MNP markets, systems must determine the current operator of a mobile number - this is where XConnect NPQ comes in.

XConnect NPQ and Melrose Labs SMPP Router

XConnect’s NPQ service provides live network information for an MSISDN by querying authoritative portability databases. SMPP Router leverages this data during message routing to:

  • Accurately identify the terminating operator.
  • Select the most appropriate target set or route.
  • Reduce undeliverable messages.
  • Eliminate waste from misrouted traffic.

The integration supports high-throughput scenarios and caching for performance optimisation.

Enabling XConnect NPQ Support in SMPP Router

To use XConnect NPQ, configure the lookup section of the SMPP Router configuration as follows:

  "lookup": {
    "enabled": true,
    "url": "https://lookup.xconnect.net/query/{msisdn}?service=npq",
    "auth_username": "YOUR_XCONNECT_USERNAME",
    "auth_password": "YOUR_XCONNECT_PASSWORD",
    "use_msisdn_cache": true,
    "worker_count": 128,
    "worker_count_min": 5,
    "max_queue_size": 10000
  }

Key Options Explained

Field Description
enabled Enables the MSISDN lookup.
url XConnect endpoint with {msisdn} placeholder.
auth_username / auth_password Basic auth credentials for the XConnect API.
use_msisdn_cache Enables in-memory caching of lookup results.
worker_count Number of concurrent threads for lookup.
worker_count_min Minimum number of concurrent threads for lookup.
max_queue_size Maximum number of queued lookup requests.

Once configured, SMPP Router will perform lookups automatically during message processing and the lookup result can be used to inform routing decisions.

MSISDN Lookup: Intelligent Network-Based Routing

The SMPP Router’s MSISDN lookup capability provides real-time network identification for mobile subscribers, enabling intelligent routing decisions based on destination network characteristics. This powerful feature transforms basic number-based routing into sophisticated, network-aware message delivery.

How MSISDN Lookup Works

When a message arrives at the SMPP Router, the platform can automatically identify the destination mobile network by performing an MSISDN (Mobile Station International Subscriber Directory Number) lookup. This process determines the Mobile Country Code (MCC) and Mobile Network Code (MNC) associated with the destination number, providing crucial routing intelligence.

The lookup process operates through multiple layers:

Cache-First Architecture: The system maintains an intelligent cache of previously looked-up numbers with configurable TTL (Time To Live) periods, typically set to 60 minutes. This ensures optimal performance for frequently messaged destinations while maintaining data freshness.

Asynchronous Processing: Live lookups are handled by dedicated worker threads, preventing any blocking of message processing. When a cache miss occurs, the lookup is queued for background processing and on completion the message continues through the routing engine.

External Integration: The system connects to XConnect’s Number Portability Query (NPQ) services via HTTP APIs.

Practical Applications

Network-Specific Routing: Messages can be automatically routed to different upstream providers based on the destination network. For example, messages to Network A might route through Provider X (who offers better rates for that network), while messages to Network B route through Provider Y.

Routing Optimisation: By identifying the destination country and network, the router can select optimised routes, reducing latency and improving delivery rates.

Rate Optimisation: Different upstream providers often have varying rates for different networks. The MSISDN lookup enables automatic selection of the most cost-effective route for each destination network.

Compliance and Filtering: Certain networks may require specific message formatting, content filtering, or regulatory compliance. The lookup capability enables automatic application of network-specific rules.

Privacy: Lookup to identify the destination network can be used to perform more direct routing of messages and reduce exposure of messages to 3rd parties.

Management and Monitoring

The MSISDN lookup system provides comprehensive management capabilities through REST APIs:

  • Live Lookup: POST /lookup/msisdn for real-time number queries
  • Cache Management: GET /lookup/msisdn/{number} for cache-only lookups
  • Batch Processing: POST /lookup/batch for bulk lookup operations
  • Statistics: GET /lookup/stats providing detailed performance metrics
  • Cache Control: DELETE /lookup/cache/clear for cache management

Performance and Scalability

The lookup system is designed for high-performance environments with configurable worker thread pools, queue management, and caching. It can handle thousands of lookups per second while maintaining low latency for cached results (typically sub-millisecond) and reasonable response times for live lookups.

Overflow Protection: The system includes queue size limits and intelligent degradation, ensuring that lookup failures don’t impact overall message processing performance.

Resource Management: Worker threads are dynamically managed based on load, with configurable minimum and maximum worker counts to balance resource usage with performance requirements.

This MSISDN lookup capability transforms the SMPP Router from a simple message forwarder into an intelligent routing platform, enabling operators to optimize delivery routes, reduce costs, and improve overall service quality through network-aware decision making.

MT Route Configuration Examples: LCR Map vs Normal Routing

Example 1: LCR Map Routing (Network-Based Least Cost Routing)

{
  "routes-mt": [
    {
      "lcrmap": {
        "match": "destination",
        "type": "mnc",
        "map": [
          {
            "targetset": "vodafone_premium",
            "coverage": [
              {
                "key": "23415",
                "cost": 0.042,
                "ignore": false
              }
            ]
          },
          {
            "targetset": "o2_direct",
            "coverage": [
              {
                "key": "23410",
                "cost": 0.038,
                "ignore": false
              }
            ]
          },
          {
            "targetset": "ee_routes",
            "coverage": [
              {
                "key": "23430",
                "cost": 0.045,
                "ignore": false
              }
            ]
          },
          {
            "targetset": "three_uk",
            "coverage": [
              {
                "key": "23420",
                "cost": 0.040,
                "ignore": false
              }
            ]
          },
          {
            "targetset": "international_tier1",
            "coverage": [
              {
                "key": "26201",
                "cost": 0.048,
                "ignore": false
              },
              {
                "key": "26202",
                "cost": 0.052,
                "ignore": false
              },
              {
                "key": "20801",
                "cost": 0.055,
                "ignore": false
              }
            ]
          },
          {
            "targetset": "budget_routes",
            "coverage": [
              {
                "key": "23415",
                "cost": 0.065,
                "ignore": false
              },
              {
                "key": "23410", 
                "cost": 0.062,
                "ignore": false
              }
            ]
          }
        ]
      }
    }
  ]
}

Example 2: Normal Criteria-Based Routing (Country/Prefix Based)

{
  "routes-mt": [
    {
      "criteria": {
        "match": "destination",
        "type": "country",
        "value": "44"
      },
      "targetset": "uk_carriers"
    },
    {
      "criteria": {
        "match": "destination", 
        "type": "country",
        "value": "49"
      },
      "targetset": "germany_carriers"
    },
    {
      "criteria": {
        "match": "destination",
        "type": "country", 
        "value": "33"
      },
      "targetset": "france_carriers"
    },
    {
      "criteria": {
        "match": "destination",
        "type": "prefix",
        "value": "447900"
      },
      "targetset": "uk_premium_numbers"
    },
    {
      "criteria": {
        "match": "destination",
        "type": "prefix",
        "value": "491701"
      },
      "targetset": "german_mobile_premium"
    },
    {
      "criteria": {
        "match": "destination",
        "type": "exact",
        "value": "12345"
      },
      "targetset": "test_routes"
    }
  ]
}

Configuration Explanations

LCR Map Routing (Example 1)

Purpose: Intelligent network-aware routing based on MSISDN lookup results with cost optimization.

How it Works:

  1. MSISDN Lookup: When a message arrives, the system performs an MSISDN lookup to determine the destination network (MCC+MNC)
  2. Network Identification: The lookup returns network information including MNC (Mobile Network Code)
  3. Cost-Based Selection: The system searches the LCR map for the destination MNC and selects the lowest-cost route
  4. Fallback Logic: If multiple targetsets cover the same MNC, the one with the lowest cost wins

Key Components:

  • match: "destination": Indicates we’re routing based on destination number
  • type: "mnc": Specifies that routing decisions are based on Mobile Network Codes
  • map array: Contains routing options for different networks
  • coverage array: Lists the specific MNC codes each targetset can handle
  • cost: Routing cost for least-cost route selection (lower is better)
  • ignore: Flag to temporarily disable a route without removing it

Example Routing Logic:

  • Message to 447900123456 → MSISDN lookup returns MNC 23415 (Vodafone UK)
  • System finds two options: vodafone_premium (cost: 0.042) and budget_routes (cost: 0.065)
  • Result: Routes via vodafone_premium (lowest cost)

Advantages:

  • :white_check_mark: Network-specific routing optimization
  • :white_check_mark: Automatic cost optimization
  • :white_check_mark: Real-time network intelligence
  • :white_check_mark: Support for multiple carriers per network
  • :white_check_mark: Easy rate management

Normal Criteria-Based Routing (Example 2)

Purpose: Traditional static routing based on number patterns and prefixes.

How it Works:

  1. Pattern Matching: System evaluates destination number against configured criteria
  2. First Match Wins: Routes are processed in order, first matching rule is used
  3. Static Rules: No external lookup required, immediate routing decision

Match Types:

  • country: Matches country code prefix (e.g., “44” for UK)
  • prefix: Matches specific number prefix (e.g., “447900” for UK premium)
  • exact: Exact number match (e.g., “12345” for test numbers)
  • regex: Regular expression matching (not shown but supported)

Example Routing Logic:

  • Message to 447900123456:
    1. Checks country “44” → Matches UK, routes to uk_carriers
    2. But since prefix “447900” appears later and is more specific, would route to uk_premium_numbers
  • Message to 491701234567: Routes to german_mobile_premium (prefix match)
  • Message to 12345: Routes to test_routes (exact match)

Advantages:

  • :white_check_mark: Simple and predictable
  • :white_check_mark: No external dependencies
  • :white_check_mark: Fast routing decisions
  • :white_check_mark: Easy to understand and troubleshoot
  • :white_check_mark: Works without MSISDN lookup service

Disadvantages:

  • :cross_mark: No network-aware intelligence
  • :cross_mark: Cannot distinguish between carriers in same country
  • :cross_mark: Static configuration requires manual updates
  • :cross_mark: No automatic cost optimization

Combined Configuration Strategy

Most production deployments use both approaches together:

{
  "lookup": {
    "enabled": true,
    "url": "https://api.network-lookup.com/{msisdn}"
  },
  "routes-mt": [
    {
      "lcrmap": {
        "match": "destination",
        "type": "mnc",
        "map": [
          {
            "targetset": "vodafone_direct",
            "coverage": [{"key": "23415", "cost": 0.035, "ignore": false}]
          }
        ]
      }
    },
    {
      "criteria": {
        "match": "destination",
        "type": "country", 
        "value": "44"
      },
      "targetset": "uk_fallback"
    },
    {
      "criteria": {
        "match": "destination",
        "type": "prefix",
        "value": "999"
      },
      "targetset": "default_routes"
    }
  ]
}

Processing Order:

  1. LCR Map First: If MSISDN lookup succeeds and finds matching MNC
  2. Criteria-Based Fallback: If lookup fails or no MNC match found
  3. Default Route: Final fallback for any unmatched traffic

This hybrid approach provides intelligent network-aware routing when possible, with reliable fallback routing for all scenarios.

Using SMPP Router’s HTTP Lookup API

SMPP Router provides a HTTP Lookup API for interacting with the NPQ service directly. An OpenAPI v3 document is available for this API. Examples of some API calls are below:

MSISDN Lookup

curl -X POST http://localhost:8080/lookup/msisdn \
  -H "Authorization: Bearer my_router_token" \
  -H "Content-Type: application/json" \
  -d '{"msisdn": "447700123456"}'

Check Cached Entry

curl -X GET http://localhost:8080/lookup/msisdn/447700123456 \
  -H "Authorization: Bearer my_router_token"

Using the Command-Line Tool (smpproutercli)

SMPP Router includes a shell-based utility for direct lookup and cache operations:

Lookup

smpproutercli lookup-msisdn 447700123456

Remove MSISDN from Cache

smpproutercli lookup-cache-remove 447700123456

View and Clear Statistics

smpproutercli lookup-stats
smpproutercli lookup-stats-clear

These commands are useful for diagnostics, development testing, and manual validation of routing decisions.

Performance and Scalability

SMPP Router is optimised for high performance in production environments:

  • Cache Hit: <0.01ms response time
  • Live NPQ Lookup: 50–300ms, depending on XConnect response time and region
  • Throughput: Thousands of lookups per second (subject to NPQ account limits)

Caching and worker pool controls allow tuning for latency-sensitive or high-volume use cases.

Availability and Licensing

The NPQ capability is included in the latest build of SMPP Router. A free licence for SMPP Router is available, valid until 1st September 2026, for evaluation and full production use.

You can download SMPP Router from:

:link: melroselabs.com/smpprouter

Conclusion

With XConnect NPQ support, SMPP Router gives messaging providers the tools to route with intelligence, precision, and efficiency. It mitigates the risks of number portability, reduces operational costs, and increases delivery success—without requiring extensive external integration.

If accurate routing matters to your business, this enhancement ensures you’re ready for the reality of modern mobile networks.