SecureSMS Main - Complete integration guide with code examples for all major programming languages
Welcome to the SecureSMS Main SMS Gateway API documentation. This guide will help you integrate our SMS services into your application.
https://whitelabled.securesmsc.com/api/v2
https://whitelabled.securesmsc.com/api/v2/sms/send
https://whitelabled.securesmsc.com/api/secure_api
https://whitelabled.securesmsc.com/api/secure_api/httpapi/send
https://whitelabled.securesmsc.com/httpapi
https://whitelabled.securesmsc.com/httpapi/send (same paths as the original platform)
Base URLs return a JSON discovery document. Append the endpoint path for actual API calls.
API requests are rate limited per API key (Advanced API v2). Typical defaults are about 60 requests per minute; exact limits depend on your key configuration. Legacy HTTP endpoints use a separate throttle.
Create an API key from your panel (API Management). Auth differs by API family:
/api/v2)Use any one of:
Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY
# or query / JSON body:
api_key=YOUR_API_KEY
Use username + password, or api_key / apikey (query or form). Do not send Bearer for these endpoints.
# Example
https://whitelabled.securesmsc.com/httpapi/send?username=USER&password=PASS&sender_id=SMSCIN&route=T&phonenumber=9876543210&message=Hello
# or
https://whitelabled.securesmsc.com/api/secure_api/httpapi/send?api_key=YOUR_API_KEY&sender_id=SMSCIN&route=T&phonenumber=9876543210&message=Hello
Send a single SMS message using the Advanced API v2. recipient must be a 10-digit Indian mobile number.
{
"sender_id": "SENDER",
"recipient": "9876543210",
"message": "Your message here",
"route": "transactional",
"dlt_entity_id": "1234567890123",
"dlt_template_id": "1234567890123456789",
"schedule_at": "2026-07-21 18:30:00",
"unicode": false,
"flash": false
}
Optional: route (transactional|promotional), dlt_entity_id, dlt_template_id, schedule_at, unicode, flash.
{
"success": true,
"message": "SMS queued successfully",
"data": {
"message_id": "67890",
"queue_id": "67890",
"status": "queued",
"estimated_delivery": "2026-07-21T12:30:00Z"
}
}
message_id and queue_id are the same queue identifier.
Send SMS messages to multiple recipients in a single API call.
{
"sender_id": "SENDER",
"recipients": ["1234567890", "0987654321", "1122334455"],
"message": "Bulk message to all recipients",
"route": "promotional"
}
Core Advanced API v2 helpers. All require API key authentication.
Schedule a single SMS. Same fields as /sms/send, but scheduled_at is required (future datetime).
{
"sender_id": "SENDER",
"recipient": "9876543210",
"message": "Scheduled reminder",
"route": "transactional",
"scheduled_at": "2026-07-22 09:00:00"
}
Lookup delivery status by queue id, broadcast id, or vendor message id.
{
"success": true,
"data": {
"balance": 1250,
"currency": "credits",
"last_updated": "2026-07-21T04:00:00Z"
}
}
GET variant of send (query params). Enabled only when GET API access is turned on for the account.
Send WhatsApp messages programmatically using the same secured API keys as the SMS API.
Authenticate with your key from API Management
via the Authorization: Bearer YOUR_API_KEY header (or an api_key parameter).
Each message uses 1 WhatsApp credit.
Open the full WhatsApp v2 reference →
message text and media can only be
delivered when the recipient has messaged you within the last 24 hours. To start a conversation,
send an approved template instead. List your approved templates with the endpoint below.
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient number with country code, e.g. 919876543210 |
message | string | Yes* | Free-form text (max 4096 chars). Requires an open 24h session. *Either message or template. |
template | string | Yes* | Approved template name, e.g. smsc_biz_otp_v1. Works for any recipient. |
params | array | No | Values for the template variables {{1}}, {{2}}… in order. |
language | string | No | Template language code (defaults to the template's language). |
media_url | string | No | Public https:// URL of an image, video, document or audio file (open session only). |
media_type | string | No | image, video, document or audio. |
caption | string | No | Caption sent with the media. |
curl -X POST "https://whitelabled.securesmsc.com/api/v2/whatsapp/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "919876543210",
"template": "smsc_biz_otp_v1",
"params": ["482913"]
}'
curl -X POST "https://whitelabled.securesmsc.com/api/v2/whatsapp/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "919876543210",
"message": "Thanks for reaching out! Your request is being processed."
}'
{
"status": "success",
"data": {
"message_id": "wamid.HBgMOTE5...",
"id": 51,
"to": "919876543210"
}
}
Lists your approved templates with name, category, language, body and the number of {{n}} parameters each expects.
curl "https://whitelabled.securesmsc.com/api/v2/whatsapp/templates" -H "Authorization: Bearer YOUR_API_KEY"
Delivery status of a sent message — pass the numeric id or the wamid returned by the send call. Statuses: sent → delivered → read, or failed with an error.
curl "https://whitelabled.securesmsc.com/api/v2/whatsapp/status/51" -H "Authorization: Bearer YOUR_API_KEY"
| HTTP | Meaning | Fix |
|---|---|---|
| 401 | Missing or invalid API key | Create a key under API Management and send it as Authorization: Bearer … |
| 402 | Insufficient WhatsApp credits | Top up WhatsApp credits from your account manager. |
| 403 | WhatsApp module disabled | Ask your account manager to enable WhatsApp for the account. |
| 404 | Template not found or not approved | Check GET /whatsapp/templates for the exact approved name. |
| 409 | No WhatsApp Business account connected | Complete WhatsApp onboarding in the dashboard first. |
| 422 | template_required / window closed | Send an approved template instead of message. |
| 422 | template_not_sendable | Template cannot be sent from the current sender — pick another approved template. |
| 422 | invalid_recipient | Use a valid number with country code (digits only). |
| 502 | Upstream provider error | Retry; check Meta / Cloud API status if it persists. |
Try these endpoints live in the API Playground.
Ready-to-use code examples for sending SMS in different programming languages:
import requests
import json
url = "https://whitelabled.securesmsc.com/api/v2/sms/send"
api_key = "{{ YOUR_API_KEY }}"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"sender_id": "SENDER",
"recipient": "1234567890",
"message": "Your message here",
"route": "transactional"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))
const url = "https://whitelabled.securesmsc.com/api/v2/sms/send";
const apiKey = "{{ YOUR_API_KEY }}";
const data = {
sender_id: "SENDER",
recipient: "1234567890",
message: "Your message here",
route: "transactional"
};
fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));
const axios = require('axios');
const url = "https://whitelabled.securesmsc.com/api/v2/sms/send";
const apiKey = "{{ YOUR_API_KEY }}";
const data = {
sender_id: "SENDER",
recipient: "1234567890",
message: "Your message here",
route: "transactional"
};
axios.post(url, data, {
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
})
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error('Error:', error.response.data);
});
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.charset.StandardCharsets;
public class SendSMS {
public static void main(String[] args) throws Exception {
String url = "https://whitelabled.securesmsc.com/api/v2/sms/send";
String apiKey = "{{ YOUR_API_KEY }}";
String jsonData = "{\"sender_id\":\"SENDER\",\"recipient\":\"1234567890\",\"message\":\"Your message here\",\"route\":\"transactional\"}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Authorization", "Bearer " + apiKey)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonData))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
class Program {
static async Task Main(string[] args) {
string url = "https://whitelabled.securesmsc.com/api/v2/sms/send";
string apiKey = "{{ YOUR_API_KEY }}";
var data = new {
sender_id = "SENDER",
recipient = "1234567890",
message = "Your message here",
route = "transactional"
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
var json = JsonConvert.SerializeObject(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'json'
require 'uri'
url = URI("https://whitelabled.securesmsc.com/api/v2/sms/send")
api_key = "{{ YOUR_API_KEY }}"
data = {
sender_id: "SENDER",
recipient: "1234567890",
message: "Your message here",
route: "transactional"
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['Authorization'] = "Bearer #{api_key}"
request['Content-Type'] = 'application/json'
request.body = data.to_json
response = http.request(request)
puts JSON.parse(response.body)
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
url := "https://whitelabled.securesmsc.com/api/v2/sms/send"
apiKey := "{{ YOUR_API_KEY }}"
data := map[string]interface{}{
"sender_id": "SENDER",
"recipient": "1234567890",
"message": "Your message here",
"route": "transactional",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer " + apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
}
curl -X POST "https://whitelabled.securesmsc.com/api/v2/sms/send" \
-H "Authorization: Bearer {{ YOUR_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{
"sender_id": "SENDER",
"recipient": "1234567890",
"message": "Your message here",
"route": "transactional"
}'
Click on any language below to view comprehensive integration guides with advanced examples:
TypeScript examples with type definitions and modern async patterns.
View TypeScript GuidePowerShell examples using Invoke-RestMethod for Windows automation.
View PowerShell GuideObjective-C examples using NSURLSession for legacy iOS/macOS apps.
View Objective-C GuideClick on any application or plugin below to view comprehensive integration guides with step-by-step instructions:
Microsoft Power Automate integration for business process automation.
View Power Automate GuideAdditional API v2 endpoints for template management, contact groups, bulk jobs, and real-time account status.
List all templates for the authenticated user.
per_page | Items per page (default: 25, max: 100) |
status | Filter by status (pending, approved, rejected) |
Get a specific template by ID.
Create a new template (draft — requires admin approval).
{
"name": "Welcome Template",
"content": "Hello {#var#}, welcome to our service!",
"dlt_template_id": "1234567890123456789",
"entity_id": "1234567890123"
}
List all contact groups for the authenticated user.
Create a new contact group.
{
"name": "VIP Customers",
"description": "Premium tier customers"
}
Delete a contact group.
List contacts in a specific group. Supports pagination.
per_page | Items per page (default: 50, max: 200) |
List all bulk SMS jobs for the authenticated user.
Get detailed job status with delivery summary.
{
"status": "success",
"data": {
"job": { "id": 1, "status": "completed", "batch_id": "..." },
"delivery_summary": {
"total": 1000,
"delivered": 950,
"failed": 30,
"pending": 20
}
}
}
Get real-time account status including today's stats, credit balance, and pending items.
{
"status": "success",
"data": {
"credit_balance": 5000,
"today": {
"total_sent": 250,
"delivered": 230,
"failed": 10,
"credits_used": 250.0
},
"pending": {
"templates": 2,
"sender_ids": 1
},
"account_status": "active",
"server_time": "2026-03-07T16:00:00+00:00"
}
}
Get delivery report for a specific message.
{
"status": "success",
"data": {
"message_id": "abc123",
"mobile": "1234567890",
"status": "delivered",
"delivery_time": "2026-03-07T16:01:30Z",
"sent_time": "2026-03-07T16:00:00Z",
"sender_id": "SENDER",
"credit": 1.0,
"route": "transactional"
}
}
List all keywords for the authenticated user.
Get a specific keyword with its received entries.
Create a new keyword (pending approval).
{
"key": "INFO",
"response_type": "static",
"static_message": "Thanks for your inquiry!"
}
Get detailed credit balance, usage, and flood status.
{
"status": "success",
"data": {
"balance": 5000,
"international_credit": 200,
"today_used": 150.0,
"month_used": 3200.0,
"flood_current": 50,
"flood_limit": 10000,
"recent_credits": [...]
}
}
Get daily credit usage history.
days | Number of days (default: 30, max: 90) |
Transfer credits to another user.
{
"recipient_username": "john_doe",
"amount": 500,
"description": "Monthly allocation"
}
List all sender ID requests for the authenticated user.
These endpoints use the same URL format as the original platform. You can switch your API base URL from dev.smsc.biz to whitelabled.securesmsc.com without any other code changes.
username + password query parameters, or an api_key / apikey parameter.
https://whitelabled.securesmsc.com/httpapi/sendhttps://whitelabled.securesmsc.com/api/secure_api/httpapi/send| Parameter | Required | Description |
|---|---|---|
username | Yes* | Account username |
password | Yes* | Account password |
api_key | Yes* | API key (alternative to username/password) |
sender_id | Yes | Approved sender ID (e.g. SMSCIN) or PROMOTIONAL |
route | Yes | T (Transactional), P (Promotional), PS (Promo with SID), I (International), V (Voice) |
phonenumber | Yes | 10-digit mobile number (India). Comma-separated for multiple. |
message | Yes | URL-encoded message text (approved template for transactional) |
type | No | 2 for Unicode (message must be UTF-16BE hex) |
text | No | Alternative to message — hybrid mode, supports URL-encoded Unicode |
schedule | No | Schedule time in YYYY-MM-DD HH:MM:SS format |
* Either username+password or api_key is required.
GET https://whitelabled.securesmsc.com/httpapi/send?username=USERNAME&password=PASSWORD&sender_id=SMSCIN&route=T&phonenumber=9876543210&message=Your%20OTP%20is%20123456
GET https://whitelabled.securesmsc.com/httpapi/send?username=USERNAME&password=PASSWORD&sender_id=SMSCIN&route=T&schedule=2026-03-08%2010:00:00&phonenumber=9876543210&message=Scheduled%20message
GET https://whitelabled.securesmsc.com/httpapi/send?username=USERNAME&password=PASSWORD&sender_id=PROMOTIONAL&route=P&phonenumber=9876543210&message=Special%20offer%20for%20you
Success: 123_abc456def_1709830000 (Broadcast ID)
Error: -7 (Authentication failed)
username + password, or api_key
GET https://whitelabled.securesmsc.com/api/getcredits?username=USERNAME&password=PASSWORD
49250| Parameter | Description |
|---|---|
username / password | Account credentials |
phonenumber | Recipient mobile number |
broadcastid | Broadcast ID from send response |
date | Date in YYYYMMDD format |
delivered | submitted | failed | -15 (not found)username + password — Returns JSON array of approved templates.
| Parameter | Description |
|---|---|
username / password | Account credentials |
sender_id | Approved sender ID |
template_name | Template name |
template_message | Template message content |
dlt_template_id | DLT template ID |
notes | Notes (optional) |
123_456 (user_id + template_id)Returns account status: active, inactive, blocked
Returns JSON array of MIS report records. Supports limit, offset, sender_id filters.
/xmlapi/send
Send SMS via XML payload. POST raw XML in xmlstring form parameter.
<pushsms>
<username>USERNAME</username>
<password>PASSWORD</password>
<senderid>SMSCIN</senderid>
<messages>
<message pno="9876543210" msg="Hello from XML API"></message>
<message pno="9876543211" msg="Second message"></message>
</messages>
</pushsms>
| Parameter | Description |
|---|---|
apikey | Your API key |
from | Sender number (approved) |
to | Recipient phone number |
text | Message text (text-to-speech) |
GET https://whitelabled.securesmsc.com/voicecall/v1/send?apikey=YOUR_KEY&from=9876543210&to=9876543211&text=Your%20OTP%20is%20123456
POST /voicecall/v1/post/send — Same parameters via POSTPOST /voicecall/v1/jpost/send — JSON body formatSend transactional and bulk email through the same account and API key you use for SMS.
Each accepted recipient consumes 1 email credit from your bulkmail balance.
Both GET and POST are supported on every endpoint below.
| Endpoint | Description |
|---|---|
POST /httpemailapi/v1/send | Recommended endpoint |
POST /httpemailapiv2/send | v2 alias (identical parameters) |
POST /httpemailapi/send | Legacy alias (backward compatible) |
| Parameter | Required | Description |
|---|---|---|
api_key | Yes* | Your API key (apikey also accepted). *Alternatively authenticate with username + password. |
from | Yes | Sender, e.g. Your Name <noreply@yourdomain.com> (approved domain) |
to | Yes | Recipient email address(es), comma-separated for multiple |
subject | Yes | Email subject line |
html | Yes | HTML body content |
text | No | Plain-text alternative body |
cc | No | CC recipients, comma-separated |
bcc | No | BCC recipients, comma-separated |
replyto | No | Reply-To address |
templateid | No | Stored email template ID (use with defaultplaceholders) |
defaultplaceholders | No | JSON object of placeholder values for the template |
attachment | No | File attachment(s) — multipart/form-data |
trackopens | No | true/false — open tracking |
trackclicks | No | true/false — click tracking |
sendat | No | Schedule delivery, e.g. 2026-08-01 10:00:00 |
notifyurl | No | Webhook URL for delivery reports (defaults to platform DLR handler) |
callbackdata | No | Opaque string echoed back in delivery callbacks |
curl -X POST "https://whitelabled.securesmsc.com/httpemailapi/v1/send" \
--data-urlencode "api_key=YOUR_API_KEY" \
--data-urlencode "from=Your Company <noreply@yourdomain.com>" \
--data-urlencode "to=customer@example.com" \
--data-urlencode "subject=Your order has shipped" \
--data-urlencode "html=<h3>Order shipped</h3><p>Track it in your account.</p>"
| Response | Meaning |
|---|---|
Broadcast ID, e.g. 3_597d04cd…_1784335654 | Accepted — email queued for delivery. Use this ID to match delivery reports. |
-7 | Authentication failed — invalid API key or username/password |
-11 | Validation failed — missing from/to/subject/html, unapproved sender, or insufficient email credits |
notifyurl to receive JSON delivery
notifications (sent / delivered / bounced) per recipient, including your
callbackdata. Open and click events are delivered to the same URL when
trackopens/trackclicks are enabled.
Receive real-time delivery notifications and status updates via webhooks.
Configure a webhook URL in your dashboard to receive delivery status updates:
{
"event": "delivery_report",
"message_id": "12345",
"status": "delivered",
"delivered_at": "2025-01-07T10:30:00Z",
"recipient": "1234567890"
}
Receive incoming SMS messages on your virtual numbers:
{
"event": "inbound_sms",
"from": "1234567890",
"to": "9876543210",
"message": "Reply message content",
"received_at": "2025-01-07T10:35:00Z"
}
Use the HTTP APIs directly with any HTTP client. Ready-made samples are available by language:
See Language Guides for the full list, or try the API Playground.
GET https://whitelabled.securesmsc.com/api/v2/balance and GET https://whitelabled.securesmsc.com/api/v2/sender-ids.POST https://whitelabled.securesmsc.com/api/v2/sms/send.GET https://whitelabled.securesmsc.com/api/v2/sms/status/{messageId} or check MIS reports in the panel.All API endpoints return these standard error codes as plain text responses:
| Code | Type | Description |
|---|---|---|
-1 | API | Missing User ID / API Key |
-2 | API | Missing Password |
-3 | API | Reserved |
-4 | API | Missing Sender ID |
-5 | API | Missing / Invalid Mobile Number |
-6 | API | Missing Message Text |
-7 | API | Authentication Failed |
-8 | API | Content Not Allowed |
-9 | XML API | Malformed XML Data Received |
-10 | API | Invalid Sender ID or Route |
-11 | API | Mobile Number in DND |
-12 | API | Credit Not Available |
-13 | API | Flood Limit Not Sufficient |
-14 | API | Internal Error |
-15 | DLR API | Invalid Broadcast ID / Phone Number |
-16 | API | User Account Locked |
-17 | API | Invalid Route ID (T/P/PS/I/V) |
-18 | API | Invalid Route or Sender ID Mapping |
-19 | API | Route or Sender ID Not Approved |
-20 | API | International SMS Not Enabled |
-21 | API | International Credit Not Available |
-22 | API | Promo with Sender ID Not Enabled |
-31 | API | DLT Entity ID Not White-listed |
-32 | API | DLT Header ID Not White-listed |
-40 | Hybrid | Unicode not allowed in message param — use text param or type=2 with UTF-16BE |
| Code | Description |
|---|---|
-1 | Missing API Key |
-4 | Missing Sender (From) |
-5 | Missing Mobile Number (To) |
-6 | Missing Message Text |
-7 | Authentication Failed |
-10 | Invalid Sender or Route |
-12 | Credit Not Available |
-14 | Internal Error |