The Arnio API follows REST principles. You can use it to send outbound iMessages globally.
Supported Endpoints
- Single message: POST /send-message
- Group message: POST /send-group-message
Sending Files
You can send media by including the media_url parameter.
- The URL must point to a publicly accessible image or .caf (for voice notes).
- File size is capped at 5MB.
- Signed URLs are not supported; use Arnio’s media object pattern for secure uploads.
Learn more here: https://docs.arnio.co/api-reference/endpoint/send-message
Status Callbacks
Arnio will POST to your status_callback endpoint when a message’s status changes.
Possible statuses:
- QUEUED
- SENT
- DELIVERED (iMessage only)
- READ (iMessage only)
- FAILED
You must respond to Arnio’s webhook to prevent duplicate notifications.
{
"accountEmail": "support@arnio.co",
"content": "Hello world!",
"is_outbound": true,
"status": "DELIVERED",
"error_code": null,
"error_message": null,
"message_handle": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
"date_sent": "2025-09-10T06:15:05.962Z",
"date_updated": "2025-09-10T06:15:14.115Z",
"from_number": "+15122164639",
"number": "+19998887777",
"to_number": "+19998887777",
"was_downgraded": false,
"plan": "enterprise"
}
Note: Your server must return a response to Arnio’s callback to prevent duplicate webhook deliveries.
Callback Body Fields
| Field | Type | Description |
|---|
| accountEmail | string | Associated Arnio account email |
| content | string | Message content |
| is_outbound | boolean | true if sent by your system, false if received from end user |
| media_url | string | A CDN link to any attached media |
| status | string | Current status of the message |
| error_code | int | Error code if the message failed, null otherwise |
| error_message | string | Human-readable error description |
| message_handle | string | Unique Arnio message handle (used to query message status later) |
| date_sent | string | ISO 8601 timestamp of when the message was created |
| date_updated | string | ISO 8601 timestamp of the last status update |
| from_number | string | E.164-formatted Arnio phone number used to send the message |
| number | string | E.164-formatted number of the end user (your contact) |
| to_number | string | E.164-formatted number of the intended recipient |
| was_downgraded | boolean | true if iMessage was unavailable and SMS was used instead |
| plan | string | Arnio account plan associated with the request |
Message Status Values
| Status | Description |
|---|
| QUEUED | Message has been validated and queued for delivery |
| SENT | Message was sent from Arnio’s servers |
| DELIVERED | Delivery confirmed (iMessage only) |
| READ | End user has read the message (iMessage only) |
| FAILED | Message failed to send (see error_code and error_message for details) |
Limits
Messages sent through the Arnio API must be fewer than 18,996 characters in length. For longer content, we recommend splitting it into multiple, smaller messages to ensure reliable delivery.
From Number
CAUTION: Arnio prioritizes deliverability and end-user experience. Each of your customers will consistently interact with your brand through one dedicated Arnio phone number, ensuring continuity and trust.
- Track which number was used to send a given message.
- Inform customers which number they should expect messages from.
Handle
Every message processed by Arnio includes a unique message_handle. You can use this handle to:
- Query the current status of a message.
- Track messages in high-volume campaigns.
- Resolve situations where a message remains QUEUED or times out.
