Send SMS
Purpose
Sends an SMS message to the SIM specified in the <iccid> element.
This command allows applications to transmit SMS messages directly to mobile devices.
This function is not available for Open-User-Group SIM types (e.g. MultiNET KPN-O).
Endpoint
POST https://api.m2miportal.com
Content-Type: application/xml
Accept: application/xml
Request (XML)
<send-sms version="1" api-id="123456">
<authentication>
<username>username</username>
<password>password</password>
</authentication>
<iccid>1234567890123456789</iccid>
<message-text>Let’s meet at the station</message-text>
<data-coding>default</data-coding>
<origin>447890123456</origin>
<sms-uid>123abcde4567</sms-uid>
</send-sms>Response (Success)
<send-sms-response api-id="123456">
<api-outcome>Success</api-outcome>
</send-sms-response>Request Elements
Element | Required | Description |
|---|---|---|
<iccid> | Yes | Target SIM ICCID. |
<message-text> | Yes | SMS message content. Maximum 160 characters. |
<data-coding> | No | Encoding type. Default is default. |
<origin> | No | Custom origination number (Manx Telecom SIMs only). |
<sms-uid> | No | Client-defined unique identifier (max 12 alphanumeric characters). |
Message Length Rules
- Maximum length: 160 characters
- Messages longer than 160 characters will return Invalid Content
- Characters must conform to the GSM 7-bit default alphabet (3GPP TS 23.038)
- Characters from the GSM 7-bit extension table count as two characters
- Other character sets may produce unpredictable results
Origination Number (<origin>)
If <origin> is:
- Omitted → An appropriate origination number is used and replies will route back to the SIM Insight platform.
- Specified (Manx Telecom SIMs only) → Replies will not be directed to the SIM Insight platform and will not be available via the SMS Log or API.
- Specified for other SIM types → The element will be ignored.
Binary SMS (MultiNET KPN-C Only)
For SIM type MultiNET KPN-C, the <data-coding> element may be set to:
In this case:
- Message must be encoded as Base64
- Maximum <message-text> length remains 160 characters
- Maximum binary payload size is 120 bytes
- Binary encoded SMS MO is not supported
Example
Binary values:
Base64 encoded:
Request elements:
SMS User ID (<sms-uid>)
The optional <sms-uid>:
- Maximum 12 alphanumeric characters
- Must be unique (client responsibility)
- Will be included in delivery receipt information
- Allows cross-referencing of messages
Delivery Behaviour
- If a device is unavailable, messages are queued and retried
- Retry period is a minimum of 72 hours
- Delivery status can be retrieved via SMS Log or API
- Some operators impose queue limits (e.g. KPN: 60 messages per SIM)
- If the operator queue limit is exceeded, the API response will be:
Operational Notes
- SMS can only be delivered to Active SIMs.
- SMS availability depends on SIM type and operator support.
- Delivery is not guaranteed and may be asynchronous.
- Operator limits may result in message rejection.
Response (Failure)
If a request cannot be processed, the response will include:
- api-outcome indicating failure
- An error description explaining the reason
Failure responses may occur due to:
- Invalid authentication credentials
- Invalid or unknown identifiers (for example ICCID or MSISDN)
- Invalid or missing parameters
- Values not permitted for the specified SIM type or account configuration
- Insufficient permissions
Integrating systems should validate input data before submission and implement appropriate error handling and logging.