Sending & receiving messages

How should I format my phone numbers?

It's best to use E.164 format whenever possible. An E.164 number has three parts:

• The prefix "+"

• A 1-3 digit country code

• A subscriber number

For example, the numbers [phone], [phone] and [phone] can be broken down as follows:

Prefix	Country code	Subscriber number
+	55 (Brazil)	11 91234 5678
+	44 (UK)	7712 345678
+	1 (US/Canada)	555 883 8530

If you're texting in the U.S. or Canada, you can just send a 10 digit phone number with area code instead of E.164 format. We also parse phone numbers from string inputs like [phone].

I'm using E.164 format but it's rejecting my number. What's wrong?

One common pitfall is that if you're sending a "+" sign in POST data, it must be URL encoded. Otherwise, the plus sign will be stripped or converted to a space when it's sent to the server.

The process for encoding a URL will vary based on language and library support. Most HTTP libraries will handle encoding for you. If you need help, please contact us.

Which carriers/countries are supported?

We support SMS destinations for 221 countries around the world. Our services are most commonly used in the U.S., Canada, European countries (UK, France, Germany, Spain, etc), South Korea, Taiwan, Brazil, India, and Mexico.

You can always try sending a text to your foreign number using the free textbelt key to determine if it's already supported. Or, email us and let us know what country you're in - we'd be happy to help.

How do I send a text internationally?

By default, texts are sent in the U.S. (country code +1). To text internationally, append the country code to your phone number.

Use the E.164 format. For example, to text someone in France (country code +33), set the number param to [phone].

How do I send texts from a specific phone number?

Textbelt SMS are sent from a very large shared pool of phone numbers. Whenever possible, our service makes sure that you are represented to your recipients as a single unique phone number.

This allows us to keep the API and service very straightforward. If you are doing a large volume of SMS, you can request a dedicated phone number or pool of phone numbers at no additional charge.

Is there a way to send multiple texts at the same time?

No. You should send multiple HTTP requests in order to send multiple texts.

Is there any rate limiting?

You shouldn't send more than 1-2 SMS per second. There isn't strict rate limiting and the API won't cut you off, but you're advised to not exceed this limit as it could impact delivery on the mobile carrier side.

How are long texts handled?

Texts up to a certain length (as of writing, 256 bytes) are automatically broken into segmented texts. Text segment length can vary based on carrier but is usually 120. If a long text is broken up into segments, it is delivered to the recipient as multiple texts. You will be charged for the number of individual SMS messages sent to the carrier.

Why was my text counted as multiple texts?

Textbelt quota corresponds to the number of SMS segments that you send. If you send a long message, it will be broken into multiple SMS.

The maximum size of a text is 140 bytes. The most efficient encoding for SMS is GSM-7, which is a limited character set that uses 7 bits for each character. This means you can send 140*8/7 = 160 characters. If you use non-GSM characters (eg. unicode) your message may be limited to 70 characters, because unicode characters are 2 bytes each.

If you're using more SMS quota than you expected and you don't think your message is unicode encoded, closely inspect your message for sneaky unicode characters such as unicode whitespace, apostrophes, and quotation marks.

Use this page to test your messages to see how many SMS segments they will use.

If I send a message and status is not "delivered" or "sending", does it count against my quota?

Yes, we can't retroactively refund texts that aren't successfully delivered. There are many explanations for a text not being delivered, but the most common explanation is that it's a bad number. Please make sure you know who you're texting!

If you are consistently having trouble sending texts to a number you know is valid, please reach out and we'll investigate and refund if necessary.

Why do my SMS include "STOP" instructions?

Regulations require us to include opt-out language on initial contact with new recipients. If you wish to customize opt-out language, including the word "stop" will suppress automatic opt-out instructions.