BLACK API Documentation

Complete guide to integrate OTP & WhatsApp OTP service with your application.

Integration Steps

1

Set Up Your Environment

Make sure you have PHP with cURL extension enabled on your server.

2

Get Your API Key

Your API key:


                    YOUR_API_KEY

3

Implement the API Call

Use the code examples below to integrate the API in your application.

API Endpoints

SMS OTP

POST https://blacksms.in/sms

WhatsApp OTP

POST https://blacksms.in/wasms

Quick SMS (GET / POST)

GET / POST https://blacksms.in/quick-sms

Bulk SMS Campaign

POST https://blacksms.in/endpoints/v1/bulk-sms

DLT Compliant SMS (Entity + Header + Template)

POST https://blacksms.in/dlt-sms

Request Format

1. OTP Send API (SMS & WhatsApp)

Headers

Header	Value	Required
Authorization	Your API key	Yes
Content-Type	application/json	Yes

Request Body Parameters

Parameter	Type	Description	Required
sender_id	String	Your sender ID (YOUR_SENDER_ID)	Yes
variables_values	String	The OTP value to send (4-6 digits)	Yes
numbers	String	Recipient's 10-digit mobile number	Yes
route	Integer	The route to use (1 to 9)	No (default: 1)

2. Bulk SMS Campaign API

Headers

Header	Value	Required
Authorization	Your API key	Yes
Content-Type	application/json	Yes

Request Body Parameters

3. DLT SMS Dispatch API (Approved Sender ID + Message ID + Variables)

Headers

Parameter	Type	Description	Required

Header	Value	Required
Authorization	Your API key (`YOUR_API_KEY`)	Yes
Content-Type	application/json	Yes

Request Body Parameters

Parameter	Type	Description	Required
authorization	String	Your API key (Alternative to Authorization Header)	Yes
sender_id	String	Approved DLT Sender ID / Header approved in DLT Manager (e.g. `BLKSMS`)	Yes
message_id	String	Assigned Random Message ID (e.g. `197853`) or DLT Template ID (e.g. `1207161234567890123`)	Yes
numbers	String	10-digit Indian recipient mobile number(s) (comma separated for multiple)	Yes
variables_values	String	Values for template variables separated by pipe `\|` if multiple (e.g. `123456` or `123456\|Rahul`)	Required if template has variables

Note: Parameter aliases are also supported: header for sender_id, template_id for message_id, mobile for numbers, and variables for variables_values.

Code Examples

DLT SMS API Integration (cURL, PHP, Python, JS)

cURL

curl -X POST https://blacksms.in/dlt-sms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "BLKSMS",
    "message_id": "197853",
    "numbers": "9876543210",
    "variables_values": "123456|Rahul"
  }'

PHP (cURL)

<?php
$payload = [
    "sender_id"        => "BLKSMS",
    "message_id"       => "197853",
    "numbers"          => "9876543210",
    "variables_values" => "123456|Rahul"
];

$ch = curl_init("https://blacksms.in/dlt-sms");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        "Authorization: YOUR_API_KEY",
        "Content-Type: application/json"
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
$resData = json_decode($response, true);
echo "Status: " . $resData['message'];
?>

Python (requests)

import requests

url = "https://blacksms.in/dlt-sms"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "sender_id": "BLKSMS",
    "message_id": "197853",
    "numbers": "9876543210",
    "variables_values": "123456|Rahul"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript (Node.js / fetch)

fetch('https://blacksms.in/dlt-sms', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender_id: 'BLKSMS',
    message_id: '197853',
    numbers: '9876543210',
    variables_values: '123456|Rahul'
  })
})
.then(res => res.json())
.then(data => console.log(data));

OTP Sending API Integration

cURL

curl -X POST https://blacksms.in/sms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "YOUR_SENDER_ID", "variables_values": "123456", "numbers": "9876543210", "route": 1}'

PHP

<?php
$data = [
    "sender_id"        => "YOUR_SENDER_ID",
    "variables_values" => "123456",
    "numbers"          => "9876543210",
    "route"            => 1
];
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://blacksms.in/sms",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        "Authorization: YOUR_API_KEY",
        "Content-Type: application/json"
    ],
]);
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
?>

JavaScript (fetch)

fetch('https://blacksms.in/sms', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender_id: 'YOUR_SENDER_ID',
    variables_values: '123456',
    numbers: '9876543210',
    route: 1
  })
})
.then(r => r.json())
.then(data => console.log(data));

Bulk SMS Campaign API Integration

cURL

curl -X POST https://blacksms.in/endpoints/v1/bulk-sms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Promo Campaign", "message": "Check out our services!", "contacts": ["9876543210", "9123456789"]}'

PHP

<?php
$data = [
    "title"    => "Promo Campaign",
    "message"  => "Check out our services!",
    "contacts" => ["9876543210", "9123456789"]
];
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://blacksms.in/endpoints/v1/bulk-sms",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        "Authorization: YOUR_API_KEY",
        "Content-Type: application/json"
    ],
]);
$response = curl_exec($curl);
curl_close($curl);
$result = json_decode($response, true);
?>

JavaScript (fetch)

fetch('https://blacksms.in/endpoints/v1/bulk-sms', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Promo Campaign',
    message: 'Check out our services!',
    contacts: ['9876543210', '9123456789']
  })
})
.then(r => r.json())
.then(data => console.log(data));

Response Format

1. OTP Sending API Response

Success

{ "status": 1, "message": "OTP Sent" }

Error

{ "status": 0, "message": "Error description details" }

2. Bulk SMS Campaign API Response

Success

{
  "success": true,
  "message": "Bulk SMS Campaign created successfully.",
  "campaign_id": 12,
  "provider_campaign_id": "98124",
  "total_contacts": 2,
  "sms_parts": 1,
  "total_cost": 0.40,
  "tracking_url": "https://blacksms.in/bulk-sms/campaign/12",
  "invalid_ignored": 0,
  "invalid_list": []
}

Error

{
  "success": false,
  "message": "Error description details"
}

Email OTP API NEW

Send One-Time Passwords (OTPs) directly to your users' email addresses using your connected SMTP account or Google/Gmail account.

Custom SMTP

Any SMTP provider

Google / Gmail

OAuth — no password

Email OTP Endpoint

POST

https://blacksms.in/endpoints/v1/email-otp

Required Headers

Header	Value	Required
`Authorization`	Your API Key	✅
`Content-Type`	`application/json`	✅

Request Body (JSON)

Parameter	Type	Required	Description
`email`	string	✅	Recipient email address
`template_id`	integer	—	ID of your saved email template. `0` = default built-in template
`sender_id`	string	—	Which sender account to use: `smtp_1`, `google_1`. Auto-selects if omitted.
`variables`	object	—	Extra template variables e.g. `{"name": "Alice"}`. Pass `{"otp": "123456"}` to use a specific OTP.

sender_id Format

smtp_<id> — Use a Custom SMTP account (e.g. smtp_1)
google_<id> — Use a connected Google account (e.g. google_1)
Omit — Auto-selects: SMTP account → Google account

Find IDs in SMTP Accounts or Google Accounts.

Email OTP — Code Examples

<?php
$apiKey = 'YOUR_API_KEY';
$url    = 'https://blacksms.in/endpoints/v1/email-otp';

$data = [
    'email'       => '[email protected]',
    'template_id' => 0,           // 0 = default template
    'sender_id'   => 'smtp_1',    // optional
    'variables'   => ['name' => 'Alice'],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        'Authorization: ' . $apiKey,
        'Content-Type: application/json',
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
    echo 'OTP sent! Request ID: ' . $response['request_id'];
} else {
    echo 'Error: ' . $response['message'];
}
?>

import requests

api_key = 'YOUR_API_KEY'
url     = 'https://blacksms.in/endpoints/v1/email-otp'

payload = {
    'email':       '[email protected]',
    'template_id': 0,
    'sender_id':   'smtp_1',     # optional
    'variables':   {'name': 'Alice'},
}

resp = requests.post(url, json=payload, headers={
    'Authorization': api_key,
    'Content-Type':  'application/json',
})
data = resp.json()

if data['success']:
    print('OTP sent! Request ID:', data['request_id'])
else:
    print('Error:', data['message'])

const apiKey = 'YOUR_API_KEY';
const url    = 'https://blacksms.in/endpoints/v1/email-otp';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': apiKey,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    email:       '[email protected]',
    template_id: 0,
    sender_id:   'smtp_1',       // optional
    variables:   { name: 'Alice' },
  }),
});

const data = await response.json();
if (data.success) {
  console.log('OTP sent! Request ID:', data.request_id);
} else {
  console.error('Error:', data.message);
}

curl -X POST https://blacksms.in/endpoints/v1/email-otp \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email":       "[email protected]",
    "template_id": 0,
    "sender_id":   "smtp_1",
    "variables":   {"name": "Alice"}
  }'

Email OTP — Response Format

✅ Success (HTTP 200)

{
  "success":    true,
  "message":    "OTP sent successfully.",
  "request_id": "EML-4A9F3C1B2E",
  "email":      "[email protected]",
  "expires_in": 600,
  "cost":       0.10,
  "balance":    49.90
}

❌ Error

{
  "success":    false,
  "message":    "Invalid email address.",
  "request_id": "EML-1B3D7A9F0C"
}

Error Codes

HTTP	Meaning
`200`	OTP sent successfully (₹0.10 deducted)
`400`	Invalid JSON body or missing parameter
`401`	Invalid or missing API key
`402`	Insufficient balance (minimum ₹0.10 required)
`403`	Account suspended
`404`	Template ID not found
`405`	Method not allowed (use POST)
`422`	Invalid email address format
`429`	Rate limit exceeded (60 req/min)
`500`	Email delivery failed

Security Notes

OTPs are generated server-side with random_int() (CSPRNG)
OTPs are stored as SHA-256 hashes only — never plain text
SMTP passwords are encrypted with AES-256-CBC
Google OAuth tokens are encrypted and refreshed automatically
Rate limiting: 60 requests per minute per API key