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/messages/sms

Request

bash

curl -X POST https://api.msgine.net/api/v1/messages/sms \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -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 1600 characters)
`from`	`string`	No	Sender ID (default: account sender ID)
`callbackUrl`	`string`	No	Webhook URL for delivery updates

Response

Status Code: 201 Created

json

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

Send to Multiple Recipients

Send the same message to multiple recipients:

bash

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

Response:

json

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

Get Message Status

Retrieve the delivery status of a sent message.

Endpoint

GET https://api.msgine.net/api/v1/messages/{messageId}

Request

bash

curl https://api.msgine.net/api/v1/messages/msg_1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Status Code: 200 OK

json

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

List Messages

Retrieve a paginated list of sent messages.

Endpoint

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

Request

bash

curl "https://api.msgine.net/api/v1/messages?page=1&limit=20&status=delivered" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

Parameter	Type	Required	Description
`page`	`number`	No	Page number (default: 1)
`limit`	`number`	No	Items per page (default: 20, max: 100)
`status`	`string`	No	Filter by status (pending, sent, delivered, failed)

Response

Status Code: 200 OK

json

{
  "data": [
    {
      "id": "msg_1234567890",
      "status": "delivered",
      "to": ["+256701521269"],
      "message": "Hello from MsGine!",
      "cost": 0.05,
      "currency": "USD",
      "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

json

{
  "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

Phone Number Sender ID

json

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

Rules:

Must be a valid phone number in E.164 format
Must be registered with your account
Supports two-way messaging

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: 1600 characters (10 parts)

Example:

json

{
  "message": "This is a very long message that exceeds 160 characters and will be split into multiple parts. Each part will be charged separately, but delivered as a single message to the recipient."
}

This 180-character message will be sent as 2 SMS parts and charged accordingly.

Pricing

SMS pricing varies by destination country. Use the pricing endpoint to check costs:

bash

curl "https://api.msgine.net/api/v1/pricing/sms?country=UG" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

json

{
  "country": "Uganda",
  "countryCode": "UG",
  "price": 0.05,
  "currency": "USD",
  "perMessage": true
}

Error Responses

400 Bad Request

Invalid request parameters:

json

{
  "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 token:

json

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

402 Payment Required

Insufficient account balance:

json

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient account balance",
    "details": {
      "balance": 0.50,
      "required": 1.25,
      "currency": "USD"
    }
  }
}

429 Too Many Requests

Rate limit exceeded:

json

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

Webhooks

Configure a webhook to receive delivery status updates:

json

{
  "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:

json

{
  "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 tokens
Rate Limits - Understanding limits
SDK Guide - Use the official SDK

SMS API ​

Send SMS ​

Endpoint ​

Request ​

Parameters ​

Response ​

Send to Multiple Recipients ​

Get Message Status ​

Endpoint ​

Request ​

Response ​

List Messages ​

Endpoint ​

Request ​

Query Parameters ​

Response ​

Message Status ​

Phone Number Format ​

Sender ID ​

Alphanumeric Sender ID ​

Phone Number Sender ID ​

Message Length ​

Single SMS ​

Concatenated SMS ​

Pricing ​

Error Responses ​

400 Bad Request ​

401 Unauthorized ​

402 Payment Required ​

429 Too Many Requests ​

Webhooks ​

Next Steps ​

SMS API

Send SMS

Endpoint

Request

Parameters

Response

Send to Multiple Recipients

Get Message Status

Endpoint

Request

Response

List Messages

Endpoint

Request

Query Parameters

Response

Message Status

Phone Number Format

Sender ID

Alphanumeric Sender ID

Phone Number Sender ID

Message Length

Single SMS

Concatenated SMS

Pricing

Error Responses

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

Webhooks

Next Steps