Send an SMS

Sends one SMS to one mobile number. The response gives you a reference you can use to get the message and check its status.

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

Request

Path parameters

Parameter	Description
`authKey`	Your API key. See Authentication.

Headers

Header	Value
`Content-Type`	`application/json`

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.
`from`	string	No	The sender ID 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.
`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.

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

Example request

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

With curl:

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.

{
  "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`.

A 200 means the message was accepted, not that it was delivered. Use Get an 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.
`401`	(empty)	The API key is missing or not recognised.
`429`	(empty)	Rate limit exceeded. See Rate limits.
`500`	`A server error occurred`	A problem on our side. Retry later.

Example 400 response:

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.
Sender IDs and replies. Recipients can’t reply to a branded sender ID. To receive replies, send from a reply number instead. See Replies.
Opt-outs. Numbers on your account’s stop list are not sent to. See 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.