Send SMS and MMS Messages in Python

In this tutorial, we’ll show you how to use Twilio’s Programmable Messaging to send SMS and MMS messages from your Python application.

The code samples in this tutorial use Twilio’s Python helper library. Let’s get started!

Sign up for (or log in to) your Twilio account

Before you can receive phone calls and send messages, you’ll need to sign up for a Twilio account and purchase a Twilio phone number.

If you’re brand new to Twilio, you can sign up for a free trial account to get started. Once you've signed up, head over to your Console and grab your Account SID and your Auth Token. You will need those values for the code samples below.

Get a phone number with SMS (and MMS) capabilities

Sending messages requires a Twilio phone number with SMS capabilities. If you don’t currently own a Twilio phone number with SMS capabilities, you’ll need to buy one. After navigating to the Buy a Number page, check the SMS box and click Search:

If you live in the US or Canada and also wish to send MMS messages, you can select the MMS box. When viewing the search results, you can see the capability icons in the list of available numbers:

Find a number you like and click Buy to add it to your account.

Now that you have a Twilio phone number you can start sending messages to mobile devices.

Send an SMS message in Python via the REST API

To send an outgoing SMS message from your Twilio account you’ll need to make an HTTP POST to Twilio's Message resource.

Twilio's Python library helps you to create a new instance of the Message resource, specifying the To, From, and Body parameters of your message.

If you don’t already have the Python helper library installed you can install it using pip:

pip install twilio

If you’re not using pip you can find manual installation instructions here.

Now, create a file named send_sms.py and include the following code:

Replace the placeholder values for account_sid and auth_token with your unique values. You can find these in your Twilio console.

You’ll tell Twilio which phone number to use to send this message by replacing the from_ number with the Twilio phone number you purchased earlier.

Next, specify yourself as the message recipient by replacing the to number with your mobile phone number. Both of these parameters must use E.164 formatting (+ and a country code, e.g., +16175551212)

We also include the body parameter, which contains the content of the SMS we’re going to send.

Once you’ve updated the code sample, you can test it out by running it from the command line:

python send_sms.py

In just a few moments you should receive an SMS!

Let’s take a moment to understand what’s going on behind the scenes when you send this request to Twilio.

Twilio's response

When Twilio receives your request to send an SMS via the REST API, it will check that you’ve included a valid Twilio phone number in the from_ field. Twilio will then either queue the SMS or return this HTTP error in its response to your request.

Twilio's JSON response includes a robust amount of data about your message. A sample response might look like this:

{"sid": "SMxxxxxxxxxxxxxxx", 
 "date_created": "Thu, 09 Aug 2018 17:26:08 +0000", 
 "date_updated": "Thu, 09 Aug 2018 17:26:08 +0000", 
 "date_sent": null, 
 "account_sid": "ACxxxxxxxxxxxxxxxx", 
 "to": "+15558675310",
 "from": "+15017122661",
 "messaging_service_sid": null,
 "body": "This is the ship that made the Kessel Run in fourteen parsecs?", 
 "status": "queued", 
 "num_segments": "1", 
 "num_media": "0",
 "direction": "outbound-api",
 "api_version": "2010-04-01",
 "price": null,
 "price_unit": "USD",
 "error_code": null,
 "error_message": null,
 "uri": "/2010-04-01/Accounts/ACxxxxxxxxx/Messages/SMxxxxxxxxxxxx.json",
 "subresource_uris": {
     "media": null
 }
}

You can access any of these attributes from your Python code, much like we did when we printed the message.sid.

Try adding a print statement like print(message.status). Save the file, then run the code with python send_sms.py one more time. You should see the status of your message, "queued", printed to your terminal.

If you receive an error in response from Twilio or never receive the message, you may want to check out these tips for troubleshooting undelivered messages.

Send a message to multiple recipients

If you want to send a message to several recipients, you could create an array of recipients and iterate through each phone number in the array:

numbers_to_message = ['+15558675310', '+14158141829', '+15017122661']
for number in numbers_to_message:
    client.messages.create(
        body='Hello from my Twilio number!',
        from_='+15017122662',
        to=number
    )

This will create a new Message instance for each phone number in the list.

Send a message containing media (MMS) in Python

To include media in your Twilio-powered text message, you need to make an addition to the code we wrote above. This time, we need to add the media_url parameter.

Create a file called send_mms.py and include the following code:

Again, update the from_ and to parameters to use your Twilio phone number and your mobile phone.

The new media_url parameter in this code tells Twilio where to go to get the media we want to include. This must be a publicly accessible URL: Twilio will not be able to reach any URLs that are hidden or that require authentication.

Just as when you send a simple SMS, Twilio will send data about the message in its response to your request. The JSON response will contain the unique SID and URI for your media resource:

"subresource_uris": {"media": "/2010-04 01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"}

When the Twilio REST API creates your new Message resource, it will save the image found at the specified media_url as a Media resource. Once created, you can access this resource at any time via the API.

You can print this value from your Python code to see where the image is stored. Add the following line to the end of your send_mms.py file to see your newly provisioned Media URI:

print(message.media._uri)

Save the file and run it from the command line:

python send_mms.py

In just a moment you should receive a text message with an image!

What's next?

You've now successfully sent some messages with the Twilio Programmable Messaging API and the Python helper library.

Check out these in-depth resources to take your programmatic messaging a step further:

• Learn how to send an SMS during an in-progress call with Python and Flask.
• Monitor the status of your message to confirm its delivery.
• Learn how to reply to an SMS sent to your Twilio phone number.
• Learn how to manage message state to turn individual messages into a true SMS conversation.
• Dig into the details with our API reference documentation for Messages.
• Sending high-volume messages? Check out our messaging services.