# Send an SMS

Sends one SMS to one mobile number. The response gives you a reference you can use to [get the message](/docs/api/get-sms/) and check its status.

```text
POST https://api.diarybook.com/{authKey}/v2/sms
```

## Request

### Path parameters

| Parameter | Description |
|-----------|-------------|
| `authKey` | Your API key. See [Authentication](/docs/api/http-api/#authentication). |
{.table}

### Headers

| Header | Value |
|--------|-------|
| `Content-Type` | `application/json` |
{.table}

### Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `to` | string | Yes | The recipient's mobile number, in international format, for example `+353871234567`. |
| `text` | string | Yes | The message text. Long messages are sent as several parts; see [SMS message parts](/docs/reference/sms-message-parts/). |
| `from` | string | No | The [sender ID](/docs/sender-ids/about-sender-ids/) to send from. It must be approved on your account. Leave it out to use your account's default sender. |
| `senderRef` | string | No | Your own reference for the message, up to 40 characters, such as an order or ticket number. You can use it in place of our reference to [get the message](/docs/api/get-sms/). |
| `category` | string | No | A billing category, up to 25 characters, for grouping costs in your reports. |
| `clientRef` | string | No | A reference for the person or record the message is about in your system, up to 40 characters. |
{.table}

Empty strings in `senderRef` and `category` are treated as not supplied.

### Example request

```json
{
  "to": "+353871234567",
  "from": "MYCOMPANY",
  "text": "Your order 10482 has been dispatched and will arrive tomorrow.",
  "senderRef": "ORDER-10482",
  "category": "Dispatch"
}
```

With curl:

```bash
curl -X POST "https://api.diarybook.com/YOUR_API_KEY/v2/sms" \
  -H "Content-Type: application/json" \
  -d '{
        "to": "+353871234567",
        "from": "MYCOMPANY",
        "text": "Your order 10482 has been dispatched and will arrive tomorrow.",
        "senderRef": "ORDER-10482",
        "category": "Dispatch"
      }'
```

## Response

### 200 OK

The message has been accepted and queued for sending.

```json
{
  "reference": "msg_sms_Xk3pR9bTq2LmZa7vN4wY",
  "links": [
    {
      "href": "https://api.diarybook.com/YOUR_API_KEY/v2/sms/msg_sms_Xk3pR9bTq2LmZa7vN4wY",
      "rel": "self"
    },
    {
      "href": "https://api.diarybook.com/YOUR_API_KEY/v2/sms/ORDER-10482",
      "rel": "self"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `reference` | string | Our unique reference for the message, beginning `msg_sms_`. Store it to look the message up later. |
| `links` | array | Links for retrieving the message. The first uses `reference`. A second is included when you supplied a `senderRef`. |
{.table}

A `200` means the message was accepted, not that it was delivered. Use [Get an SMS](/docs/api/get-sms/) to follow its status.

### Errors

| Status | Body | Cause |
|--------|------|-------|
| `400` | `No message details given` | The request body is missing or isn't valid JSON. |
| `400` | `No message body` | `text` is missing or empty. |
| `400` | `No mobile number` | `to` is missing or empty. |
| `400` | `Error[9101]: ...` | The message was rejected, for example an invalid value. The number is a [status code](/docs/reference/sms-status-codes/). |
| `401` | *(empty)* | The API key is missing or not recognised. |
| `429` | *(empty)* | Rate limit exceeded. See [Rate limits](/docs/api/http-api/#rate-limits). |
| `500` | `A server error occurred` | A problem on our side. Retry later. |
{.table}

Example `400` response:

```text
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

No mobile number
```

## Things to know

- **Cost.** Each message part is charged to your account at the rate for the destination country. The price is shown when you [get the message](/docs/api/get-sms/).
- **Sender IDs and replies.** Recipients can't reply to a branded sender ID. To receive replies, send from a reply number instead. See [Replies](/docs/replies-and-reports/replies/).
- **Opt-outs.** Numbers on your account's stop list are not sent to. See [Opt-outs](/docs/reference/opt-outs/).
- **Characters.** A message containing characters outside the GSM 7-bit alphabet, such as emoji, is sent as Unicode and holds fewer characters per part. See [SMS message parts](/docs/reference/sms-message-parts/).

## Related

- [DiaryBook API overview](/docs/api/http-api/)
- [Get an SMS](/docs/api/get-sms/)
- [About sender IDs](/docs/sender-ids/about-sender-ids/)
- [Status and error codes](/docs/reference/sms-status-codes/)

---
Source: https://iflow.net/docs/api/send-sms/