iMissive
Developer Integration

API Documentation

Comprehensive guide to integrating iMissive SMS, OTP, Webhooks, and SMPP services into your applications

Quick StartSMS APIOTP APISMPP
Quick Start
Get started sending your first message in minutes
View details
Authentication
Learn how to authenticate your API requests
View details
SMS API
Send and receive SMS messages
View details
OTP API
Generate and verify OTP codes
View details
Webhooks
Receive real-time delivery notifications
View details
SMPP
Enterprise SMPP connectivity
View details
Rate Limits
Understand API limits and quotas
View details
Error Codes
Handle errors and responses
View details
Quick Start

Quick Start

Send your first message in just a few minutes

1
Get Your API Key

Log in to your dashboard and retrieve your API key from the Settings section.

2
Send a Message

Use the following code to send your first message:

Example - Sample endpoint
curl -X POST https://api.example.com/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+966501234567",
    "message": "Hello from iMissive!",
    "sender_id": "MyCompany"
  }'

* Replace YOUR_API_KEY with your actual API key. Production URL provided after onboarding.

Authentication

Authentication

All API requests require authentication via Bearer Token

Adding the Authorization Header
HTTP Header
Authorization: Bearer YOUR_API_KEY

Include this header in all your API requests. API keys are available from your dashboard.

Security Best Practices
  • Never share your API key publicly
  • Use environment variables to store keys
  • Rotate keys regularly
  • Always use HTTPS
SMS API

SMS API

Send single or bulk SMS messages

Send Single Message
POST /v1/sms/send
JSON
{
  "to": "+966501234567",
  "message": "Your message content here",
  "sender_id": "MyCompany",
  "scheduled_at": "2024-01-15T10:00:00Z" // optional
}
Send Bulk Messages
POST /v1/sms/bulk
JSON
{
  "messages": [
    { "to": "+966501234567", "message": "Hello User 1" },
    { "to": "+966501234568", "message": "Hello User 2" }
  ],
  "sender_id": "MyCompany"
}
OTP API

OTP API

Generate and verify one-time passwords

Send OTP
POST /v1/otp/send
JSON
{
  "phone": "+966501234567",
  "length": 6,           // 4-8 digits
  "expiry": 300,         // seconds (configurable)
  "template": "Your verification code is: {code}"
}
Verify OTP
POST /v1/otp/verify
JSON
{
  "otp_id": "otp_abc123",
  "code": "123456"
}
Webhooks

Webhooks

Receive real-time notifications about message status

Webhook Configuration

Configure your webhook URL from the dashboard to receive notifications.

Example Webhook Payload
POST https://your-server.com/webhook

{
  "event": "message.delivered",
  "message_id": "msg_abc123xyz",
  "timestamp": "2024-01-15T10:01:23Z",
  "data": {
    "to": "+966501234567",
    "status": "delivered",
    "delivered_at": "2024-01-15T10:01:22Z"
  }
}
Event Types
message.queuedMessage queued for delivery
message.sentMessage sent to carrier
message.deliveredMessage delivered to recipient
message.failedMessage delivery failed
SMPP

SMPP Connectivity

Enterprise SMPP v3.4 connectivity for high-volume messaging

Connection Details
HostProvided during onboarding
PortProvided during onboarding
system_idProvided during onboarding
passwordProvided during onboarding
VersionSMPP v3.4
Bind TypeBased on account configuration
ThroughputBased on approved commercial and technical configuration
Delivery ReceiptsSupported when enabled for the account

* SMPP credentials and connection details available after technical onboarding for qualified enterprise customers

Supported Features
  • Unicode support for Arabic messages
  • Long messages (automatic concatenation)
  • Delivery reports (DLR)
  • Message scheduling
  • Multiple binds
Rate Limits

Rate Limits

Rate limits and throughput depend on the approved account configuration, route, sender type, and commercial agreement

Rate Limit Types
API RequestsRequests per second/minute
Message ThroughputMessages per second/minute
SMPP ThroughputDefined per agreement
Campaign BatchingMaximum recipients per batch request
Account-Level LimitsDaily/monthly maximum quotas

* Contact sales for your account-specific limit details

Response Headers
HTTP Headers
X-RateLimit-Limit: <account_limit>
X-RateLimit-Remaining: <remaining_quota>
X-RateLimit-Reset: <reset_timestamp>
Error Codes

Error Codes

Reference for common error codes and how to handle them

HTTP Errors
400

Bad Request

Check the request body for validation errors

401

Unauthorized

Invalid or missing API key

403

Forbidden

You do not have permission for this action

429

Too Many Requests

Rate limit exceeded

500

Server Error

Try again later

Message Error Codes
Examples of common error codes
INVALID_PHONEInvalid phone number format
INVALID_SENDERSender ID not authorized
INSUFFICIENT_CREDITSNot enough credits
MESSAGE_TOO_LONGMessage exceeds maximum length

Frequently Asked Questions

Answers to the most common questions

Code Examples

Quick examples to get you started with integration

Send SMS Message
Example - Sample endpoint
bash
curl -X POST https://api.example.com/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+966501234567",
    "message": "Hello from iMissive!",
    "sender_id": "MyCompany"
  }'

Ready to start integrating?

Contact us to get your API keys and start integrating enterprise messaging services

Contact SalesLogin to Dashboard