SMS

Queue an outgoing SMS

Use this method to queue SMS messages. Can be used to send the same message body to multiple recipients.

Schemas

Request

Name	Type	Description
to	Array:String(format:e164)	Array of recipient phone numbers inclusive of country code. Numbers must be in E.164 format (eg +17055551234). Note: Multiple recipient numbers will results in multiple messages
body	String(1..4096)	The SMS body. Depending on the quantity and type of characters in the body, a single SMS may be split into multiple segments, incurring a charge for each.
from	String(format:e164)	The sender number or address on your account that the message should originate from. If set to null or not present, a random number from the account will be used instead. Numbers must include the country code and be in E.164 format (eg +17055551234).
id	String	Any user-supplied ID string. Does not need to be unique, however it will only be used for tagging purposes and is not generally available for lookup. Users may provide this ID, or the response’s ID for inquiries or support.
request_dlr	Boolean	Whether or not a DLR should be requested. Note: some carriers may not return a DLR.
expires_at	String(format:date-time)	An ISO8601 timestamp denoting when the message should be considered expired and abort sending. Expired messages will not refund the cost of processing the message, even if it is never sent.
encode_as	Integer	Optional. Allows the encoding of the message body to be specified. Only for specific use cases and generally should be omitted. Defaults to 0 (GSM 7-bit). See encoding for supported types.

Response

Name	Type	Description
results	Array:Object	Array of result objects, one for each recipient
results[].direction	String	Direction of the message, “OUTBOUND” for sent messages
results[].error_code	String	Status code of the operation, “OK” for success or an error code.
results[].expires_at	String(format:date-time)	ISO8601 timestamp when the message expires
results[].from	String(format:e164)	The sender phone number
results[].id	String	Unique identifier for the message
results[].origin_id	String	User-supplied ID passed in the request
results[].parts	Array:Object	Array of message parts
results[].parts[].id	String	Unique identifier for the message part
results[].schedule_at	String(format:date-time)	ISO8601 timestamp when the message is scheduled to be sent
results[].status	String	Current status of the message
results[].timestamp	String(format:date-time)	ISO8601 timestamp of when the message was processed
results[].to	String(format:e164)	The recipient phone number
results[].type	String	The message type, “SMS” for text messages
results[].encoding	Integer	The encoding of the message body

Examples

Successful request

Everything is correct and functioning as expected.

Request:

POST: https://sms.swift-api.com/v1/sms
Content-Type: application/json
Authorization: Bearer ABC123

{
  "body": "Hello, World",
  "expires_at": "2024-06-14T00:00:00.000000Z",
  "from": "12003004000",
  "id": "my-sms-id-1",
  "request_dlr": true,
  "to": [
    "12003004001"
  ]
}

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 527

{
  "results": [
    {
      "direction": "OUTBOUND",
      "error_code": "OK",
      "expires_at": "2024-06-14T00:00:00.000000Z",
      "from": "12003004000",
      "id": "01JDQ02MQ543RTQBT08WY88589",
      "origin_id": "my-sms-id-1",
      "parts": [
        {
          "id": "01JDQ02H94HEWKPK0VMJPY9N3H"
        }
      ],
      "schedule_at": "2024-06-14T00:00:00.000000Z",
      "status": "NEW",
      "timestamp": "2024-06-14T00:00:00.000000Z",
      "to": "12003004001",
      "type": "SMS"
    }
  ]
}

Errored request

Occurs when there’s an issue with the request. Refer to the error_code field for details. A list of possible error codes can be found here.

HTTP/1.1 422
Content-Type: application/json
Content-Length: 527

{
  "results": [
    {
      "direction": "OUTBOUND",
      "error_code": "ACCOUNT_SMS_DISABLED",
      "expires_at": "2024-06-14T00:00:00.000000Z",
      "from": "12003004000",
      "id": "01JDQ02MQ543RTQBT08WY88589",
      "origin_id": "my-sms-id-1",
      "parts": [
        {
          "id": "01JDQ02H94HEWKPK0VMJPY9N3H"
        }
      ],
      "schedule_at": "2024-06-14T00:00:00.000000Z",
      "status": "NEW",
      "timestamp": "2024-06-14T00:00:00.000000Z",
      "to": "12003004001",
      "type": "SMS"
    }
  ]
}

Partial success

Occurs when there are successes and failures in the request.

HTTP/1.1 207
Content-Type: application/json
Content-Length: 527

{
  "results": [
    {
      "direction": "OUTBOUND",
      "error_code": "ACCOUNT_SMS_DISABLED",
      "expires_at": "2024-06-14T00:00:00.000000Z",
      "from": "12003004000",
      "id": "01JDQ02MQ543RTQBT08WY88589",
      "origin_id": "my-sms-id-1",
      "parts": [
        {
          "id": "01JDQ02H94HEWKPK0VMJPY9N3H"
        }
      ],
      "schedule_at": "2024-06-14T00:00:00.000000Z",
      "status": "NEW",
      "timestamp": "2024-06-14T00:00:00.000000Z",
      "to": "12003004001",
      "type": "SMS"
    }
  ]
}