SMS API Integration Guide for Developers

Overview

This guide explains how to integrate with the SMS API using API keys. The API provides endpoints for sending individual and bulk SMS messages, checking message status, and managing SIM numbers.

Table of Contents

  1. Getting Started
  2. Authentication
  3. Endpoints
  4. Request/Response Formats
  5. Error Handling
  6. Rate Limits & Quotas
  7. Code Examples
  8. Webhooks
  9. Best Practices

Getting Started

Prerequisites

  1. Active Company Account: You need a company account registered in the system
  2. API Key: Generate an API key from the Admin Dashboard (Admin > API Keys)
  3. Active Subscription: Your company must have an active subscription with SMS quota

Base URL

Production: https://prosendi.com/api
Development: http://localhost:8000/api

Authentication

API Key Authentication

All API requests require authentication using an API key. The API key must be:

  1. Active - Not deactivated by an administrator
  2. Not Expired - Must have a valid expiration date
  3. Valid - Properly associated with your company account
  4. Service-Specific - Matches the service type you're accessing (sms, email, whatsapp)

API Key Validation

The system automatically validates your API key on every request:

  • Existence Check: API key exists in the system
  • Active Status: active field is true
  • Expiration Check: Current date is before expires_date
  • Company Status: Associated company account is active

If any validation fails, the request is rejected with a 401 Unauthorized response.

Include your API key in one of the following ways:

Option 1: Custom Header (Recommended)

X-API-Key: your_api_key_here

Option 2: Authorization Header

Authorization: Bearer your_api_key_here

Example

curl -X POST https://prosendi.com/api/sms/send \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "+22370123456", "message": "Hello World"}'

Endpoints

1. Send SMS

Send a single SMS message to a recipient.

Endpoint: POST /api/sms/send

Authentication: Required (API Key + Quota Check)

Request Body:

{
    "recipient": "+22370123456",
    "message": "Your message text here (max 1600 characters)",
    "sim_number_id": 1,
    "campaign_id": 5
}

Success Response (200):

{
    "success": true,
    "message": "SMS envoyé avec succès",
    "data": {
        "sms_id": "uuid-here",
        "task_id": "17617592691708",
        "sim_number": "+22366603716",
        "recipient": "+22370123456",
        "status": "sent"
    }
}

Error Responses:

Status Code Error Type Description
400 Bad Request Invalid phone number format or message too long
401 Unauthorized Missing or invalid API key
403 Forbidden Company account is inactive
429 Too Many Requests Quota exceeded
500 Internal Error Server error or SIM unavailable

2. Send Bulk SMS

Send multiple SMS messages in a single request.

Endpoint: POST /api/sms/send-bulk

Authentication: Required (API Key + Quota Check)

Request Body:

{
    "messages": [
        { "recipient": "+22370123456", "message": "Message 1" },
        { "recipient": "+22370987654", "message": "Message 2" }
    ],
    "sim_number_id": 1,
    "campaign_id": 5
}

Constraints:

  • Maximum 100 messages per request
  • All recipients must be valid phone numbers
  • Total character count must not exceed limits

Success Response (200):

{
    "success": true,
    "message": "Envoi terminé: 2 succès, 0 échecs",
    "summary": { "total": 2, "success": 2, "failed": 0 },
    "results": [
        {
            "recipient": "+22370123456",
            "success": true,
            "sms_id": "uuid-1",
            "task_id": "17617592691708",
            "sim_number": "+22366603716"
        },
        {
            "recipient": "+22370987654",
            "success": true,
            "sms_id": "uuid-2",
            "task_id": "17617592691709",
            "sim_number": "+22366603716"
        }
    ]
}

3. Check SMS Status

Retrieve the status of a previously sent SMS.

Endpoint: GET /api/sms/status/{sms_id}

Authentication: Required (API Key only)

Parameters:

  • sms_id (path parameter): UUID of the SMS message

Success Response (200):

{
    "success": true,
    "data": {
        "sms_id": "uuid-here",
        "recipient": "+22370123456",
        "sender": "+22366603716",
        "message": "Your message text",
        "status": "sent",
        "status_label": "Sent",
        "sent_at": "2025-10-30T14:30:00.000000Z",
        "delivered_at": null,
        "failed_at": null,
        "failure_reason": null,
        "cost": 0.05,
        "retry_count": 0,
        "sim_number": "+22366603716"
    }
}

Status Values:

Status Description
pending Message queued for sending
sent Message sent successfully
delivered Message delivered to recipient
failed Message failed to send
cancelled Message was cancelled

4. Get Available SIMs

List all available SIM cards for SMS sending.

Endpoint: GET /api/sms/sims/available

Authentication: Required (API Key only)

Success Response (200):

{
    "success": true,
    "data": {
        "assigned_sim": {
            "id": 1,
            "number": "+22366603716",
            "name": "Orange Mali SIM",
            "operator": "Orange",
            "can_send_sms": true
        },
        "available_sims": [
            {
                "id": 1,
                "number": "+22366603716",
                "name": "Orange Mali SIM",
                "operator": "Orange",
                "port": 8,
                "slot": 2,
                "is_default": true,
                "balance": 0,
                "daily_limit": 100,
                "monthly_limit": 3000,
                "usage_stats": {
                    "today_sent": 45,
                    "today_failed": 2,
                    "this_month_sent": 1250
                },
                "can_send_sms": true,
                "assigned_to": "Orange Mali"
            }
        ],
        "total_available": 1
    }
}

5. Test Connection

Test the 1SIMPLE1 gateway connection (Administration only).

Endpoint: GET /api/sms/test-connection

Authentication: Required (API Key only)

Success Response (200):

{
    "success": true,
    "message": "Connexion 1SIMPLE1 réussie",
    "data": { "result": "success" },
    "status_code": 200
}

Request/Response Formats

Phone Number Format

^(\+223)?[67][0-9]{7}$

Valid Examples:

  • +22370123456
  • 22370987654
  • 70123456
  • 70987654

Invalid Examples:

  • 223701234567
  • 26312345678
  • 22350123456

Message Format

  • Character Limit: 1600 characters
  • Encoding: UTF-8
  • Supported Characters: All standard text characters, emojis supported

JSON Headers

Always include:

Content-Type: application/json
Accept: application/json

Error Handling

Standard Error Response

{
    "success": false,
    "message": "Human-readable error message",
    "error": "error_code",
    "data": {}
}

Common Error Codes

Error Code HTTP Status Description
missing_api_key 401 API key not provided
invalid_api_key 401 API key is invalid
inactive_api_key 401 API key is expired or deactivated
inactive_company 403 Company account is inactive
service_type_mismatch 403 API key is not valid for this service type
quota_exceeded 429 SMS quota exceeded
invalid_request 400 Request validation failed
sim_unavailable 400 No available SIM for sending
company_not_found 500 Company not found for this API key

Inactive API Key Response

{
    "success": false,
    "message": "API key has expired",
    "error": "inactive_api_key",
    "data": {
        "expired": true,
        "deactivated": false,
        "expires_date": "2025-01-15T00:00:00.000000Z",
        "active": true
    }
}

Service Type Mismatch Response

{
    "success": false,
    "message": "API key is not valid for this service type",
    "error": "service_type_mismatch",
    "data": { "api_key_service": "email", "requested_service": "sms" }
}

Quota Exceeded Response

{
    "success": false,
    "message": "Quota exceeded",
    "error": "quota_exceeded",
    "data": {
        "service_type": "sms",
        "requested": 10,
        "remaining": 0,
        "total_quota": 1000,
        "usage_percentage": 100.0
    }
}

Rate Limits & Quotas

Quota Management

  • Quota Checking: Automatic for all send operations
  • Per-Request Check: System verifies available quota before processing
  • Bulk Requests: Total messages count against quota

Quota Information

Check your quota status:

  1. Dashboard: Admin Dashboard > SMS Quota
  2. API Response: Included in quota exceeded errors

Example Quota Breakdown

Total Quota: 1,000 SMS/month
Sent This Month: 750
Remaining: 250
Usage: 75%

Code Examples

JavaScript/Node.js

const axios = require("axios");

const API_KEY = "your_api_key_here";
const BASE_URL = "https://prosendi.com/api";

async function sendSMS(recipient, message) {
    const response = await axios.post(
        `${BASE_URL}/sms/send`,
        { recipient, message },
        {
            headers: {
                "X-API-Key": API_KEY,
                "Content-Type": "application/json",
            },
        }
    );
    return response.data;
}

Python

import requests

API_KEY = 'your_api_key_here'
BASE_URL = 'https://prosendi.com/api'

def send_sms(recipient, message):
    url = f'{BASE_URL}/sms/send'
    headers = {'X-API-Key': API_KEY, 'Content-Type': 'application/json'}
    data = {'recipient': recipient, 'message': message}
    return requests.post(url, json=data, headers=headers).json()

PHP

<?php
$apiKey = 'your_api_key_here';
$baseUrl = 'https://prosendi.com/api';
$ch = curl_init($baseUrl . '/sms/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey,'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['recipient' => '+22370123456','message' => 'Hello from PHP!']));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

cURL

API_KEY="your_api_key_here"
BASE_URL="https://prosendi.com/api"
curl -X POST "$BASE_URL/sms/send" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{"recipient": "+22370123456", "message": "Hello from bash!"}'

Webhooks

Note: Webhooks are not yet implemented but planned for future releases.

Best Practices

1. API Key Security

  • Never commit API keys
  • Store keys in environment variables
  • Rotate keys regularly
  • Revoke keys if compromised

2. Error Handling

Implement robust error handling.

3. Rate Limiting

  • Bulk limit: 100 messages
  • Throttle bulk requests
  • Exponential backoff on errors

4. Phone Number Validation

Validate using regex before sending.

5. Message Optimization

  • Keep messages concise
  • Use short URLs
  • Avoid costly characters

6. Monitoring

  • Track sent/failed counts
  • Monitor quota usage and alerts
  • Log API requests

Support

Documentation

  • API Reference: /api/documentation (coming soon)

Contact

Status

Changelog

Version 1.0.0 (October 2025)

  • Initial API release
  • SMS send functionality
  • Bulk SMS support
  • Status checking
  • SIM management

License

© 2025 Your Company. All rights reserved.