SMS API

Complete reference for the SMS messaging endpoint.

Send SMS

Send SMS messages to one or more recipients.

Endpoint

POST https://api.msgine.net/api/v1/developers/sms

Request

curl -X POST https://api.msgine.net/api/v1/developers/sms \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+256701521269",
    "message": "Hello from MsGine!",
    "from": "MyApp",
    "callbackUrl": "https://your-app.com/webhook"
  }'

Parameters

Parameter	Type	Required	Description
to	string | string[]	Yes	Recipient phone number(s) in E.164 format
message	string	Yes	Message content (max 1000 characters)
from	string	No	Sender ID, max 11 characters (default: account sender ID)
callbackUrl	string	No	Webhook URL for delivery updates

Response

Status Code: 201 Created

{
  "id": "msg_1234567890",
  "sid": "SM1234567890abcdef",
  "channel": "sms",
  "to": ["+256701521269"],
  "from": "MyApp",
  "content": "Hello from MsGine!",
  "status": "pending",
  "cost": 30,
  "currency": "UGX",
  "createdAt": "2024-01-15T10:30:00Z"
}

Send to Multiple Recipients

Send the same message to multiple recipients:

curl -X POST https://api.msgine.net/api/v1/developers/sms \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+256701521269", "+256701234567", "+256709876543"],
    "message": "Batch message to all recipients"
  }'

Response:

{
  "id": "msg_1234567890",
  "sid": "SM1234567890abcdef",
  "channel": "sms",
  "to": ["+256701521269", "+256701234567", "+256709876543"],
  "from": "MsGine",
  "content": "Batch message to all recipients",
  "status": "pending",
  "cost": 90,
  "currency": "UGX",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Message History

Retrieve a paginated list of sent messages.

Endpoint

GET https://api.msgine.net/api/v1/developers/sms/history

Request

curl "https://api.msgine.net/api/v1/developers/sms/history?page=1&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20, max: 100)

Response

Status Code: 200 OK

{
  "data": [
    {
      "id": "msg_1234567890",
      "status": "delivered",
      "to": ["+256701521269"],
      "content": "Hello from MsGine!",
      "cost": 30,
      "currency": "UGX",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 247,
    "pages": 13
  }
}

Message Status

Messages can have the following statuses:

Status	Description
pending	Message is queued for delivery
sent	Message has been sent to the carrier
delivered	Message was successfully delivered
failed	Message delivery failed

Phone Number Format

All phone numbers must be in E.164 format:

+[country code][number]

Examples:

• ✅ +256701521269 (Uganda)
• ✅ +14155552671 (United States)
• ✅ +447911123456 (United Kingdom)
• ❌ 0701521269 (missing country code)
• ❌ 256701521269 (missing + prefix)

Sender ID

The from parameter sets the sender ID displayed to recipients:

Alphanumeric Sender ID

{
  "from": "MyApp",
  "to": "+256701521269",
  "message": "Hello!"
}

Rules:

• Max 11 characters
• Alphanumeric only (A-Z, 0-9)
• No spaces or special characters
• May not be supported in all countries

Message Length

Single SMS

• Standard (GSM-7): 160 characters
• Unicode: 70 characters

Concatenated SMS

Messages longer than a single SMS are split into multiple parts:

• Standard (GSM-7): 153 characters per part
• Unicode: 67 characters per part
• Maximum: 1000 characters

Pricing

SMS pricing in Uganda is 30 UGX per message. Costs are shown in the response:

{
  "cost": 30,
  "currency": "UGX"
}

For messages to multiple recipients, the cost is multiplied by the number of recipients.

Error Responses

400 Bad Request

Invalid request parameters:

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

401 Unauthorized

Invalid or missing API key:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

402 Payment Required

Insufficient account balance:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient account balance",
    "details": {
      "balance": 20,
      "required": 90,
      "currency": "UGX"
    }
  }
}

429 Too Many Requests

Rate limit exceeded:

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

Webhooks

Configure a webhook to receive delivery status updates:

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

When the message status changes, MsGine will POST to your callback URL:

{
  "id": "msg_1234567890",
  "event": "message.delivered",
  "status": "delivered",
  "to": "+256701521269",
  "timestamp": "2024-01-15T10:30:15Z"
}

Learn more in the Webhooks Guide.

Next Steps

• Webhooks - Receive delivery notifications
• Authentication - Manage API keys
• Rate Limits - Understanding limits
• SDK Guide - Use the official SDK