Send SMS

POST

Send a single SMS message to a recipient. Supports E.164 phone number format, custom sender IDs, and idempotency to prevent duplicate sends.

Endpoint

POST

https://api.smsgateway.com/api/v1/sms/send

Request Headers

Header	Required	Description
Authorization	Required	Bearer token API key. Format: `Bearer sg_live_xxx`
Content-Type	Required	Must be `application/json`
Idempotency-Key	Optional	Unique key to prevent duplicate sends. Valid for 24 hours.

Request Body

Parameter	Type	Required	Description
to	string	Required	Recipient phone number in E.164 format. Minimum 7 characters. Example: `+251911234567`
body	string	Required	Message body. Maximum 1,600 characters. Longer messages are automatically segmented.
senderId	string	Optional	Approved sender ID (alphanumeric, max 15 characters). Must be pre-approved by the administrator.
idempotencyKey	string	Optional	Unique key to prevent duplicate sends within 24 hours. Can also be passed as a header.

Examples

Send SMS with cURL

1curl -X POST https://api.smsgateway.com/api/v1/sms/send \
2  -H "Authorization: Bearer sg_live_xxxxxxxxxxxx" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "to": "+251911234567",
6    "body": "Hello from SMS Gateway!"
7  }'

Response

Success (201 Created)

Success response

1{
2  "success": true,
3  "data": {
4    "messageId": "msg_8f2k3j4h5g6d1a0b",
5    "status": "QUEUED",
6    "to": "+251911234567",
7    "from": "MyApp",
8    "segments": 1,
9    "cost": 0.02,
10    "isOtp": false,
11    "isSandbox": false,
12    "createdAt": "2026-07-20T14:30:00.000Z"
13  }
14}

Error Responses

400

Bad Request

The request body is missing required fields or contains invalid data.

json

1{
2  "success": false,
3  "error": {
4    "code": "VALIDATION_ERROR",
5    "message": "Invalid phone number format. Use E.164 format (e.g., +251911234567)."
6  }
7}

401

Unauthorized

The API key is missing, invalid, or has been revoked.

json

1{
2  "success": false,
3  "error": {
4    "code": "UNAUTHORIZED",
5    "message": "Invalid or expired API key."
6  }
7}

402

Payment Required

The organization has insufficient balance or no active billing plan.

json

1{
2  "success": false,
3  "error": {
4    "code": "INSUFFICIENT_BALANCE",
5    "message": "Your account balance is insufficient to send this message. Please top up your balance."
6  }
7}

429

Rate Limited

Too many requests. The send endpoint is limited to 100 requests per minute per organization.

json

1{
2  "success": false,
3  "error": {
4    "code": "RATE_LIMITED",
5    "message": "Rate limit exceeded. Try again in 32 seconds.",
6    "retryAfter": 32
7  }
8}

Rate Limits

100 requests per minute

Per organization. The rate limit resets every 60 seconds. Check the X-RateLimit-Reset header for the exact reset time.