TeraMouv SMS Gateway
API Reference

Overview

The TeraMouv API Gateway is a thin, stable REST layer that lets your application send A2P SMS messages and receive P2A replies without ever touching the underlying messaging infrastructure directly.

Protocol basics

Quick Start

Three calls to go from zero to a delivered SMS. Complete the steps below to send your first message.

1. Obtain an API key

   Call POST /auth/login with your credentials. Save the returned api_key — you'll send it as the X-API-Key header on every subsequent request.

   cURLCopy

   curl -X POST https://api.sms.teramouv.com/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username":"your_username","password":"your_password"}'

   ⚠️

   Production systems: do not call /auth/login from every process. Ask your TeraMouv administrator for a permanently provisioned API key instead. See API Key Types below.

2. Send an SMS

   Use the key from Step 1 in the X-API-Key header. A 200 response means the message was accepted — not yet delivered. Save the message_id for status polling.

   cURLCopy

   curl -X POST https://api.sms.teramouv.com/api/v1/sms/send \
     -H "Content-Type: application/json" \
     -H "X-API-Key: sk_live_..." \
     -d '{"to":"25700000000","message":"Hello from TeraMouv","from":"TeraMouv"}'

3. Poll for delivery status

   Use the message_id from Step 2 to check whether the message reached the handset. The status moves from submitted → pending → sent → delivered (or failed).

   cURLCopy

   curl https://api.sms.teramouv.com/api/v1/sms/status/msg_901991 \
     -H "X-API-Key: sk_live_..."

API Key Types

There are two ways to obtain an API key. Understanding the difference is critical for production deployments.

IP Whitelisting

A key can optionally be restricted to a list of source IP addresses. Requests from an unlisted IP are rejected with 403 IP_NOT_ALLOWED regardless of how valid the key is. Contact your administrator to view or update your key's IP whitelist.

Authentication

All protected endpoints require the X-API-Key header. The key is checked before any business logic runs — an invalid or missing key always returns 401 immediately.

curl -X POST https://api.sms.teramouv.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your_username","password":"your_password"}'

const res = await fetch('https://api.sms.teramouv.com/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'your_username',
    password: 'your_password'
  })
});
const { api_key, user } = await res.json();
// Store api_key securely — use it in X-API-Key on subsequent requests

$ch = curl_init('https://api.sms.teramouv.com/api/v1/auth/login');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'username' => 'your_username',
        'password' => 'your_password'
    ]),
]);
$data = json_decode(curl_exec($ch), true);
$apiKey = $data['api_key'];

import requests

resp = requests.post(
    'https://api.sms.teramouv.com/api/v1/auth/login',
    json={'username': 'your_username', 'password': 'your_password'}
)
api_key = resp.json()['api_key']

{
  "success": true,
  "api_key": "sk_live_abc123...",
  "user": {
    "id": 2,
    "username": "your_username",
    "email": "you@example.com"
  }
}

{ "success": true, "message": "Logged out successfully." }

SMS

Send outbound A2P messages, check delivery receipts, and retrieve inbound P2A messages.

curl -X POST https://api.sms.teramouv.com/api/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{
    "to": "25700000000",
    "message": "Your OTP code is 482910. Valid for 5 minutes.",
    "from": "TeraMouv"
  }'

curl -X POST https://api.sms.teramouv.com/api/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{
    "to": "25700000000",
    "message": "Your appointment is tomorrow at 09:00.",
    "from": "TeraMouv",
    "schedule": "2026-06-20T08:00:00"
  }'

async function sendSMS(to, message, from) {
  const res = await fetch('https://api.sms.teramouv.com/api/v1/sms/send', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.TERAMOUV_API_KEY
    },
    body: JSON.stringify({ to, message, from })
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`SMS failed: ${err.error} — ${err.message}`);
  }

  return await res.json(); // { success, message_id, status, ... }
}

function sendSMS(string $to, string $message, string $from): array {
    $ch = curl_init('https://api.sms.teramouv.com/api/v1/sms/send');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-API-Key: ' . getenv('TERAMOUV_API_KEY')
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'to'      => $to,
            'message' => $message,
            'from'    => $from,
        ]),
    ]);
    $data = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $data;
}

import os, requests

def send_sms(to: str, message: str, sender_id: str = None) -> dict:
    payload = {"to": to, "message": message}
    if sender_id:
        payload["from"] = sender_id

    resp = requests.post(
        "https://api.sms.teramouv.com/api/v1/sms/send",
        json=payload,
        headers={"X-API-Key": os.environ["TERAMOUV_API_KEY"]},
        timeout=10
    )
    resp.raise_for_status()
    return resp.json()  # { "success": True, "message_id": "msg_...", ... }

{
  "success": true,
  "message_id": "msg_901991",      // save this — use it to poll /sms/status
  "status": "submitted",
  "destination": "25700000000",
  "credits_deducted": 1,             // always 1 per accepted message
  "timestamp": "2026-06-03T16:49:42+02:00"
}

{
  "message_id": "msg_901991",
  "status": "delivered",
  "destination": "25700000000",
  "submitted_at": "2026-06-03 16:49:42",  // YYYY-MM-DD HH:MM:SS, no timezone
  "updated_at": "2026-06-03 16:49:47",     // null if no live DLR check succeeded
  "error_code": "0"
}

{
  "success": true,
  "total": 5,              // count of rows in THIS page, not all-time total
  "limit": 10,
  "offset": 0,
  "messages": [
    {
      "id": "1",
      "from": "25700000000",
      "message": "STOP",
      "received_at": "2026-06-03T09:55:00+02:00"
    }
  ]
}

Account

Check your credit balance and retrieve your full account profile from the gateway.

{
  "success": true,
  "balance": 4989564,
  "currency": "SMS",  // always the literal string "SMS", not a monetary currency
  "timestamp": "2026-06-03T16:49:42+02:00"
}

{
  "success": true,
  "data": {
    "username": "your_username",
    "name": "Your Company",
    "email": "you@example.com",
    "mobile": "",
    "balance": 4989564,
    "last_outgoing_id": "901991",  // highest sent message ID on record
    "last_incoming_id": "0",       // highest received message ID
    "last_inbox_id": "0"           // highest two-way inbox message ID
  },
  "timestamp": "2026-06-03T16:49:42+02:00"
}

{
  "status": "ok",
  "service": "TeraMouv API Gateway",
  "timestamp": "2026-06-03T16:49:42+02:00"
}

Request Validation

Every POST / PUT / PATCH request is validated before your API key is even checked. A bad request always returns 400, never 401.

{
  "success": false,
  "error": "VALIDATION_FAILED",
  "errors": {
    "to": ["The to format is invalid."],
    "message": ["The message field is required."]
  }
}

Rate Limiting

Each API key has its own rate limit window. The default is 1,000 requests per 60-second window, configurable per key by an administrator.

Every protected endpoint response includes these headers so you can track consumption in real time:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995

When the limit is exceeded, the gateway responds with:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit of 1000 requests per minute exceeded."
}

Retries & Idempotency

/sms/send is not idempotent. If you retry a send that timed out or returned 500, you may end up delivering the same message twice.

Recovery procedure

1. You received a message_id before the failure

   Call GET /sms/status/{message_id} first. If the status is submitted or higher, the message is already in the queue — do not resend.

2. You never received a message_id

   The request failed before a response was returned. There is currently no lookup mechanism for this case. Wait briefly and check your own application logs. If duplicate sends are a serious concern for your use case, contact TeraMouv support.

Safe to retry freely

All GET requests and /auth/logout are idempotent and can be retried without any risk of side effects.

Error Handling

All error responses share a consistent shape. The error field is the machine-readable code; message is a human-readable description.

Standard error shape

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description of what went wrong."
}

Validation error shape (extra errors object)

{
  "success": false,
  "error": "VALIDATION_FAILED",
  "errors": {
    "to": ["The to format is invalid."],
    "message": ["The message field is required."]
  }
}

Complete error code reference

Limits & Constraints

Hard boundaries enforced by this API version. These are not configurable per key.

Security Headers

Every response — including errors — carries these hardening headers. They don't affect server-to-server clients but are worth knowing when debugging via a browser or proxy.

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: default-src 'none'