Overview

MSG SMS API for Algeria

MSG provides a simple HTTPS API to send and receive SMS in Algeria using local +213 numbers. You can integrate it with your website, backend, mobile apps, or internal tools in just a few minutes.

• Send one‑time passwords (OTP) and 2FA codes
• Notify users about orders, deliveries, and account activity
• Run bulk or campaign SMS to Algerian customers

Quickstart

The fastest way to send your first SMS in Algeria with MSG.

1. Get your API key
Sign in to the MSG dashboard, go to API keys, and create a new key. Keep it secret – it grants access to your account.

2. Call the SMS endpoint

Use any HTTP client to send a POST request to the /v1/messages endpoint.

curl https://api.msg.io/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+213555000000",
    "from": "MSGDemo",
    "text": "Your verification code is 482913",
    "webhook_url": "https://yourapp.com/webhooks/msg"
  }'

3. Handle delivery reports (optional)
Configure a webhook_url to receive delivery status for each message. See Webhooks for payload examples.

Authentication

MSG uses API keys with Bearer tokens for authentication.

• Create and manage keys from the MSG dashboard.
• Send the key in the HTTP Authorization header.
• Never expose keys in public code or client‑side apps.

Authorization: Bearer YOUR_API_KEY

Base URL & regions

All requests are made over HTTPS to the MSG API.

Base URL: https://api.msg.io/v1

MSG currently focuses on Algeria (+213). All SMS traffic is routed through Algerian operators. Global messaging is not yet available.

Send SMS

Use the POST /v1/messages endpoint to send SMS.

Request body (JSON)

to – recipient phone number in E.164 format (+213...), required.
from – sender ID or MSG number, required.
text – message body (up to 160 GSM chars per segment), required.
webhook_url – optional URL for delivery webhooks.
metadata – optional object echoed in webhooks.

Example

POST /v1/messages
{
  "to": "+213555000000",
  "from": "MSGDemo",
  "text": "Your verification code is 482913",
  "metadata": { "user_id": "user_123" },
  "webhook_url": "https://yourapp.com/webhooks/msg"
}

On success, MSG returns 202 Accepted with a JSON body containing the message ID and initial status.

Webhooks

Webhooks allow MSG to notify your system about message events in real‑time.

Delivery receipts (DLR)

When you set webhook_url in your send request, MSG will POST delivery updates to that URL.

POST https://yourapp.com/webhooks/msg
{
  "event": "message.status",
  "id": "msg_123456",
  "to": "+213555000000",
  "status": "delivered", // queued | sent | delivered | failed
  "error_code": null,
  "timestamp": "2025-01-15T10:23:45Z",
  "metadata": { "user_id": "user_123" }
}

Inbound SMS

For enabled numbers, inbound SMS can be forwarded to your webhook URL as well.

{
  "event": "message.inbound",
  "id": "msg_in_98765",
  "from": "+213555111111",
  "to": "+213555000000",
  "text": "STOP",
  "timestamp": "2025-01-15T10:25:10Z"
}

Your webhook endpoint should return 2xx quickly. MSG may retry deliveries on transient failures.

Errors & status codes

MSG uses standard HTTP status codes plus a structured error body.

Common responses

202 Accepted – message accepted for delivery.
400 Bad Request – invalid parameters (e.g. missing to or text).
401 Unauthorized – invalid or missing API key.
403 Forbidden – key doesn't have permission.
429 Too Many Requests – rate limit exceeded.
5xx Server Error – unexpected error on MSG side.

Error body

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'to' field is required.",
    "field": "to",
    "request_id": "req_abc123"
  }
}

Use request_id when contacting support about a specific failure.

Best practices

Recommendations for reliable, user‑friendly SMS integrations in Algeria.

• Store message_id from the API response so you can match webhooks to your internal records.
• Use metadata to attach non‑sensitive context (user ID, order ID) instead of encoding it in the SMS text.
• Implement retry logic on your webhook endpoints for transient network issues.
• For OTPs, set reasonable expiry and limit the number of SMS per user over a given time window.
• Respect user preferences and local regulations for marketing SMS (opt‑in/opt‑out).