> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hany.tools/llms.txt
> Use this file to discover all available pages before exploring further.

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

> POST /sms/send sends a single SMS to one recipient. Accepts to, from (Sender ID), and message. Returns message_id and credits_used.

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.

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

## Endpoint

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

## Request

```bash theme={null}
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

<ParamField body="to" type="string" required>
  Recipient phone number in E.164 format (e.g. `+233201234567`). Ghana numbers follow the pattern `+233XXXXXXXXX`.
</ParamField>

<ParamField body="from" type="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.
</ParamField>

<ParamField body="message" type="string" required>
  The SMS message body. Messages longer than 160 characters are automatically split into segments — each segment consumes 1 credit.
</ParamField>

<ParamField body="callback_url" type="string">
  An HTTPS URL to receive delivery status webhook events for this message. The URL must be publicly reachable.
</ParamField>

## Response

### 200 — Success

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

## Response Fields

<ResponseField name="status" type="string">
  Indicates the outcome of the request. Either `"success"` or `"error"`.
</ResponseField>

<ResponseField name="message_id" type="string">
  Unique identifier for this message. Use this value to query delivery status via the [Delivery Reports](/api-reference/sms/delivery-reports) endpoint.
</ResponseField>

<ResponseField name="to" type="string">
  The recipient phone number exactly as you provided it.
</ResponseField>

<ResponseField name="from" type="string">
  The Sender ID used for this message.
</ResponseField>

<ResponseField name="segments" type="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.
</ResponseField>

<ResponseField name="credits_used" type="integer">
  The number of credits consumed for this send. Equal to the number of segments.
</ResponseField>

<ResponseField name="credits_remaining" type="integer">
  Your account's remaining credit balance after this send.
</ResponseField>

## Error Responses

<Warning>
  Always inspect the `status` field. A non-2xx HTTP status code will accompany an error response body.
</Warning>

| 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

<CodeGroup>
  ```javascript JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>