Throttling Bulk SMS Campaigns with Python and Vonage SMS API

Bulk SMS comes in handy when marketing teams need to do promotional campaigns. Organizations can also deploy them to pass information to a large group of people.

Problems can arise when you send a bulk SMS campaign meant to generate responses to a large audience. For instance, receiving thousands of inbound responses at once could overwhelm your team. One solution to this problem is to use throttling. For example, you can design a campaign to send the messages in batches, at specific periods, or both.

This article will teach you how to implement bulk SMS throttling in Python using the Django REST framework and the Vonage Messages API. The web application we will build in this tutorial will allow you to message multiple users in batches at specified time intervals.

The Vonage Messages API allows developers to develop SMS-based applications and implement messaging features in their apps for SMS, WhatsApp, Messenger, etc. Django is a Python framework used for building web applications. Django REST framework allows developers to build RESTful APIs with Django.


  1. A free Vonage API account
  2. A Vonage application. You can follow this guide to create an application on your Vonage dashboard.
  3. Python (version 3.6 or a later). You can download Python from the official website.
  4. The Python package manager pip. You can find instructions for installing pip here.
  5. The Python tool virtualenv for creating isolated virtual environments for Python projects.

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.

Setup and Installation

You will start with setting up the project dependencies and installing the modules you need with pip. Next, you will create the Django project for the tutorial.

Install Dependencies

First, create a new directory and a virtual environment. Then, activate the newly created virtual environment:

The commands above installed the following packages:

  1. Django: the Django framework package.
  2. djangorestframework: the Django REST framework for creating APIs in Django.
  3. django-cors-headers: This allows our API to make cross-origin requests to other servers.
  4. vonage: the Vonage Python server SDK.

Create a Django project

Now, use the django-admin utility to create a Django project called vonage_project:

Next, you need to configure the Django-cors-headers for the application. That way, other origins and frontend applications can make a request to your Django application. Go to the MIDDLEWARE in the file and add the following middleware classes:

Next, create a Django app called myapp to host our bulk SMS functionality:

Create Bulk SMS functionality

In this section, you will set up the bulk SMS feature with the Vonage SMS API. You will also implement a throttling feature.

Initialize the Vonage Library

Usually, you would need to initialize the Vonage library to use the Vonage API for sending messages. However, the new Vonage Messages API is in beta, and Python is not supported yet. However, we can still use the Messages API.

First, add the following code to the file:

In the above code, replace the API_KEY and API_SECRET values with the values from your Vonage dashboard. The vonageCredentials variable takes your Vonage credentials: your API key and secret key in the form 'API_KEY: API_SECRET.' You then encode and decode the string with your credentials in base64 form to pass them as ASCII standard characters.

Create a View to Send SMS message

Now, create a view for sending the SMS messages in like this:

In the code above, you imported the csrf_exempt, parser_classes, and JSONParser class to enable you to define decorators for the view. You also imported the json, JsonResponse, and other modules you will need in your web app. Then, you created the sendMessage function, where you will put the logic for sending the message.

Next, you will add code inside the sendMessage view to accept requests and user inputs. Modify as follows:

In the above code, you specified the view accepts POST requests in the line: request.method == 'POST'. Then, you decoded the request body in JSON format. After that, you stripped the body of the request to the items it contains. The items are the following inputs received from the user:

  1. sender: a variable that contains the information about the message sender.
  2. recipients: a list of the phone numbers of the SMS recipients.
  3. message_string: the text you will send in the bulk SMS campaign.
  4. batch_size: stipulates the number of recipients to send an SMS to at once.
  5. delay_period: the time frame in between sending SMS batches (measured in seconds).

Now, you will create a function to split the list of the recipients’ phone numbers into batches. Add the following code outside the sendMessage function in the file:

You defined a function called batch. It accepts two parameters: the recipients list and the batch_size integer that represents how many recipients you want to send a message to at once. You use a for loop and the yield keyword to create a batch of phone numbers. If this is unclear, you can read more about the range and yield keywords work.

Now, you will implement the logic to enable sending messages. Modify the sendMessage view as shown below:

There are two for loops inside the sendSmsMessage function. The external for statement loops through the batches of phone numbers using the batch function you defined earlier in this article. You divide the recipients' phone numbers into batches using `batch_size' from the POST request.

Then, you have an inner loop that takes each number in every batch and makes a POST request to the Vonage Messages API at the endpoint. The request header contains the base64 encoded credentials that you created earlier as a “b64value.” It also includes a JSON payload to deliver to the Messages API. The JSON payload contains the following information:

  • sender: a variable that contains the information about the sender of the message.
  • recipients: a list of the phone numbers of the SMS recipients.
  • message_string: the text to be contained in the bulk SMS.
  • batch_size: the number of recipients to be sent a message to at once.
  • delay_period: the time frame in between the SMS batches to be sent.

Upon making a successful request to the Messages API endpoint, the SMS message goes to the recipient, and the code prints a message to your terminal to alert you of the sent message. Then, your code works on sending the next batch.

After you’ve sent a message to all the recipients in a batch, the parent for loop executes after the delay period you set with time.sleep(delay_period).

When you finish sending the SMS messages, your code returns a 200 - OK JsonResponse.

The full code is as follows:

Define a URL path

Since you have created a view for receiving requests, you will need a corresponding URL for users to access the view to make requests. Therefore, you will add a path to the urlpatterns inside the file of the project. Navigate to the project subdirectory and add the following code:

As shown above, you imported path and the sendMessage view. Then, you added a path with the URL message/ to the list of urlpatterns.

Test Application API

You can test the functionality built above with the Postman tool for simulating and documenting APIs. You can sign up for a free Postman account.

To run this test, you also need to start Django’s test server like this:

Let’s assume you intend to use the following details for your SMS bulk campaign.

You can input the above details into the body of a Postman request as JSON as shown in the following image:

Make sure you replace the "recipients" phone numbers with real numbers and replace "sender" with your Vonage number before sending the request. Then, the messages will be delivered to your recipients.


In this article, you implemented bulk SMS throttling using Vonage in a Django REST API. You can now integrate this solution into your projects and build more solutions with Vonage. You can review our authentication guide to better understand authentication with Vonage APIs.




Developer content from the team at Vonage, including posts on our Java, Node.js, Python, DotNet, Ruby and Go SDKs

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Pro-Tip: Store Sensitive Data in Amazon S3 (and retrieve it from within a Django application)

CS373 Spring 2022: Henry Liu

What does a tech writer do?

Cloud Computing Trends that Amaze you in 2021

Enappd Store: biggest inventory of best quality iOS/Android App Templates

Effective Java: For Instance Control, Prefer Enum types to readResolve

When You Need to Scroll Deeper: Addressing UIScrollView’s Optimization Problems

The Program Committee of JS Kongress 19

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Vonage Dev

Vonage Dev

Developer content from the team at Vonage, including posts on our Java, Node.js, Python, DotNet, Ruby and Go SDKs

More from Medium

Database in Python using psycopg2

Beginner’s guide to using diff and patch

10 Minutes of Killer Python Inspiration With Influencer Mike Driscoll

Git and GitHub Basics: Part 2— git commands