SMS Messaging API

The EnableX SMS API lets you send and receive SMS messages worldwide through a single REST API. You can send transactional messages (OTPs, alerts, confirmations), promotional campaigns (offers, announcements), and two-way conversations — all with high delivery rates, intelligent routing, and real-time delivery reporting.

SMS is the most universal messaging channel — it reaches every mobile phone regardless of internet connectivity or app installations. With EnableX, you get carrier-grade infrastructure without negotiating with individual operators or managing telecom complexity.

▶  Run in Postman Collection last updated Aug 12, 2024

Use Cases

SMS serves different business needs depending on the message type and audience:

Key Capabilities

The EnableX SMS platform provides:

Quick Start — Send Your First SMS

Follow these four steps to go from zero to sending your first SMS message. The entire process takes less than 10 minutes.

Step 1: Sign Up and Create a Project

Sign up at the EnableX Portal and create an SMS project:

1. Log in to the portal and navigate to My Projects.
2. Click CREATE PROJECT.
3. Enter a project name and description.
4. In the Channels section, enable SMS services.
5. Click CREATE PROJECT to confirm.

On successful creation, a confirmation popup displays your APP ID and APP Key — these are also emailed to your registered address. Save these credentials securely; you will need them for every API call.

Step 2: Subscribe to SMS Service

After creating your project, subscribe to the SMS service through the portal. For trial accounts, a default campaign and test template are automatically provisioned — you can send test SMS immediately.

Step 3: Send a Test SMS

Use the Try Now feature in the portal to send a quick test SMS without writing any code:

1. Go to the SMS section and click Try Now.
2. Select the default campaign.
3. Enter a recipient number (trial accounts can send to registered numbers only).
4. Click send.

The portal also provides a ready-to-use code snippet that you can copy into your application for programmatic testing.

Step 4: Send SMS Programmatically

Once you have your APP ID, APP Key, Campaign ID, and an approved template, send your first SMS via the API:

POST https://api.enablex.io/sms/v1/messages/
Authorization: Basic base64(APP_ID:APP_KEY)
Content-Type: application/json

{
  "from": "+44999999999",
  "to": ["+919876543210"],
  "type": "sms",
  "campaign_id": "your-campaign-id",
  "template_id": "your-template-id",
  "data_coding": "plain"
}

Success Response:

{
  "result": 0,
  "job_id": "5e71f1b23630865c34443fb4"
}

The job_id is your tracking reference — use it to query delivery status or correlate with webhook notifications.

Setup and Resources

Before sending production SMS, you need to configure three resources in the EnableX Portal: a Sender Identity, a Message Template, and optionally a Phone Number for two-way messaging.

Sender ID

A Sender ID is an alphanumeric string (up to 11 characters) that appears as the sender name in the recipient's inbox — for example, MYBANK instead of a phone number. Sender IDs help brand your messages and increase open rates.

To request a Sender ID:

1. Navigate to SMS → Resource → Sender ID in the portal.
2. Click ADD SENDER ID.
3. Select your country of operation.
4. Enter the Sender ID string and a sample SMS.
5. Submit for verification.

Sender ID requests go through an approval process. Once approved, the status changes from Pending to Fulfilled. Trial accounts use the default Sender ID ENABLX.

SMS Templates

An SMS template is a pre-defined message body that you create, submit for approval, and reuse across campaigns. Templates support dynamic placeholders for personalization — data fields enclosed in {$variable} syntax that are replaced with actual values at send time.

Example template body:

Hi {$name}, your order {$order_id} has been shipped. Track at {$tracking_url}

To create a template:

1. Navigate to SMS → Resource → Template in the portal.
2. Click NEW TEMPLATE REQUEST.
3. Select your country and template type.
4. Enter the template title and SMS body with any {$variable} placeholders.
5. Submit for review.

Once approved, the template appears in your template list with status Fulfilled and a template_id that you reference in API calls.

Virtual Numbers (Long Code / Short Code)

To receive incoming SMS or to use a phone number as the sender instead of a Sender ID, you need a virtual number.

To order a number:

1. Navigate to SMS → Resource → Phone Number in the portal.
2. Click BUY A NUMBER.
3. Choose country and number type (Long Code, Short Code).
4. Search and purchase from EnableX inventory, or place a custom order.

EnableX offers virtual numbers in 100+ countries. Shared short codes provide ready-to-use delivery at lower cost, while dedicated numbers build brand identity.

Campaign Management

A campaign is the operational container that ties together your sender identity, message templates, phone numbers, webhook configuration, and country-specific settings. Every SMS you send goes through a campaign.

Creating a Campaign

1. Navigate to SMS → Dashboard → My Campaigns.
2. Select your SMS project and click CREATE CAMPAIGN.
3. Configure the campaign settings:

Outgoing SMS Campaign Settings

For outgoing campaigns, configure:

Sender ID — Select an approved Sender ID or create a new one.
Template — Approved message templates are linked to campaigns for use.
Long Code / Short Code — Optionally assign a purchased phone number.
Webhook URL — Enter an HTTPS URL to receive delivery notifications.

Incoming SMS Campaign Settings

For incoming campaigns, you must assign a phone number (Long Code or Short Code) and provide a webhook URL where incoming messages will be delivered via HTTP POST.

Try Campaign Now

After creating a campaign, use the Try Now option to send a test SMS immediately. Trial accounts can send up to 10 free messages. For paid accounts, charges are deducted from your EnableX Wallet.

Scheduling a Campaign

You can schedule bulk campaign delivery for a future date and time:

1. Go to My Campaigns and click the Send/Schedule icon on your campaign.
2. Select a message template, review the SMS body, and choose the Sender ID.
3. Upload a recipient list in .csv, .xls, or .xlsx format.
4. Either click SEND NOW for immediate delivery or set a date/time and click SCHEDULE.

Using Campaign ID in the API

To get your Campaign ID for API use, go to My Campaigns and click the Copy Campaign Link icon. The ID is copied to your clipboard — paste it into the campaign_id field of your API payloads.

Base URL

All SMS API endpoints use the following base URL:

https://api.enablex.io/sms/v1/

Authentication

EnableX supports two authentication mechanisms for the SMS API.

HTTP Basic Authentication

Each SMS project is assigned an APP ID and APP Key. Create a base64-encoded string of APP_ID:APP_KEY and pass it in the Authorization header.

POST https://api.enablex.io/sms/v1/messages/
Authorization: Basic base64(APP_ID:APP_KEY)
Content-Type: application/json

Bearer Token Authentication

Generate a Bearer Token valid for 60 minutes. During this window, use the token for any number of API calls.

Create a token:

POST https://api.enablex.io/sms/v1/token
Content-Type: application/json

{
  "app_id": "your-app-id",
  "app_key": "your-app-key"
}

Response:

{
  "result": 0,
  "token": "eyJhbGciOiJIUz..."
}

Use the token in subsequent requests:

POST https://api.enablex.io/sms/v1/messages/
Authorization: Bearer eyJhbGciOiJIUz...
Content-Type: application/json

Authentication Errors

{
  "result": "1",
  "details": "Authentication failed",
  "desc": "Authentication failed"
}

If using Bearer Token auth, regenerate a new token and retry.

Send SMS API

The primary API for sending SMS messages. Supports single recipients, bulk delivery with data merge, scheduling, and multiple encoding options.

Send SMS — POST Method

POST https://api.enablex.io/sms/v1/messages/
Authorization: Basic base64(APP_ID:APP_KEY)
Content-Type: application/json

The JSON payload structure supports two recipient modes: a simple to array for uniform messages, or a recipient array for personalized data merge.

Simple Delivery (Same Message to All)

Use the to array with the data object for one-time field replacement applied to all recipients:

{
  "from": "+44999999999",
  "to": [
    "+919876543210",
    "+919876543211"
  ],
  "data": {
    "event": "Summer Sale",
    "venue": "Online Store",
    "start_date": "Apr 15, 2025"
  },
  "type": "sms",
  "campaign_id": "your-campaign-id",
  "template_id": "your-template-id",
  "data_coding": "plain"
}

Personalized Delivery (Per-Recipient Data Merge)

Use the recipient array when each recipient needs unique placeholder values:

{
  "from": "+44999999999",
  "recipient": [
    {
      "to": "+919876543210",
      "name": "Rahul",
      "amount": "1,500",
      "uuid": "ext-ref-001"
    },
    {
      "to": "+919876543211",
      "name": "Priya",
      "amount": "2,300",
      "uuid": "ext-ref-002"
    }
  ],
  "type": "sms",
  "campaign_id": "your-campaign-id",
  "template_id": "your-template-id",
  "data_coding": "plain"
}

Complete Payload Reference

Success Response:

{
  "result": 0,
  "job_id": "5e71f1b23630865c34443fb4"
}

The result: 0 indicates success. The job_id is the unique identifier for this SMS job — use it to query delivery status.

Send SMS — GET Method

For simpler integrations, you can send SMS using an HTTP GET request with query string parameters. This is useful for quick integrations from systems that only support HTTP GET.

GET https://api.enablex.io/sms/v1/send-sms?username={APP_ID}&password={APP_KEY}&from=%2B44999999999&to=%2B919876543210&type=sms&campaign_id={ID}&template_id={ID}&data_coding=plain

Delivery Status and Reporting

After sending an SMS, you can track its delivery status in two ways: by polling the status API or by receiving real-time webhook notifications.

Query Delivery Status (API Polling)

GET https://api.enablex.io/sms/v1/message/{job_id}
Authorization: Basic base64(APP_ID:APP_KEY)

Response:

{
  "result": 0,
  "job_id": "5e71f1b23630865c34443fb4",
  "summary": {
    "total": 10,
    "sent": 10,
    "delivered": 8,
    "failed": 1,
    "unknown": 1
  },
  "detailed": [
    {
      "to": "+919876543210",
      "sent": "2025-03-15T08:29:42Z",
      "delivered": "2025-03-15T08:29:45Z",
      "uuid": "ext-ref-001",
      "status": "delivered"
    }
  ]
}

The response includes both a summary (aggregate counts) and a detailed array (per-recipient status). The uuid field appears only if you provided it in the recipient array when sending.

Delivery Notifications via Webhook

If you configure a Delivery Notification Webhook URL in your campaign settings, EnableX posts real-time delivery updates as they occur. This is the recommended approach for production systems.

{
  "job_id": "5e71f1b23630865c34443fb4",
  "detailed": [
    {
      "to": "+919876543210",
      "datetime": "2025-03-15 08:29:45",
      "status": "delivered"
    },
    {
      "to": "+919876543211",
      "datetime": "2025-03-15 08:30:02",
      "error_code": "202",
      "error_des": "User abort",
      "status": "failed"
    }
  ]
}

The uuid field appears in webhook notifications only if you provided it in the recipient array when sending. For failed messages, error_code and error_des provide the failure reason.

Incoming SMS (Two-Way Messaging)

To receive SMS messages from users, you need a virtual number (Long Code or Short Code) assigned to a campaign with incoming SMS enabled, and a webhook URL configured to receive the messages.

Setup Requirements

1. Purchase a phone number through the EnableX Portal (SMS → Resource → Phone Number).
2. Assign the number to a campaign with SMS In Only or Both Ways direction.
3. Configure the webhook URL in the campaign settings.

Incoming Message Webhook Payload

When a user sends an SMS to your EnableX number, the message is forwarded to your webhook URL via HTTP POST:

{
  "id": "61e8efab5c8ece74657d3d54",
  "to": "44999999999",
  "received": "2025-03-15T05:14:19Z",
  "from": "919876543210",
  "body": "Hello, I need help with my order"
}

Character Encoding and Message Length

SMS character limits depend on the encoding used:

When a message exceeds the single-SMS limit, it is automatically split into multiple segments (concatenated SMS). Each segment uses slightly fewer characters (153 for GSM-7, 67 for Unicode) because some bytes are reserved for the concatenation header that allows the recipient's phone to reassemble the segments in order.

Error Handling

SMS API responses use a numeric result code to indicate success or failure. A result of 0 means success; any non-zero value indicates an error.

Success:

{
  "result": 0,
  "job_id": "5e71f1b23630865c34443fb4"
}

Error:

{
  "result": "1003",
  "error": "Campaign not found",
  "desc": "The specified campaign_id does not exist or is not active"
}

Best Practices

Consent and Opt-In

Always obtain explicit consent before sending SMS. Many countries legally require opt-in before sending promotional messages. Implement clear opt-out mechanisms — a standard approach is to honor STOP keyword replies and confirm unsubscription.

Message Content

Keep messages concise — aim for a single SMS segment (160 characters for GSM-7). Include your brand name for recognition. For promotional messages, many countries require an opt-out instruction in the message body (e.g., "Reply STOP to unsubscribe").

Timing and Throttling

Respect local time restrictions — several countries prohibit promotional SMS during nighttime hours (e.g., India: 9 PM to 9 AM). For bulk campaigns, EnableX throttles at approximately 1 SMS per second per number. For higher throughput, use multiple numbers or short codes.

Fallback and Retry

Use the validity parameter to set an expiry window for time-sensitive messages like OTPs. Monitor delivery webhooks for failed statuses and implement retry logic with exponential backoff. For critical messages, consider a fallback to an alternate channel.

Compliance

Familiarize yourself with regulations for every country you message into. Requirements vary significantly — from DLT registration in India to 10DLC in the United States to content whitelisting in China. See the SMS Regulations page for comprehensive country-by-country guidance.