Send a Single SMS Message — POST /sms/send Endpoint

Use this endpoint to send a single SMS message to one recipient. You must provide a registered and approved Sender ID along with the recipient’s phone number in E.164 format.

All requests must include the Authorization: Bearer YOUR_API_KEY header. Requests and responses use Content-Type: application/json.

Endpoint

POST https://api.hany.tools/v1/sms/send

Request

curl -X POST https://api.hany.tools/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233XXXXXXXXX",
    "from": "YourBrand",
    "message": "Hello! Your appointment is confirmed for tomorrow at 10am.",
    "callback_url": "https://yourapp.com/webhooks/sms"
  }'

Request Body Parameters

string

required

Recipient phone number in E.164 format (e.g. +233201234567). Ghana numbers follow the pattern +233XXXXXXXXX.

string

required

Your registered and approved Sender ID. Maximum 11 alphanumeric characters. The Sender ID must have status: "approved" before you can use it to send messages.

string

required

The SMS message body. Messages longer than 160 characters are automatically split into segments — each segment consumes 1 credit.

string

An HTTPS URL to receive delivery status webhook events for this message. The URL must be publicly reachable.

Response

200 — Success

{
  "status": "success",
  "message_id": "msg_abc123xyz",
  "to": "+233XXXXXXXXX",
  "from": "YourBrand",
  "segments": 1,
  "credits_used": 1,
  "credits_remaining": 4999
}

Response Fields

string

Indicates the outcome of the request. Either "success" or "error".

string

Unique identifier for this message. Use this value to query delivery status via the Delivery Reports endpoint.

string

The recipient phone number exactly as you provided it.

string

The Sender ID used for this message.

integer

The number of SMS segments the message was split into. Messages up to 160 characters use 1 segment; longer messages are split into 153-character segments.

integer

The number of credits consumed for this send. Equal to the number of segments.

integer

Your account’s remaining credit balance after this send.

Error Responses

Always inspect the status field. A non-2xx HTTP status code will accompany an error response body.

HTTP Status	Error Code	Description
`401`	`unauthorized`	Your API key is missing, invalid, or revoked.
`400`	`invalid_recipient`	The `to` number is not a valid E.164 phone number.
`400`	`invalid_sender_id`	The `from` Sender ID is not registered or is not yet approved.
`422`	`insufficient_credits`	Your account does not have enough credits to send this message.

Code Examples

const response = await fetch("https://api.hany.tools/v1/sms/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+233201234567",
    from: "YourBrand",
    message: "Hello! Your appointment is confirmed for tomorrow at 10am.",
    callback_url: "https://yourapp.com/webhooks/sms",
  }),
});

const data = await response.json();
console.log(data.message_id);  // "msg_abc123xyz"
console.log(data.credits_remaining);  // 4999

import requests

response = requests.post(
    "https://api.hany.tools/v1/sms/send",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "to": "+233201234567",
        "from": "YourBrand",
        "message": "Hello! Your appointment is confirmed for tomorrow at 10am.",
        "callback_url": "https://yourapp.com/webhooks/sms",
    },
)

data = response.json()
print(data["message_id"])       # "msg_abc123xyz"
print(data["credits_remaining"])  # 4999

Overview

SMS

Webhooks

Send a Single SMS Message — POST /sms/send Endpoint

Endpoint

Request

Request Body Parameters

Response

200 — Success

Response Fields

Error Responses

Code Examples

​Endpoint

​Request

​Request Body Parameters

​Response

​200 — Success

​Response Fields

​Error Responses

​Code Examples

Endpoint

Request

Request Body Parameters

Response

200 — Success

Response Fields

Error Responses

Code Examples