You can take advantage of IO Phone programmatically through our API version 6 and above. While texting plans are unlimited, we do throttle and have limits in place on an account level (regardless of location or phone number) for billable outbound messages to prevent abuse whether intentional or accidental. Additionally our API has rate limiting of 300 requests every 300 seconds. Texting limits are 200/hour, 300/day, 1500/week. If the limit is hit, you may still send manual text messages, including through the API but not via an automation, at the rate of 1 message every 5 minutes. Certain system text messages sent on your behalf such as wind alerts are unbillable and are not counted in these limits.

Base URL: https://rental.software/api6
Required query parameters: apiKey

POST /text

Request Body Parameters

toNumber string required
- The phone number the message should be sent to
- E.164 format is recommended but not required
text string required
- The contents of the text message
- Must be 2048 characters or less
fromNumber string
- One of your IO Phone numbers that the message should be sent from
- E.164 format is recommended but not required
- If omitted, an IO Phone number of yours will be chosen automatically
callbackUrl string
- The URL where webhook requests will be sent
- http or https is required; https (TLS) is highly recommended
- The most recent callback URL that you’ve sent is stored on our server (one per fromNumber)
- If omitted, the most recent callback URL associated with fromNumber will be used
- The callback URL can be cleared from our server by sending it to us as an empty string ("")
- If a callback URL has never been specified or was cleared for a given fromNumber, webhooks will not be sent
country string default "US"
- Optional country code with which to force toNumber to be parsed, in ISO 3166-1 alpha-2 format
- It’s recommended to only specify this parameter if toNumber’s country of origin is known and its format is nonstandard or unknown
customKey string
- An optional custom string value that, when specified, will be returned in the subsequent outbound message webhook response
- This can be useful for tracking purposes
- Must be 32 characters or less
media string
- An optional array of string values representing URLs that, when specified, will be included as media attachments as part of the message (MMS)
- Each URL must not exceed 4096 characters

Response Schema

Blue indicates properties that are only sent when the message is accepted

Red indicates properties that are only sent when the message fails

id integer
- The unique ID associated with the message
time string
- The UTC timestamp of the message, in ISO 8601 format
segmentCount integer
- The number of segments that the message was broken into before sending over to carrier networks
direction string
- The direction of the message, either in or out
to string
- The phone number the message was sent to, in E.164 format
from string
- The phone number the message was sent from, in E.164 format
text string
- The text message content that was sent to the recipient
media array
- The list of URLs that were sent along to the recipient as media attachments (if specified in the request)
status integer
- The status code associated with the request
- If the message was accepted, 202 should be expected
- Errors will return a status code >= 400 and <= 599
message string
- A message describing the error

Example Request

POST https://rental.software/api6/text?apiKey=XXXX

Content-Type: application/json
{
"toNumber": "+15554447777",
"fromNumber": "+15551112222",
"text": "Hello world",
"callbackUrl": "https://my-callback-url/path",
"media": ["https://my-server/image.jpg"]
}

Example Responses

Successful response example

200 OK
Content-Type: application/json
{
"id": 1753065,
"time": "2023-09-14T17:28:18.709287Z",
"segmentCount": 1,
"direction": "out",
"to": "+15554447777",
"from": "+15551112222",
"text": "Hello world",
"status": 202,
"media": ["https://my-server/image.jpg"],
"request_time": 1694712498
}

Error response examples

400 Bad Request
Content-Type: application/json
{
"status": 400,
"message": "Required parameter 'text' cannot be empty"
}

403 Forbidden
Content-Type: application/json
{
"status": 403,
"message": "This account is not authorized to send text messages from this number ('fromNumber')"
}

Webhook Response Examples

POST {YOUR_CALLBACK_URL}

Content-Type: application/json

Outbound message delivery receipt

{
"id": 1753064,
"time": "2023-09-14T15:59:38.406172698Z",
"type": "message-delivered",
"description": "Message delivered to carrier.",
"segmentCount": 1,
"direction": "out",
"to": "+15554447777",
"from": "+15551112222",
"text": "Hello world",
"customKey": "custom string",
"media": ["https://rental.software/your-outbound-hosted-image.jpg"]
}

Inbound message received

{
"id": 1753060,
"time": "2023-09-14T13:52:27.881412Z",
"type": "message-received",
"description": "Incoming message received",
"segmentCount": 1,
"direction": "in",
"to": "+15551112222",
"from": "+15554447777",
"text": "Hello world",
"media": ["https://rental.software/inbound-hosted-image.jpg"]
}

Outbound message failure

{
"id": 1753063,
"time": "2023-09-14T17:56:57.406573455Z",
"type": "message-failed",
"description": "invalid-destination-address",
"segmentCount": 0,
"direction": "out",
"to": "+15554447777",
"from": "+15551112222",
"errorCode": 4720,
"text": "Hello world",
"customKey": "custom string"
}

Testing

You can test sending through the API by using a from Number of (999) 999-9999. Test SMS messages are not sent but we simulate as if they are and will also initiate a send to your call back URL if you have specified one. See the example send and call back below.

Send

{
    "id": 5553,
    "time": "2023-09-18T15:49:43.052Z",
    "segmentCount": 1,
    "direction": "out",
    "to": "+15554447777",
    "from": "+19999999999",
    "text": "API Test Request",
    "status": 202,
    "request_time": 1695066583
}

Call Back

{
    "id": 5553,
    "time": "2023-09-18T15:49:43.052Z",
    "type": "message-delivered",
    "description": "Message delivered to carrier.",
    "segmentCount": 1,
    "direction": "out",
    "to": "+15554447777",
    "from": "+19999999999",
    "text": "API Test Request"
}

API - SMS, Text Message Sending and Recieving