19 things to check before your SMS API integration goes live

19 important things to check before your SMS API integration goes live

This list is really important.

Some of the points highlight areas where you could use more SMS credits than you intended. 

Before you press ‘go’ on your SMS API integration, have a quick look at these 18, easily made mistakes.

1. Check your messages are using the GSM character set

Our SMS API platform uses the GSM character set for transmitting SMS.

GSM characterset

If a message contains any character outside the GSM alphabet, UTF-16 encoding will apply, along with a 70-character limit on message length.

This allows us to support the sending of emoticons, which many customers need.

UTF-16 encoding a message dramatically reduces the numbers of characters available per text credit. Instead of the usual 160 characters, a UTF-16 encoded message allows just 70.

This is reflected in the number of credits used to send the message (i.e. we will charge you 1 credit per 70 characters.)

Don’t be tempted to copy and paste content from Microsoft Word or other word processing applications. This would probably result in non-GSM characters being used and the message sent as UTF-16. 

Some characters, such as certain apostrophes and hyphens may appear to be in the GSM character set but actually contain subtle differences.

The apostrophe and hyphen are probably the most commonly mis-used characters.

Also be careful when using the pound sign and check that you’ve tested this before your integration goes into production.

Use our free unicode detector to identify and remove any non-gsm characters in your text messages

2. Triple-check your code in all possible scenarios

Please make sure that you’ve thoroughly checked your code so that it functions as expected in all different scenarios.

Make sure that you’ve understood the error codes that we respond with and that your system responds appropriately.

Check that your code can’t run wild and send out messages in an uncontrolled way.
You don’t want to find that your SMS credits have all been consumed very quickly because of an obvious error.

I’m afraid we can’t refund credits that have been lost in this way. Our code samples have been thoroughly tested but it’s important that you ensure they work in your unique set-up.

(Again, we can’t be held responsible for problems that arise because of use of our code snippets in your environment.)

We have a flooding filter which is there to help prevent a single person receiving multiple messages in a short space of time.
A single number can only receive 20 varied messages and 3 identical messages per hour.

In some situations though, the flooding filter may not prevent multiple message being sent, so please don’t rely on it to prevent multiple messages being attempted. (We can’t refund credits that have been lost because the flooding filter didn’t stop messages being delivered.)

Please also check that the flooding filter won’t prevent intended messages from being delivered.
If you’re using our service for server alerts for example, it’s conceivable that you may want to send more than 6 identical messages in a 1 hour period.

3. Set up low credits warning email alerts

Running out of SMS credits is a worry for most customers. To prevent this happening, you can set up low credits warning emails.

You’ll be sent daily emails when your account falls below a set number of credits remaining.

To set up your low credits warning alerts, simply log into your account and scroll to Low Credit Warning. Here you can set the number of credits below which the alerts will be triggered.

We suggest that you trigger the alerts when you have about 3 weeks of credit remaining. That way you’ll have plenty of time before the account runs out.

Don’t forget to add all the contacts that need to receive the alerts and make sure that you’ve whitelisted our domains so that you can receive the emails, see below – point 8.

You can also set up SMS auto top up. This will automatically make a purchase of a certain number of SMS credits if the credits level drops below a set level.

You can also apply for an SMS overdraft. This allows your account to continue sending even if the credit level falls below zero.
This overdraft is agreed with us in advance and we usually set the overdraft to around 2 weeks of SMS usage.

4. Check you have the relevant permissions to send SMS

Since GDPR came into force in May 2018, the rules surrounding the sending of marketing texts have become stricter.

If you’re planning to send marketing texts to your customers,  you’ll need to make sure you have their permission.

Failure to do so could result in some rather alarming fines if people complain.

The rules are designed to protect consumers but there’s nothing too much to worry about. There are a number of ‘legitimate interests’ that allow you to send marketing texts.

This guide on SMS opt out rules might be useful

5. Make sure that replies are being handled correctly

If your SMS service has a reply option, ensure that your have configured the URL to which you want incoming texts to be sent and that it’s been tested from end to end.

Incoming texts can also be sent to you by email. This can be easily configured in your account.

6. Check the message length is as intended

A standard text message using the GSM character set is 160 characters including spaces. Messages that are longer than 160 characters will use more than one text credit. Messages can be up to a maximum of 1280 characters in length.

Messages longer than 160 characters get segmented into chunks of 153 characters to send to the recipient’s handset, so you’ll be charged 1 credit per 153 characters.

(The missing 7 characters are used to insert instructions to stitch longer messages together, so that they arrive as one long text rather than a series of texts.)

For more information on the credit usage, please visit our developers’ page.
Also see our in depth article about SMS message length.

Before your SMS integration goes into production, please make sure that you’ve checked that message length is correct. Unfortunately, we can’t refund credits that have been consumed because of a miscalculation.

Our free SMS message length calculator shows the number of characters in a text and how many SMS credits will be needed to send it.

7. Failed international texts are not refunded

This is more of a reminder than something to check. Non-delivered international texts are not refunded back to customers’ accounts.

The reason for this simple. We are charged for all non-UK SMS traffic that we submit, so we have to charge for international texts, regardless of delivery outcome.

Also, please note that if you’re intending to send messages outside the UK, then you will need to contact us so that we can enable your account for international sending. Don’t worry though, it only takes a minute.

International delivery reports are also far less detailed than those for the UK. In many cases we are unable to determine why a particular message has failed as the relevant network do not always provide us with the relevant information.

Unfortunately when this is the case we won’t be able to obtain further information.

If you’re planning to send messages outside the UK, please  also read this important article about international SMS. It highlights a few things you need to be aware of.

One final note. It costs more to send to international mobile numbers. Here’s our international pricing table.

8. White list our domains

If you’re using our SMS to email reply function, make sure that our emails aren’t going to get stuck in your spam filters.

If you ever change your login credentials, you’ll also need to be able to receive emails from us.

The 2 domains from which email are sent are as follows.


Please contact us if you need to white list our IP addresses, so that you can receive data sent to a URL endpoint. ([email protected])

9. Generating a new key and secret from your account will invalidate the existing token

Please be aware that if you generate a new key and secret from your account page, then your existing token will be invalidated and your texts will stop sending.

Make sure that all the relevant staff are aware of this, so that no mishaps occur.

Your account will ask you to confirm that you want to generate a new secret and key along with a warning of the consequences!

If you need further clarification or need an extra account for testing, just ask us. We’re here to help.

10. Delivery reports will expire after 3 months

Please not that due to very large files sizes, SMS delivery reports will expire after 3 months and will no longer be accessible. If you need access to your delivery data, please make sure you download reports before they are permanently deleted.

11. If you use the ‘ttl’ parameter you will not be able to view delivery reports

The ttl (time to live) parameter allows you to remove all message data from our systems after a set number of minutes. For data protection, some customers are required to remove all data from third parties.

If you’ve used this tool, then you won’t be able to access delivery reports because we will have deleted all data.

12. Server locations

All servers and data centres used to handle data and send SMS messages are based in the UK.

13. Is your testing to one number triggering our flooding filters?

An ‘SMS flooding filter‘ is in place to prevent individuals being sent the same message repeatedly in a short space of time. A single number can only receive 20 varied messages and 6 identical messages per hour.

When conducting testing, please use a selection of mobile numbers to prevent messages being rejected.

14. Conduct your testing using UK phone numbers

Do you use developers based overseas?

This can cause problems when trying to test a service which will mainly be used in the UK.

Problems often occur when using non-UK mobile numbers for testing. For example some overseas networks do not permit alphanumeric sender IDs, so this can’t be tested accurately. Delivery reporting can also be slower and reporting not as consistent as the UK networks.

If your service is mainly going to be based in the UK, then please use UK numbers for testing.

15. Set webhook alarm triggers

This is a safeguarding tool that alerts you by email if the webhooks that you have configured stop working or become unresponsive.

This webhook monitor gives you piece of mind that your webhooks are functioning as intended.

You’ll find more detail on this on the Incoming SMS monitor page.

16. Do you have a web form that generates an SMS? Make sure it’s not a victim of SMS pumping

SMS traffic pumping fraud happens when fraudsters take advantage of a mobile phone number input field on a web form.

They ambush it by triggering large volumes of outbound texts to automatically generated mobile numbers. The criminals benefit from a revenue share with a mobile network.

17. Enable our costing saving tools

Consider enabling our AI SMS optimiser, unicode replacement and emoji removal tools. They could save you a considerable unintended overspend.

18. Check that the sender IDs you intend to use are permitted

BT/EE have brought in a new code of conduct to help reduce fraudulent SMS on their network.
Generic sender IDs like ‘Info’ or ‘appointment’ will be blocked.
Foreign virtual reply are numbers are not permitted.
UK reply numbers and short code are allowed.
BT/EE will block suspected spam or fraudulent URLs

We suggest that you test all the messages and sender IDs before going live.
The following article details the new code of conduct for sending business SMS.

19. Don’t generate a new JSON Web Token for every text that you send

There’s no need to renew your JSON Web Token for every text that you send and doing this could cause issues.

you should treat your JSON Web Token like a password, and renew it periodically, inline with your organisation’s password policy.

Can we help at all?

If you run into any bumps in the road while getting your SMS integration ready for action, then please don’t hesitate to be in touch. We may be able to help.

Sometimes, just having a different set of eyes on a problem can help a solution emerge.

Customers have said some very kind things about our service, reliability and support, so I hope we’ll be able to provide you with a top notch service.

author avatar
Phil Warner Technical Director
Co-founder and Director of The SMS Works, a low cost and powerful SMS API for developers. About Phil.