Send a new SMS

POST /sms/message

application/json

Body Required

to array[string] Required

List of msisdns to whom the message is being sent
from string Required

The msisdn of the sender; this is who the recipient will see as the sender of the message
body string Required

Message contents to send

Maximum length is 2000.
send_at string(date-time)

When to send the message; default is to send now
expires_at string(date-time)

When the message should expire; any recipients not yet attempted will be abandoned (cannot be provided with ttl)
ttl string

Alternative to expires_at - number of seconds after the send_at time after which the message will be considered expired (cannot be provided with expires_at)
num_parts_max integer

Maximum number of message parts allowed; if the submitted message requires more than this many (due to length and/or required character encoding) then it will not be sent; an HTTP 200 response will be returned instead of the normal HTTP 201 for this method.
ref string

Client reference; this will be included in any callbacks

Maximum length is 80.
callbackURL string(uri)

URL that delivery reports should be sent to for this message; if not provided the account default will be used
delivery_report string
Delivery report type:
- summary - One report for the message, sent when all recipients have been attempted or expired; shows a summary of the number of delivered, failed, expired etc recipients
- details - One report for the message, sent when all recipients have been attempted or expired; shows statuses with a breakdown of recipients
- per_recipient_final - Single delivery report will be sent for each recipient when the status is final (eg "delivered", "expired", "rejected")
- per_recipient - Report per recipient is sent for each change of status (eg "sent" meaning that the message has been submitted to the SMSC and then the final status)
If not provided the account default will be used, if set to null delivery reports will be disabled for this message
Values are summary, detailed, per_recipient_final, or per_recipient.
paused boolean

Whether to submit the message in a paused state (will not be sent until released)

Default value is false.

Responses

200 application/json

Successful operation
Hide response attributes Show response attributes object
- num_parts integer
  
  The number of parts used to send the message
- num_parts_max integer
  
  The number of parts used to send the message
- info string
  
  Error message
201 application/json

Sms created
Hide response attributes Show response attributes object
- messageID integer
  
  The Id of the message
- num_parts integer
  
  The number of parts used to send the message
- num_recipients integer
  
  The number of recipients the message was sent to
400 application/json

Invalid input
Hide response attributes Show response attributes object
- status_code integer
  
  Status code 400
- status_msg string
  
  Error message text
- error string
  
  Validation error text
- type string
  
  Type of the validation error
- arguement string
  
  The arguement the validation error applies to
401 application/json

Unauthorized
Hide response attributes Show response attributes object
- status_code integer
  
  Status code 401
- status_msg string
  
  Error message text
403 application/json

Invalid input
Hide response attributes Show response attributes object
- status_code integer
  
  Status code 403
- status_msg string
  
  Error message text
- error string
  
  Validation error text
- type string
  
  Type of the validation error
- arguement string
  
  The arguement the error applies to
- bad_value string
  
  The value which the error is for
- info string
  
  additional information
404 application/json

Not Found
Hide response attributes Show response attributes object
- status_code integer
  
  Status code 404
- status_msg string
  
  Error message text
- info string
  
  Additional information
405 application/json

Method Not Allowed
Hide response attributes Show response attributes object
- status_code integer
  
  Status code 405
- status_msg string
  
  Error message text
- Allow array[string]
  
  HTTP Method

POST /sms/message

curl \
 -X POST https://sms.apicontrol.co.uk/v1/sms/message \
 -H "Authorization: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"to":["+447700900111","+447700900122"],"from":"+447700900001","body":"Message to send","send_at":"2024-06-03T10:05:22Z","expires_at":"2024-06-04T10:05:22Z","ttl":60,"num_parts_max":4,"ref":"d93b9ec9-4e0d-42b8-80c0-ef3036acdafc","callbackURL":"https://sms-callbacks.barbuck.com","delivery_report":"summary","paused":false}'

Request examples

{
  "to": [
    "+447700900111",
    "+447700900122"
  ],
  "from": "+447700900001",
  "body": "Message to send",
  "send_at": "2024-06-03T10:05:22Z",
  "expires_at": "2024-06-04T10:05:22Z",
  "ttl": 60,
  "num_parts_max": 4,
  "ref": "d93b9ec9-4e0d-42b8-80c0-ef3036acdafc",
  "callbackURL": "https://sms-callbacks.barbuck.com",
  "delivery_report": "summary",
  "paused": false
}

Response examples (200)

{
  "num_parts": 2,
  "num_parts_max": 1,
  "info": "Message not accepted because it would exceed the requested maximum number of message parts"
}

Response examples (201)

{
  "messageID": 923934,
  "num_parts": 1,
  "num_recipients": 2
}

Response examples (400)

{
  "status_code": 400,
  "status_msg": "Bad Request",
  "error": "Argument not supplied",
  "type": "ARG_MISSING",
  "arguement": "to"
}

Response examples (401)

{
  "status_code": 401,
  "status_msg": "Unauthorized"
}

Response examples (403)

{
  "status_code": 403,
  "status_msg": "Forbidden",
  "error": "Argument has disallowed value",
  "type": "VAL_ILLEGAL",
  "arguement": "from",
  "bad_value": "+443480047819",
  "info": "Number must be validated against your account"
}

Response examples (404)

{
  "status_code": 404,
  "status_msg": "Not Found",
  "info": "string"
}

Response examples (405)

{
  "status_code": 405,
  "status_msg": "Method Not Allowed",
  "Allow": [
    "POST"
  ]
}