Developer Docs

API Documentation

Complete guide to integrate SkySMS into your application

Navigation

Getting Started: Create a free account to get your API key. You'll receive 10 free SMS credits.

Create Free Account →

Video Tutorials

Authentication

All API requests require authentication using an API key passed in the request header:

X-API-Key: your_api_key_here

Generate API keys from your dashboard after logging in.

Send SMS

POST /api/v1/sms/send

Parameters

Parameter Type Required Description
phone_number string Yes Recipient phone number (e.g., +639123456789)
message string Yes SMS content (max 160 characters)
use_subscription boolean No Use subscription instead of credits (default: false)
Payment Method: Pass use_subscription: true to charge from your subscription daily limit instead of credits. You can also set this per API key from your dashboard — no parameter needed when the toggle is on.

Example Request

curl -X POST https://www.skysms.skyio.site/api/v1/sms/send \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+639123456789",
    "message": "Hello from SkySMS!"
  }'

Response

{ "success": true, "message": "SMS queued successfully", "data": { "id": 123, "status": "pending" } }

OTP Service

Use {{otp}} placeholder in your message. The system auto-generates a 6-digit code.

Send OTP

POST /api/v1/otp/send 
curl -X POST https://www.skysms.skyio.site/api/v1/otp/send \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+639123456789",
    "message": "Your code is {{otp}}",
    "expire": 300
  }'

Verify OTP

GET /api/v1/otp/verify?otp=123456&phone=+639123456789

Bulk SMS

Send SMS to multiple recipients at once. Efficient for marketing campaigns and mass notifications.
POST /api/v1/sms/send-bulk

Parameters

Parameter Type Required Description
recipients array Yes Array of objects with phone_number key
message string Yes Message content for all recipients
use_subscription boolean No Use subscription instead of credits (default: false)
Payment Method: Pass use_subscription: true to charge from your subscription daily limit instead of credits. You can also set this per API key from your dashboard — no parameter needed when the toggle is on.

Example Request

curl -X POST https://www.skysms.skyio.site/api/v1/sms/send-bulk \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [{"phone_number": "+639123456789"}, {"phone_number": "+639987654321"}],
    "message": "Hello everyone!"
  }'

Get Messages

Fetch your sent messages with optional filters. Use this to sync message status with your system.

GET /api/v1/sms/messages

Query Parameters

Parameter Type Description
status string Filter: pending, sent, failed, queued
from date Start date (YYYY-MM-DD)
to date End date (YYYY-MM-DD)
per_page integer Results per page (max 100) 
curl -X GET "https://www.skysms.skyio.site/api/v1/sms/messages?status=failed" \
  -H "X-API-Key: your_api_key"

Get Failed Messages Only

GET /api/v1/sms/messages/failed

Resend Failed Messages

Resending costs 1 credit per message. Only failed messages can be resent.

Resend by Unique Message ID (Recommended)

POST /api/v1/sms/messages/resend 
curl -X POST "https://www.skysms.skyio.site/api/v1/sms/messages/resend" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"unique_message_id": "msg_4a8b2c9d1e3f5a6b"}'

Resend by Queue ID

POST /api/v1/sms/messages/{'{id}'}/resend

Bulk Resend

POST /api/v1/sms/messages/bulk-resend 
curl -X POST "https://www.skysms.skyio.site/api/v1/sms/messages/bulk-resend" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"ids": [123, 456, 789]}'

Message Content Policy

Violations result in credit penalties. Messages that violate our policy appear as "sent" but are NOT delivered to the recipient.

Rules are automatically enforced on /sms/send and /sms/send-bulk.

Prohibited Content

Violation Penalty Description
URL / Links 10 credits/msg Any URLs, domains, IPs, shortened links (http, www, bit.ly, etc.)
Profanity 50 credits/msg Filipino (Tagalog, Bisaya) or English profanity, insults, bullying
Bulk SMS: Penalty is charged per recipient. URL to 10 recipients = 100 credits penalty. Profanity to 5 recipients = 250 credits penalty.

Example Violation Response

{"success":true,"status":"sent","warning":"Message contained a URL. A 10-credit penalty has been applied and the message was not delivered.","penalty_credits":10,"credits_remaining":90}

Rate Limits

API requests are limited to 60 requests per minute per API key.
Type Requests Period Scope
Standard60per minutePer API Key
Burst10per secondPer API Key

Best Practices

  • Add delays: Implement 1-2 second delays between API calls.
  • Handle 429: When you receive 429 Too Many Requests, check the Retry-After header.
  • Exponential backoff: On repeated failures, increase wait time (2s → 4s → 8s → 16s).
  • Avoid rapid loops: Tight loops without delays will trigger burst protection and may result in IP blocking.

Error Codes

Code Message Description
400 Bad Request Invalid parameters
401 Unauthorized Invalid API key
402 Payment Required Insufficient credits
403 Forbidden Access denied
422 Validation Error Missing/invalid parameters
429 Too Many Requests Rate limit exceeded (60/min)
500 Server Error Internal error

Ready to start?

Create your free account and get 10 SMS credits to test.

Get Free API Key