Sending to the US and Canada

This page provides the request values you'll need to use for US and Canadian messaging and gives examples of message requests.

Help with US and Canadian requirements

Running services in the US and Canada means complying with certain laws, industry guidelines and mobile operator policies. However, it can be challenging to stay compliant with guidelines and policies that are continually evolving. That's why we've provided some guides for different aspects of US and Canadian message:

Types of message originators you can use

In the US and Canada, you can use the following message originators:

  • Short codes
  • Virtual mobile numbers (VMNs)
  • Toll-free numbers
  • Landline numbers

For a list of the mobile operators that support text-enabled landlines and toll-free numbers, see Mobile Operator IDs.

Program briefs

US messaging requires you to provision message originators and provide the mobile operators with a program brief. Your OpenMarket account manager can assist with these tasks.

Once you're provisioned, your message requests sent with a US short code require programId in the request. However, you don't need to include this if the originator is a Canadian short code or any other US or Canadian originator type.

When should I include the mobileOperatorId?

You should include the mobileOperatorId — if you know it — in request from a short code or toll-free number. If you do not include this, we will perform an operator lookup. Depending on your contract with OpenMarket, you may be charged for each operator lookup.

For other message originators, you do not need to include the mobileOperatorId. We perform a dynamic lookup, which you are not charged for.

Including interaction

You do not need to include interaction in your requests, as all US and Canada messaging is two-way by default.

Receiving delivery receipts and MO messages for different originators

There are a couple of differences in what you may receive from OpenMarket based on the message originator:

  • MO messages — OpenMarket tells you the end user's mobile operator when the message is to a short code, toll-free number or landline number. However, for VMNs we do not provide the operator; instead the mobile operator ID sent is zero (0).
  • Delivery receipts — Messages sent using short codes can receive a wide range of delivery receipt codes, as the mobile operators provide us with a range of error descriptions for short code messaging. However, for other US message originators, you'll receive a subset of these codes that indicate both successful and failed messaging. Once the message has been forwarded to the mobile operator, we can only return a zero (0) code, which indicates that the message was successfully delivered to the mobile operator.

Example message requests

Example using a short code

In this example, a short code is the source address. You must set a value programId. You can also optionally set a value for mobileOperatorId.

JSON request

{
   "mobileTerminate" : {
      "options": {
         "programId": "1234"
      },
      "destination": {
         "address": "12515550100",
         "mobileOperatorId": 383
      },
      "source": {
         "ton": 3,
         "address": "222111"
      },
      "message": {
         "content": "This is a text message!",
         "type": "text"
      },
      "delivery": {
         "receiptRequested": "final",
         "url": "https:my.example.com/receiver.php"
      }
   }
}

XML request

<?xml version="1.0" encoding="UTF-8"?>
<mobileTerminate>
   <options programId="1234" />
   <destination address="12515550100" mobileOperatorId="383" />
   <source ton="3" address="222111" />
   <message type="text">
      <content>This is a text message!</content>
   </message>
   <delivery receiptRequested="final" url="https:my.example.com/receiver.php" />
</mobileTerminate>

Example using a landline or toll-free number

In this example, a toll-free number is the source address. For a toll-free number, you can also optionally set a value for mobileOperatorId. If your source address is a landline number, exclude mobileOperatorId.

JSON request

{
"mobileTerminate" : {
      "destination": {
         "address": "12515550100",
         "mobileOperatorId": 383
      },
      "source": {
         "ton": 1,
         "address": "18772772801"
      },
      "message": {
         "content": "This is a text message!",
         "type": "text"
      },
      "delivery": {
         "receiptRequested": "final",
         "url": "https:my.example.com/receiver.php"
      }
   }
}

XML request

<?xml version="1.0" encoding="UTF-8"?>
<mobileTerminate>
   <destination address="12515550100" mobileOperatorId="383" />
   <source ton="1" address="18772772801" />
   <message type="text">
      <content>This is a text message!</content>
   </message>
   <delivery receiptRequested="final" url="https:my.example.com/receiver.php" />
</mobileTerminate>

Example using a VMN

In this example, a toll-free number is the source address. For VMNs, you do not need to include any values specific to US or Canadian messaging.

JSON request

{
   "mobileTerminate" : {
      "destination": {
         "address": "12515550100"
      },
      "source": {
         "ton": 1,
         "address": "12515550145"
      },
      "message": {
         "content": "This is a text message!",
         "type": "text"
      },
      "delivery": {
         "receiptRequested": "final",
         "url": "https:my.example.com/receiver.php"
      }
   }
}

XML request

<?xml version="1.0" encoding="UTF-8"?>
<mobileTerminate>
   <destination address="12515550100" />
   <source ton="1" address="12515550145" />
   <message type="text">
      <content>This is a text message!</content>
   </message>
   <delivery receiptRequested="final" url="https:my.example.com/receiver.php" />
</mobileTerminate>