Skip to main content
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

​
to
string
required
Recipient phone number in E.164 format (e.g. +233201234567). Ghana numbers follow the pattern +233XXXXXXXXX.
​
from
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.
​
message
string
required
The SMS message body. Messages longer than 160 characters are automatically split into segments — each segment consumes 1 credit.
​
callback_url
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

​
status
string
Indicates the outcome of the request. Either "success" or "error".
​
message_id
string
Unique identifier for this message. Use this value to query delivery status via the Delivery Reports endpoint.
​
to
string
The recipient phone number exactly as you provided it.
​
from
string
The Sender ID used for this message.
​
segments
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.
​
credits_used
integer
The number of credits consumed for this send. Equal to the number of segments.
​
credits_remaining
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 StatusError CodeDescription
401unauthorizedYour API key is missing, invalid, or revoked.
400invalid_recipientThe to number is not a valid E.164 phone number.
400invalid_sender_idThe from Sender ID is not registered or is not yet approved.
422insufficient_creditsYour 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