REST API

Direct HTTP API integration for any programming language.

Base URL

All API requests should be made to:

https://api.msgine.net/api/v1

Authentication

All API requests must be authenticated using an API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Security Warning

Never expose your API token in client-side code. Always make API requests from your backend server.

Request Format

All requests must:

• Use HTTPS
• Include the Authorization header with your API token
• Send Content-Type: application/json for POST/PUT requests
• Use UTF-8 encoding

Example Request

curl -X POST https://api.msgine.net/api/v1/messages/sms \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+256701234567",
    "message": "Hello from MsGine!"
  }'

Response Format

All API responses are returned as JSON:

{
  "id": "msg_1234567890",
  "status": "pending",
  "to": ["+256701234567"],
  "message": "Hello from MsGine!",
  "cost": 0.05,
  "currency": "USD",
  "createdAt": "2024-01-15T10:30:00Z"
}

Try It Out

Send SMS - Interactive PlaygroundPOST /messages/sms

API Token

Request Body (JSON) { "to": "+256701234567", "message": "Hello from MsGine!" }

No response yet. Make a request to see the response here.

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions
404	Not Found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable

Error Responses

Error responses include a descriptive message:

{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number must be in E.164 format",
    "details": {
      "field": "to",
      "value": "0701234567"
    }
  }
}

Rate Limiting

API requests are rate-limited to protect our infrastructure:

• Default: 100 requests per minute per API token
• Burst: Up to 20 requests per second

When rate limited, you'll receive a 429 status code with this response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later.",
    "retryAfter": 60
  }
}

The Retry-After header indicates when you can retry (in seconds).

TIP

The official SDK handles rate limiting automatically with exponential backoff.

Pagination

List endpoints support pagination using these parameters:

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page (max: 100)

Example:

curl "https://api.msgine.net/api/v1/messages?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 247,
    "pages": 5
  }
}

Idempotency

To prevent duplicate requests, include an Idempotency-Key header:

curl -X POST https://api.msgine.net/api/v1/messages/sms \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-12345" \
  -d '{...}'

INFO

The API stores idempotency keys for 24 hours. Requests with the same key within that period will return the original response without creating a duplicate resource.

Language Examples

cURL

curl -X POST https://api.msgine.net/api/v1/messages/sms \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+256701234567",
    "message": "Hello from MsGine!"
  }'

JavaScript (Fetch)

const response = await fetch('https://api.msgine.net/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+256701234567',
    message: 'Hello from MsGine!'
  })
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    'https://api.msgine.net/api/v1/messages/sms',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'to': '+256701234567',
        'message': 'Hello from MsGine!'
    }
)

print(response.json())

PHP

<?php
$ch = curl_init('https://api.msgine.net/api/v1/messages/sms');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'to' => '+256701234567',
    'message' => 'Hello from MsGine!'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.msgine.net/api/v1/messages/sms')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  to: '+256701234567',
  message: 'Hello from MsGine!'
}.to_json

response = http.request(request)
puts response.body

Webhooks

Configure webhooks to receive real-time updates about message delivery:

{
  "to": "+256701234567",
  "message": "Your code is 123456",
  "callbackUrl": "https://your-app.com/webhooks/msgine"
}

Learn more in the Webhooks Guide.

Next Steps

• SMS API - Send SMS messages
• Authentication - Manage API tokens
• Webhooks - Receive delivery updates
• Rate Limits - Understanding limits