Quickstart

Quickstart

This section walks you through the minimal path from an empty host to your first sent SMS — about five minutes, assuming you already have a license file and access to your operator's SMSC.

If you need a detailed installation with full coverage of volumes, network configuration, and production-ready parameters, go directly to SMS Gateway Proxy Installation.

Prerequisites

Step 1. Prepare Directories and License

mkdir sms-gateway && cd sms-gateway
mkdir -p config journal/stat license logs smpp_rules storage

# Copy your license file
cp /path/to/your.lic license/

Minimal smpp_rules/smpp_rules.toml — one SMPP link to your operator:

[links.100]
esme_disabled = false
esme_addr = "smsc.your-provider.com"
esme_port = 2775
esme_systemid = "your_system_id"
esme_password = "your_password"
esme_rate = 100
esme_rate_burst = 100

The minimal config/config_local.yaml is provided by the vendor with the distribution — copy it as-is, fine-tuning comes later.

Step 2. Start the Platform

Create docker-compose.yml:

services:
  proxy:
    image: sms-sender-proxy:v1.0.0
    ports:
      - "8080:8080"      # REST API
      - "44044:44044"    # gRPC API
    volumes:
      - ./config:/app/config
      - ./journal:/app/journal
      - ./license:/app/license
      - ./logs:/app/logs
      - ./smpp_rules:/app/smpp_rules
      - ./storage:/app/storage
    depends_on: [redis, aerospike]
    restart: unless-stopped

  redis:
    image: redis:latest
    restart: unless-stopped

  aerospike:
    image: aerospike:ce-6.4.0
    restart: unless-stopped

Start:

docker compose up -d

Verify the proxy is alive:

curl http://localhost:8080/healthy
# {"status":"ok"}

Step 3. Register a User

Each client sends SMS under its own app_id. Create the first account:

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "change-me",
    "app_name": "quickstart"
  }'

The response includes a user_id — this will be your app_id in subsequent requests.

Step 4. Obtain a JWT Token

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "change-me",
    "app_id": 1
  }'

Response:

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

Save this token — it is valid for 12 hours by default.

Step 5. Send Your First SMS

curl -X POST http://localhost:8080/api/v1/sms/send \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-App-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "esme": 100,
    "source": "TestSender",
    "destination": "+998901234567",
    "message": "Hello from SMS Gateway Proxy",
    "transaction_id": "tx-001"
  }'

The response includes a message_id for tracing and a task_id for checking status later:

{
  "success": true,
  "esme": 100,
  "transaction_id": "tx-001",
  "message_id": "msg-uuid",
  "status": "submitted",
  "sms_ids": ["sms-001"],
  "task_id": 12345
}

If you receive a 403 — the client IP is not in the SMPP link's allowlist. If you receive a 429 — the rate limiter triggered; check the esme_rate parameters in smpp_rules.toml.

What's Next

• System Architecture — what is deployed, what connects to what, and what manages what
• SMS Gateway Proxy Installation — production volume parameters, network configuration, backups
• SMS Gateway Proxy Configuration — detailed configuration of the application, SMPP links, and pools
• REST API — full endpoint reference for authentication, sending, and monitoring
• Message Control Platform Deployment — add contact policies and filtering