SMS Provider API Documentation

Our REST API provides programmatic access to the SMS Provider platform to send messages, track delivery, and manage your account.

Introduction

To start using the SMS Provider API, you'll need to:

  1. Sign up for an account at SMS Provider
  2. Generate an API key in your dashboard
  3. Include the API key in your requests as shown in the examples

Base URL

https://api.smsprovider.com/v1

Authentication

All API requests must include your API key in the Authorization header:

curl -X GET https://api.smsprovider.com/v1/account \
-H "Authorization: Bearer YOUR_API_KEY"
Security Note:

Never share your API key publicly or include it in client-side code.

Sending SMS Messages

Send SMS messages to a single recipient or multiple recipients.

POST
/messages

Request Parameters

Parameters Type Required Description
to string or array Yes Phone number in E.164 format (e.g., +1234567890) or array of numbers
message string Yes Message content (max 1600 characters)
from string No Sender ID (if not specified, default will be used)
scheduled_at string No ISO 8601 timestamp for scheduled delivery
callback_url string No URL to receive delivery status updates

Example Request

curl -X POST https://api.smsprovider.com/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+1234567890",
"message": "Hello from SMS Provider!",
"from": "YourBrand"
}'

Example Response

{
"success": true,
"message_id": "msg_5f8d2b38c4a7f",
"credits_used": 1,
"credits_remaining": 1229,
"status": "queued"
}

Sending to Multiple Recipients

curl -X POST https://api.smsprovider.com/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": ["+1234567890", "+9876543210"],
"message": "Bulk message from SMS Provider!"
}'

Message Status Updates

Check the status of sent messages by message ID.

GET
/messages/{message_id}

Example Request

curl -X GET https://api.smsprovider.com/v1/messages/msg_5f8d2b38c4a7f \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
"message_id": "msg_5f8d2b38c4a7f",
"to": "+1234567890",
"from": "YourBrand",
"message": "Hello from SMS Provider!",
"status": "delivered",
"sent_at": "2023-12-01T15:23:45Z",
"delivered_at": "2023-12-01T15:23:48Z"
}

Status Codes

Status Description
Queued The message is in queue for delivery
Sent The message was sent to the operator
Delivered The message was delivered successfully
Failed Failed to deliver the message
Expired The message expired before being delivered

Error Codes

When an error occurs, the API will return an error response.

{
"success": false,
"error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits"
}
}

Common Error Codes

Code Description
authentication_failed Invalid or missing API key
insufficient_credits Account has insufficient credits
invalid_phone_number Phone number format is invalid
message_too_long Message exceeds maximum length
rate_limit_exceeded API rate limit exceeded

Client Libraries

We offer official client libraries for popular programming languages:

JavaScript

npm install smsprovider-js
View Docs

PHP

composer require smsprovider/smsprovider-php
View Docs

Python

pip install smsprovider
View Docs

Java

<dependency>
<groupId>com.smsprovider</groupId>
<artifactId>smsprovider-java</artifactId>
<version>1.0.0</version>
</dependency>
View Docs

Rate Limits

To ensure platform stability, API requests are subject to rate limiting.

Plan Rate Limit
Standard 10 requests per second
Enterprise 50 requests per second

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests per period
  • X-RateLimit-Remaining: Requests remaining in current period
  • X-RateLimit-Reset: Time (in seconds) until rate limit resets

Webhooks

Receive real-time updates about message status changes through webhooks.

Setting Up Webhooks

Configure your webhook URL in the dashboard or via API:

curl -X POST https://api.smsprovider.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/sms-webhook",
"events": ["message.delivered", "message.failed"]
}'

Webhook Payload Example

{
"event": "message.delivered",
"message_id": "msg_5f8d2b38c4a7f",
"to": "+1234567890",
"status": "delivered",
"delivered_at": "2023-12-01T15:23:48Z",
"timestamp": 1701446628
}

Webhook Security

Verify webhook authenticity by checking the signature in the X-SMSProvider-Signature header: 

// Example verification in Node.js
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');

return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}