How to Send SMS Messages with Python, Flask and Vonage

Published June 22, 2017 by Mark Smith

This is the first post in a series about using the Vonage APIs with Python.

The Vonage SMS API is an HTTP-based API using either XML or JSON to describe how to send an SMS or understand a received SMS. Fortunately, you don’t need to worry about that too much because Vonage provides a Python client library called nexmo-python that takes care of a lot of the underlying detail for you.


Before starting, you’ll want to make sure you have Python installed. The code here was tested on Python 2.7 and 3.6. If you have the choice, use Python 3.6 – it’s awesome! If you’re running Python 2, make sure you also have virtualenv installed.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs. If you’ve just signed up, the initial cost of a number will be easily covered by your available credit.

Start building with Vonage

Install the Nexmo Python Library

Just to keep everything neat and tidy, let’s create a virtualenv and install the Nexmo python client library into it:

Send an SMS from the Python REPL

Sending an SMS is so easy, let’s just do it from the REPL. First, run python from the command-line, and then enter the three lines below.

Let’s just quickly recap on what those three lines did:

  • The first line imported nexmo-python.
  • The second line created a Nexmo Client object, which can be re-used, and knows your Vonage API key and the secret associated with it.
  • The third line actually sends the SMS message.

Hopefully, you received an SMS message! If not, check the contents of the response, the error messages are quite helpful.

SMS screenshot

Notice that send_message returns a dictionary, which tells you how many messages your SMS was divided into, and how much it cost you to send the message. Because the message I sent was short enough to be sent as a single SMS and it was sent within the UK, it cost me only 3.33 Euro Cents, but longer messages will need to be sent as multiple messages. Vonage will divide them up for you, and the SMS client on the phone will automatically reassemble them into the original long message, but this costs more than a short message.

Extra Credit: Build an SMS Sending Flask App

If anything, that was a bit too easy. So for extra credit, let’s create a tiny web application that allows you to send an SMS message.

I’ll show you how to build a small Flask app with a form for a phone number and an SMS message. When you press “Send SMS” it will post to a second view that will send the SMS using the Vonage SMS API.

view on Github

Set Up Our SMS Sending Flask App

So first let’s install our dependencies. I’d recommend checking out the sample code and running pip install -r requirements.txt. At the very least, you’ll need to install Flask into your virtualenv.

So next I create a Nexmo Client object and an empty Flask app. I also like to create 12-factor apps, so I’m loading in configuration from environment variables (check out the helper function in in the sample code).

The problem with loading in environment variables is that it can make running the app a little bit more difficult, so I’m using the python-dotenv library to load a .env file for me. It copies the values into the env var dictionary, so I can still get the values using getenv as I would normally.

Add a Send SMS View

Next we’ll add a view that renders a Jinja2 template:

Let’s now create that template at templates/index.html. Otherwise, it won’t work!

The following HTML includes the Bootstrap CSS framework and then renders a form with two fields: to_number for taking the destination phone number and message, so the user can enter their SMS message.

Run the Flask Server

Before you can start your server, you’ll need to provide configuration in a .env file. Start with the following and fill in your details:

Now start your app with:

Now if you load http://localhost:5000/, you should see something like this:

SMS Form Screenshot

Don’t press “Send SMS” just yet! We haven’t told Flask what to do when you submit the form, so you’ll get a 404 page not found error.

Handle the Form Post

Add the following function to the bottom of your python file, to accept the POST request from the form:

If your FLASK_DEBUG flag is set to true, then your changes should automatically be reloaded into the running server, so refresh your form, fill in your phone number and a message. Make sure the number is in international format without the ‘+’ at the start. Hit “Send SMS” and check your phone!

I hope it worked for you! If not, check out the extra lines in the sample code in and index.html that use Flask’s flash message mechanism to report errors to the user.

And We’re Done!

I hope you enjoyed this getting started guide. Stay tuned for our upcoming guide about receiving SMS messages with Python! In the meantime for more information on our APIs including inbound SMS, Voice, 2-Factor-Authentication and others, have a look at our developer portal. Or to spark your imagination on what’s possible with our APIs, make sure you check out our use-cases and Developer blog!


The following documentation may be useful:

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at