Skip to main content

What You Can Do with the Messaging APIs

The HORISEN Messaging APIs let you submit SMS traffic (over HTTPS, SMPP, or Binary-Safe), receive inbound (MO) messages in real time, and understand how MNP and SMS data move through the platform internally.

Send SMS (HTTPS, SMPP, or Binary-Safe)​

  • Use the HTTPS MT API for simple, JSON-based server-to-server submission.
  • Use the SMPP API (v3.4 / v5.0) for high-throughput binds.
  • Use the Binary-Safe API when you need direct control over raw SMPP submit_sm/deliver_sm PDU fields (UDH, data coding, ESM class) beyond what the standard HTTPS API exposes.

Receive Inbound SMS (MO)​

  • Use the Inbound SMS API for real-time MO forwarding via GET/POST callback (URL parameters) or a JSON webhook.
  • Use the Premium Transit API for premium/short-code MO-MT services with keyword and session handling, and per-message pricing.

Understand the Platform's Internal Data Flow​

  • The Data Flow diagrams document how MNP resolution (over SS7, ENUM, and the HTTP API) and SMS routing (SMPP delivery, MO forwarding, SS7 MT/MO cases, retries) work internally. These are architecture references, not callable endpoints — for actual MNP lookups, see the separate MNP API section.

Messaging API Modules​

API ModuleDescription
HTTPS MT APIJSON-over-HTTPS SMS submission (text, binary, or WSI), authenticated via API Key or OAuth2, with configurable DLR webhooks.
Binary-Safe SMS HTTP APIExtension of the HTTPS API exposing raw SMPP submit_sm/deliver_sm PDU fields for full protocol control.
SMPP APISMPP v3.4 (compatible with v5.0) binds; this section documents unified DLR error codes and custom NACK statuses.
Inbound SMS APIReal-time MO forwarding via GET/POST callback (URL parameters) or JSON webhook.
Premium Transit APIMO-MT premium/short-code SMS over HTTP, with keyword, session, and per-message pricing support.

Authentication​

Each API uses its own authentication method:

  • HTTPS MT API — an X-API-Key header, or an OAuth2 Bearer token obtained via the client_credentials grant. If both are present, X-API-Key takes precedence.
  • Binary-Safe API — username/password or OAuth2 token, optionally combined with mTLS and IP whitelisting.
  • Premium Transit API — account, username, and password sent as MT submission parameters; both sides exchange static IP addresses for MO/MT delivery.

Quick Examples​

Send an SMS (HTTPS MT API)​

curl -X POST "https://sms.example.org/bulk/v5/send" \
-H "X-API-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "sender": "MyCompany",
  "receiver": "41790000000",
  "text": "Hello from MyCompany!",
  "dlrUrl": "https://yourapp.com/dlr"
}'

Inbound SMS Webhook Example (JSON payload)​

{
  "id": "d1ec69e2-bcfd-11ed-afa1-0242ac120002",
  "src": "41781234567",
  "dst": "41587000000",
  "text": "This is an MO",
  "received": "2006-01-02T15:04:05Z07:00"
}

SMPP DLR Error Reference​

The SMPP API documents unified DLR error codes and custom NACK statuses returned for MT submissions, for example:

ValueDescription
0No error.
29Absent subscriber.
990HLR failure.
999Repeated submission (possible looping).

See the full list on the SMPP API page.

Typical Integrations​

Customer Portals​

Send MT messages over the HTTPS MT API, receive DLRs as webhooks or via query, and display traffic/routing stats.

Chatbots & Automation Systems​

Receive MO messages via the Inbound SMS API webhook and reply in real time over the HTTPS MT API.

Premium / Short-Code Services​

Run keyword-based, session-aware premium SMS services with per-message pricing via the Premium Transit API.

Enterprise Notification Systems​

Send OTPs, alerts, and transactional messages over HTTPS or SMPP, with delivery confirmed via DLRs.