Endpoints

Service Endpoints

The platform exposes a set of service endpoints that allow client applications to interact with the system. These endpoints cover authentication, authorization, SMS infrastructure access, and message delivery operations.

The API is available over two protocols — REST (HTTP/JSON on port 8080) and gRPC (HTTP/2 on port 44044). This page provides a conceptual overview of the endpoints. For complete API specifications with all fields and response codes, see the REST API and gRPC API reference pages.

Authentication Endpoints

Authentication endpoints are responsible for user management and access control. They allow clients to register, authenticate, and manage permissions within the system.

Register

Registers a new user account.

// POST /api/v1/auth/register
{
  "email": "user@example.com",
  "password": "secure-password",
  "app_name": "my-application"
}

// Response
{
  "user_id": 1
}

The system validates input fields and detects duplicate email addresses. Each registered user receives a unique app_id and app_secret used for API access.

Login

Authenticates a user and returns a JWT token.

// POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "secure-password",
  "app_id": 1
}

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

The returned token must be included in the Authorization: Bearer <token> header for all protected API calls.

IsAdmin

Checks whether a user has administrative privileges.

// Request
{ "user_id": 1 }

// Response
{ "is_admin": true }

DeleteUser

Removes a user account from the system.

// Request
{ "user_id": 3 }

// Response
{ "result": true }

SMS Endpoints

SMS endpoints provide access to messaging functionality and SMPP infrastructure status.

SendMessage

Submits an SMS message through the gateway.

// POST /api/v1/sms/send
{
  "esme": 1000,
  "source": "+123456789",
  "destination": "+987654321",
  "message": "Hello world",
  "transaction_id": "tx-001"
}

// Response
{
  "success": true,
  "error": "",
  "esme": 1000,
  "transaction_id": "tx-001",
  "message_id": "msg-uuid",
  "status": "submitted",
  "sms_ids": ["sms-001", "sms-002"],
  "task_id": 12345
}

The esme field specifies the target SMPP link or pool ID. If the message is long, the platform automatically segments it and returns multiple sms_ids.

CheckESME

Checks the availability and state of an SMPP connection.

// POST /api/v1/sms/check-esme
{ "esme": 100 }

// Response
{
  "persist": true,
  "system_id": "my_system",
  "error": ""
}

Returns whether the connection is currently active (persist: true) and the SMPP system ID of the remote SMSC. Use this endpoint to verify connectivity before sending messages.

SmsInfo

Returns delivery information about a previously sent message.

// POST /api/v1/sms/info
{
  "esme": 100,
  "message_id": "msg-uuid"
}

// Response
{
  "message_id": "msg-uuid",
  "mode": "single",
  "parts": { "1": "DELIVERED" },
  "delivered_count": 1,
  "sent_at": 1937082918,
  "updated_at": 1937082925,
  "transaction_id": "tx-001",
  "task_id": 12345,
  "status": "DELIVERED",
  "error": ""
}

For multipart messages, the parts field contains delivery status for each segment individually.

Monitoring Endpoints

These endpoints are publicly accessible (no authentication required) and provide system health and performance data.

Error Handling

The platform uses a consistent error response format across all endpoints:

All error responses follow the format:

{
  "error": "description of the error"
}

Typical Integration Flow

A typical integration follows these steps:

1. Register a user account via /api/v1/auth/register
2. Login to obtain a JWT token via /api/v1/auth/login
3. Verify SMPP connectivity via /api/v1/sms/check-esme
4. Send messages via /api/v1/sms/send (REST) or sms.v1.SmsService/SendMessage (gRPC)
5. Track delivery via /api/v1/sms/info or sms.v1.SmsService/SmsInfo