v3 SMS HTTP
Note: If you're new to OpenMarket, then integrate with our Global SMS (version 4) operations.
Customers currently integrated using v3 may continue to use it, although we encourage customers to migrate to v4 in order to take advantage of new features. Please also note that there are no SDKs available for either version of the Global SMS API.
Our version 3 HTTP API supports the following operations:
- Send an SMS (v3) — Sends an SMS message of any supported type; e.g. text, binary or WAP Push.
- Query Message Status (v3)
- Receive an SMS Delivery Receipt (v3) — Our way to send you the final delivery status.
- Receive an SMS (v3) — Our way to send you an SMS from an end user.
- Mobile Operator Lookup (v3) — Retrieves information about the mobile phone, the mobile operator, and the phone's location.
Requests for version 3 should go to the following fully-qualified OpenMarket domain name:
When connecting, we strongly recommends using HTTPS over secure port 443. You'll need to use Transport Layer Security. For more information see Security and Authentication.
OpenMarket charge types
OpenMarket uses the notion of a charge type to distinguish between US and Canada standard rate and international rate messages. In a submit request, you'll include one of the following charge types:
- 0 — standard rate SMS
- 20 — international rate SMS
If you submit a request that does not specify a charge type, OpenMarket assumes the message is standard rate (charge type 0).
Receiving delivery receipts
Delivery receipts enable you to programmatically receive information about the final disposition of an MT message that you submitted through OpenMarket. Delivery receipts for international, US standard rate, and Canada standard rate messages include information about message delivery success or failure.
Note: If the message originator is a US or Canadian landline or long code then you will not receive delivery receipts.
If you wish to receive a delivery receipt, then you must include the delivery element in the submit request.
<delivery receipt_requested="true" url="https://myurl.com/delivery_receipts"/>
For a list of the possible delivery states, see Response and Delivery Receipt Codes for SMS Version 3 API.
Retrying failed MTs
OpenMarket can, on your behalf, retry MTs that fail with retryable error conditions. Automatic retry applies to MTs that fail with retryable error conditions after the MT is accepted by OpenMarket and a ticket ID is returned to your system. We can retry MTs for up to 24 hours or until the MT validity period expires, whichever comes first. OpenMarket returns a delivery receipt, if requested, after the maximum number of retries has been exhausted.
If you submit an MT with a carrier ID and the MT is rejected by the carrier with an invalid destination address error, OpenMarket will perform a carrier lookup to determine if a different carrier ID should be used to route the MT. If a different carrier ID for the destination address is found, OpenMarket will submit the MT to the new carrier and your account will be charged for the lookup.
When OpenMarket is retrying an MT, the message state is “Retrying” in the SMS Activity Search results on Customer Center.
By default, automatic retry is enabled on accounts for new customers. If you would like to disable or re-enable automatic retry on an existing account, contact your OpenMarket account manager.