# Send single or multi-recipient SMS
URL: /docs/api-reference/transactional-sms/sendSms

## POST `/api/v1/public/sms/send`

**Summary:** Send single or multi-recipient SMS
**Operation ID:** `sendSms`

Dispatches high-priority transactional SMS to 1-10 recipients. Supports test keys (`sk_test_...`) and magic numbers (`+233200000001` through `+233200000004`) for deterministic sandbox simulation without deducting wallet credits.

**Authentication:** `X-Api-Key: sk_live_...` or `Authorization: Bearer sk_live_...`

### Parameters

| Name | In | Required | Description |
| :--- | :--- | :--- | :--- |
| `Idempotency-Key` | `header` | No | Unique UUID or string for idempotent dispatch protection. Guarantees that a message is only sent once within a 24-hour window. |

### Request Body (`application/json`)

```json
{
  "type": "object",
  "required": [
    "message"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "Single recipient phone number in E.164 format",
      "example": "+233241234567"
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "description": "Multi-recipient list (1-10 phone numbers in E.164 format)",
      "example": [
        "+233241234567",
        "+233200000001"
      ]
    },
    "message": {
      "type": "string",
      "description": "Text content of the message",
      "example": "Your OTP verification code is 849201."
    },
    "senderId": {
      "type": "string",
      "maxLength": 11,
      "description": "Registered alphanumeric Sender ID (max 11 chars)",
      "example": "SMSPRO"
    },
    "scheduleAt": {
      "type": "string",
      "format": "date-time",
      "description": "Optional future timestamp to schedule delivery",
      "example": "2026-11-01T12:00:00Z"
    },
    "deliveryCallbackUrl": {
      "type": "string",
      "format": "uri",
      "description": "Webhook URL to receive signed delivery receipts",
      "example": "https://myapp.com/webhooks/dlr"
    }
  }
}
```

### Responses

- **`202`**: Message accepted and queued for carrier delivery or simulated in sandbox

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "example": "success"
    },
    "message": {
      "type": "string",
      "example": "Queued"
    },
    "data": {
      "type": "object",
      "properties": {
        "jobId": {
          "type": "string",
          "example": "job-d41d8cd9-8f00"
        },
        "messageIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "c7a8b9e0-1234-5678-9abc-def012345678"
          ]
        },
        "messageId": {
          "type": "string",
          "example": "c7a8b9e0-1234-5678-9abc-def012345678"
        },
        "status": {
          "type": "string",
          "example": "ACCEPTED"
        },
        "segmentCount": {
          "type": "integer",
          "example": 1
        },
        "totalUnits": {
          "type": "integer",
          "example": 1
        }
      }
    }
  }
}
```
- **`400`**: Invalid or malformed request syntax
- **`401`**: Authentication failed or API key missing
- **`403`**: API key lacks required scope (e.g. sms:send, mfa:write, balance:read)
- **`422`**: Validation error or invalid input parameters
- **`429`**: Rate limit exceeded for the API key