Send Your First SMS

Send your first SMS with Exotel in under 5 minutes. This guide walks you through getting your API credentials and making your first API call.

Prerequisites

Before you begin, make sure you have:

• An Exotel account (Sign up here)
• API credentials (API Key, API Token, Account SID)
• For India: DLT registration (Entity ID and Template ID)

Where to find your credentials

Log in to the Exotel Dashboard → Settings → API Settings. You'll find your API Key, API Token, and Account SID on this page. See Authentication for details.

Step 1: Set Up Your Credentials

Store your credentials as environment variables to keep them out of your code:

macOS / Linux

export EXOTEL_API_KEY="your_api_key"
export EXOTEL_API_TOKEN="your_api_token"
export EXOTEL_ACCOUNT_SID="your_account_sid"
export EXOTEL_SUBDOMAIN="api.exotel.com"

Windows

set EXOTEL_API_KEY=your_api_key
set EXOTEL_API_TOKEN=your_api_token
set EXOTEL_ACCOUNT_SID=your_account_sid
set EXOTEL_SUBDOMAIN=api.exotel.com

Which subdomain?

Use api.exotel.com (Singapore) for most accounts, or api.in.exotel.com (Mumbai) for India-based accounts with lower latency needs.

Step 2: Send Your First SMS

cURL

curl -X POST "https://$EXOTEL_API_KEY:$EXOTEL_API_TOKEN@$EXOTEL_SUBDOMAIN/v1/Accounts/$EXOTEL_ACCOUNT_SID/Sms/send" \
  -d "From=EXOTEL" \
  -d "To=+919876543210" \
  -d "Body=Hello from Exotel! Your OTP is 123456" \
  -d "DltEntityId=YOUR_DLT_ENTITY_ID" \
  -d "DltTemplateId=YOUR_DLT_TEMPLATE_ID"

Node.js

// send-sms.js — Requires Node.js 18+
const apiKey = process.env.EXOTEL_API_KEY;
const apiToken = process.env.EXOTEL_API_TOKEN;
const accountSid = process.env.EXOTEL_ACCOUNT_SID;
const subdomain = process.env.EXOTEL_SUBDOMAIN || 'api.exotel.com';

async function sendSMS() {
  const url = `https://${subdomain}/v1/Accounts/${accountSid}/Sms/send`;

  const params = new URLSearchParams({
    From: 'EXOTEL',
    To: '+919876543210',
    Body: 'Hello from Exotel! Your OTP is 123456',
    DltEntityId: 'YOUR_DLT_ENTITY_ID',
    DltTemplateId: 'YOUR_DLT_TEMPLATE_ID',
  });

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + Buffer.from(`${apiKey}:${apiToken}`).toString('base64'),
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: params,
    });

    const data = await response.json();

    if (response.ok) {
      console.log('SMS sent successfully!');
      console.log('SMS SID:', data.SMSMessage.Sid);
      console.log('Status:', data.SMSMessage.Status);
    } else {
      console.error('Failed:', data);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

sendSMS();

Run with:

node send-sms.js

Python

# send_sms.py
import os
import requests

api_key = os.environ['EXOTEL_API_KEY']
api_token = os.environ['EXOTEL_API_TOKEN']
account_sid = os.environ['EXOTEL_ACCOUNT_SID']
subdomain = os.environ.get('EXOTEL_SUBDOMAIN', 'api.exotel.com')

url = f'https://{subdomain}/v1/Accounts/{account_sid}/Sms/send'

data = {
    'From': 'EXOTEL',
    'To': '+919876543210',
    'Body': 'Hello from Exotel! Your OTP is 123456',
    'DltEntityId': 'YOUR_DLT_ENTITY_ID',
    'DltTemplateId': 'YOUR_DLT_TEMPLATE_ID',
}

response = requests.post(url, data=data, auth=(api_key, api_token))

if response.ok:
    result = response.json()
    print('SMS sent successfully!')
    print('SMS SID:', result['SMSMessage']['Sid'])
    print('Status:', result['SMSMessage']['Status'])
else:
    print('Failed:', response.text)

Run with:

pip install requests
python send_sms.py

Step 3: Check the Response

A successful request returns:

{
  "SMSMessage": {
    "Sid": "a]1b2c3d4e5f6",
    "AccountSid": "your_sid",
    "From": "EXOTEL",
    "To": "+919876543210",
    "Body": "Hello from Exotel! Your OTP is 123456",
    "Status": "queued",
    "DateCreated": "2026-02-25 10:30:00",
    "DateSent": null,
    "Price": null
  }
}

Field	What it means
Sid	Your unique SMS ID — save this to check delivery later
Status	queued means accepted and waiting to be sent
Price	Updates after delivery

Important

A 200 response means the SMS was accepted, not delivered. The Status will be queued. Use the SMS Details endpoint or set up a StatusCallback webhook to track delivery.

Step 4: Verify Delivery (Optional)

Check if your SMS was delivered using the Sid from Step 3:

curl "https://$EXOTEL_API_KEY:$EXOTEL_API_TOKEN@$EXOTEL_SUBDOMAIN/v1/Accounts/$EXOTEL_ACCOUNT_SID/SMS/Messages/YOUR_SMS_SID.json"

Look for "DetailedStatus": "DELIVERED_TO_HANDSET" in the response.

Understanding DLT (India)

What is DLT?

DLT (Distributed Ledger Technology) is a regulatory requirement by TRAI for all SMS sent in India. You need:

1. DLT Entity ID — Register as a business entity on a DLT portal (e.g., Jio, Airtel, Vodafone-Idea)
2. DLT Template ID — Register your message templates for approval
3. Sender ID — Register your header/sender ID (e.g., "EXOTEL")

Without DLT registration, SMS to Indian numbers will be blocked by telecom operators.

What's Next?

• Send SMS — Full API Reference — All parameters, response fields, and error codes
• Bulk SMS — Send to Multiple Numbers — Send up to 100 messages per request
• SMS Delivery Status Codes — Understand delivery statuses
• Webhooks — Get Delivery Notifications — Real-time delivery updates
• Error Codes Reference — Troubleshoot common errors