Getting started sending SMS guide

Developers are encouraged to view the Quick Starts, including screencasts, on Github: See Sending your first SMS

Nexmo’s RESTful API connects you to carriers in over 200 countries around the world.  It's easy to use and takes just minutes to connect.

You will need:

  • Nexmo account
  • API key and your API secret from the Nexmo Dashboard
  • Your mobile phone number, which will act as the destination number. Until you have made your first top-up you will be restricted to sending to 10 pre-registered numbers. The mobile phone number you used to authenticate your account will automatically be added to this list. You can find more information about adding destination numbers to your destination list here.
  • SenderID, which is the From: information that will appear on the recipient’s handset.  For U.S. and Canadian destinations this must be a pre-approved phone number, which you can purchase from the Nexmo Dashboard.  

1. Format your destination number
Make sure you format your mobile number correctly, with the country code and without spaces or plus signs or leading zeros. Here is an example of how a number should be formatted:


This is the format for any destination number that will receive SMS from your application, both local and international.  Be sure to verify local carrier restrictions for any messages you would like to send by using our Country Specific Knowledge Base.

2. Prepare your message
Now it’s time to compose your message body. For your first message, we suggest you send plain text. Note that until you have made your first top-up we will include [FREE SMS DEMO, TEST MESSAGE] in your SMS.
(Older accounts will have [Nexmo DEMO] in your SMS instead of [FREE SMS DEMO, TEST MESSAGE] ).

As with all parameters, your message body must always be URL encoded. For type=unicode message body should be also UTF8 encoded (URL and UTF8).  Simply plug your message body into this website to format it properly:

3. Put it all together
Now, copy the below link, paste it into the address box of your favourite web browser, and replace values with your actual API key, API secret, senderID, destination number and message body into this URL.  Upon hitting "Enter" you should receive a text almost immediately.

Congratulations!  You've just sent your first text using the Nexmo API.


Next Steps:

Was this article helpful?
6 out of 6 found this helpful
Have more questions? Submit a request