Sending text messages

So, how do we actually send text messages?

Quick example

# -*- coding: utf-8 -*-

from __future__ import unicode_literals

from djsms import send_text

frm = '+33123456789'
to = '+33987654321'
text = 'Please remember to pick up the bread before coming'
message = send_text(text, frm, to)

The send_text method


Phone numbers must be formatted in international format, with the country code at the beginning and a leading “+”.

The easiest way to send text messages is to use the send_text utility method. It’s a convenient helper to quickly access the application features.

djsms.send_text(text, frm, to, fail_silently=True, status_report=False)

A convenient helper to quickly access the application features.

Returns a TextMessage object.

Required parameters:

  • text – the text message body. It’s length is not limited, but if it’s too long, your carrier will probably split it and send in a multipart text message, and you will be charged accordingly
  • frm – the originator phone number. Some carriers accept alphanumerical values, but it really depends on mobile networks and local laws.
  • to – the recipient phone number.

Additionals parameters:

  • fail_silently – If True, errors will just be ignored.
  • status_report – If True, asks the selected carrier to provide status report by asynchronously calling an uri. If your carrier does’nt provide this option, the parameter value will simply be ignored.


Any TextMessageError subclass if fail_silently is False.


Most backends will work using a REST Api. send_text will result in a blocking HTTP request which can generate a noticeable delay if called during a client’s request processing.

You might want to delegate the actual call to the method in a Celery task.

The TextMessage class

class djsms.models.TextMessage(*args, **kwargs)

An outgoing or incoming text message representation.


Messages sent as multipart are still represented by a single TextMessage object.

TextMessage objects will be created by other part of the app (e.g the send_text method or incoming messages), so you don’t have to create them by yourself.

You can however access TextMessage objects to have information about sent and received messages, such as price, status, date of creation, etc.

The following attributes are available:

  • frm: the sender’s phone number
  • to: the recipient’s phone number
  • text : the message’s content
  • direction: flag to show whether it’s an incoming or outgoing message. Values are ‘incoming’ or ‘outgoing’.
  • price (Decimal): the price billed by your provider for this message
  • status: the message’s current status
  • created_on: the date / time of the message creation

Example usage:

>>> message = send_text(text, frm, to)
>>> print message.price
>>> print message.direction
>>> print message.status


The price attributes contains the price charged by the provider for this text message. This price can be expressed in any currency, however, depending on your account configuration. Check your provider documentation to know more.


The list of different possible statuses.

  • created: the message was just created in the database and was not yet submitted to your text message provider
  • sending: the message was successfully sent to your provider
  • sent: the message was successfully sent to the upstream carrier
  • delivered: the message was successfully delivered to the destination handset
  • refused: the message was refused by your provider
  • rejected: the message was refused by the destination carrier


Because a message was received and accepted by your text message provider does not mean it will be accepted by the destination carrier, nor the destination handset. Be careful not to be confused by the different statuses.