Package: django-sms
Django SMSdjango-smsis a Django app for sending SMS with interchangeable backends. The module is heavily based upon and structured the same way as thedjango.core.mailmodule.Sending SMSQuick examplesend_sms()ExamplesTheMessageclassMessage ObjectsSMS backendsObtaining an instance of an SMS backendConsole backendFile backendIn-memory backendDummy backendMessageBird backendTwilio backendDefining a custom SMS backendSignalssms.signals.post_sendAcknowledgementSending SMSThese wrappers are provided to make sending SMS extra quick, to help test SMS sending during development, and to provide additional SMS gateways.Quick exampleIn two lines:fromsmsimportsend_smssend_sms('Here is the message','+12065550100',['+441134960000'],fail_silently=False)The text messages are sent using one of the configuredSMS backends.send_sms()send_sms(body, originator, recipients, fail_silently=False, connection=None)In most cases, you can send text messages usingsms.send_sms().Themessage,originatorandrecipientsparameters are required.message: A string.originator: A string. IfNone, django-sms will use theDEFAULT_FROM_SMSsetting.recipients: A list of strings, each an phone number.fail_silently: A boolean. When it'sFalse,send_sms()will raise an exception if an error occurs. See theSMS backendsdocumentation for a list of possible exceptions.connection: The optional SMS backend to use to send the text message. If unspecified, an instance of the default backend will be used. See the documentation ofSMS backendsfor more details.The return value will be the number of successfully delivered text messages.ExamplesThis sends a text message to+44 113 496 0000and+44 113 496 0999:send_sms('Here is the message','+12065550100',['+441134960000','+441134960999'])TheMessageclassdjango-sms'send_sms()function is  actually a thin wrapper that makes use of theMessageclass.Not all features of theMessageclass will be available though thesend_sms()and related wrapper functions. If you wish to use advanced features, you'll need to createMessageinstances directly.Note: This is a design feature.send_sms()was originally the only interfaces django-sms provided.Messageis responsible for creating the text message itself. The SMS backend is then responsible for sending the SMS.For convenience,Message* provides asend()method for sending a single text message. If you need to send multiple text messages, the SMS backend API provides alternatives.Message ObjectsclassMessageTheMessageclass is initialized with the following parameters (in the given order, if positional arguments are used). All parameters are optional and can be set at any time prior to calling thesend()method.body: The body text. This should be a plain text message.originator: The sender of the text message.recipients: A list or tuple of recipient phone numbers.connection: An SMS backend instance. Use this parameter if you want to use the same connection for multiple text messages. If omitted, a new connection is created whensend()is called.For example:fromsmsimportMessagemessage=Message('Here is the message','+12065550100',['+441134960000'])The class has the following methods:send(fail_silently=False)sends the text message. If a connection was specified when the text message was constructed, that connection will be used. Otherwise, an instance of the default backend will be instantiated and used. If the keyword argumentfail_silentlyisTrue, exceptions raised while sending the text messages will be quashed. An empty list of recipients will not raise an exception.SMS backendsThe actual sending of an SMS is handled by the SMS backend.The SMS backend class has the following methods:open()instantiates a long-lived SMS-sending connection.close()closes the current SMS-sending connection.It can also be used as a context manager, which will automatically callopen()andclose()as needed:importsmswithsms.get_connection()asconnection:sms.Message('Here is the message','+12065550100',['+441134960000'],connection=connection).send()sms.Message('Here is the message','+12065550100',['+441134960000'],connection=connection).send()Obtaining an instance of an SMS backendThesms.get_connection()function insmsreturns an instance of the SMS backend that you can use.get_connection(backend=None, fail_silently=False, *args, **kwargs)By default, a call toget_connection()will return an instance of the SMS backend specified inSMS_BACKEND. If you specify thebackendargument, an instance of that backend will be instantiated.Thefail_silentlyargument controls how the backend should handle errors. Iffail_silentlyis True, exceptions during the SMS sending process will be silently ignored.All other arguments are passed directly to the constructor of the SMS backend.django-sms ships with several SMS sending backends. Some of these backends are only useful during testing and development. If you have special SMS sending requirements, you canwrite your own SMS backend.Console backendInstead of sending out real text messages the console backend just writes the text messages that would be sent to the standard output. By default, the console backend writes tostdout. You can use a different stream-like object by providing thestreamkeyword argument when constructing the connection.SMS_BACKEND='sms.backends.console.SmsBackend'This backend is not intended for use in production - it is provided as a convenience that can be used during development.File backendThe file backend writes text messages to a file. A new file is created for each session that is opened on this backend. The directory to which the files are written is either taken from theSMS_FILE_PATHsetting or file thefile_pathkeyword when creating a connection withget_connection().To specify this backend, put the following in your settings:SMS_BACKEND='sms.backends.filebased.SmsBackend'SMS_FILE_PATH='/tmp/app-messages'# change this to a proper locationThis backend is not intended for use in production - it is provided as a convenience that can be used during development.In-memory backendThe'locmen'backend stores text messages in a special attribute of thesmsmodule. Theoutboxattribute is created when the first message is sent. It's a list with anMessageinstance of each text message that would be sent.To specify this backend, put the following in your settings:SMS_BACKEND='sms.backends.locmem.SmsBackend'This backend is not intended for use in production - it is provided as a convenience that can be used during development.Dummy backendAs the name suggests the dummy backend does nothing with your text messages. To specify this backend, put the following in your settings:SMS_BACKEND='sms.backends.dummy.SmsBackend'This backend is not intended for use in production - it is provided as a convenience that can be used during development.MessageBird backendTheMessageBirdbackend sends text messages using theMessageBird SMS API. To specify this backend, put the following in your settings:SMS_BACKEND='sms.backends.messagebird.SmsBackend'MESSAGEBIRD_ACCESS_KEY='live_redacted-messagebird-access-key'Make sure the MessageBird Python SDK is installed by running the following command:pip install "django-sms[messagebird]"Twilio backendTheTwiliobackend sends text messages using theTwilio SMS API. To specify this backend, put the following in your settings:SMS_BACKEND='sms.backends.twilio.SmsBackend'TWILIO_ACCOUNT_SID='live_redacted-twilio-account-sid'TWILIO_AUTH_TOKEN='live_redacted-twilio-auth-token'Make sure the Twilio Python SDK is installed by running the following command:pip install "django-sms[twilio]"Defining a custom SMS backendIf you need to change how text messages are sent you can write your own SMS backend. TheSMS_BACKENDsetting in your settings file is then the Python import path for you backend class.Custom SMS backends should subclassBaseSmsBackendthat is located in thesms.backends.basemodule. A custom SMS backend must implement thesend_messages(messages)method. This methods receives a list ofMessageinstances and returns the number of successfully delivered messages. If your backend has any concept of a persistent session or connection, you should also implementopen()andclose()methods. Refer to one of the existing SMS backends for a reference implementation.Signalsdjango-smsprovides a set of built-in signals that let user code get notified by Django itself of certain actions. These include some useful notifications:sms.signals.post_sendSent aftersend()is called on aMessageinstance. Arguments sent with this signal:sender: TheMessageclass.instance: The actualMessageinstance being send.AcknowledgementThis project is heavily based upon thedjango.core.mailmodule, with the modified work byRoald Nefs. TheDjango licenseis included withdjango-sms.ChangelogAll notable changes indjango-smsare documented below.Unreleased0.7.0ChangedAdd support for Django 4.2 and 5.0.Add support for Python 3.12.DeprecatedDrop support for Django 2.2, 3.1 and 4.0.Drop support for Python 3.6 and 3.7.0.6.0ChangedAdd support for Django 3.2, 4.0 and 4.1.Add support for Python 3.11.DeprecatedDrop support for Django 3.0.0.5.0AddedThesms.backends.twilio.SmsBackendto send text messages usingTwilio(#7).0.4.0AddedThesms.backends.messagebird.SmsBackendto send text messages usingMessageBird(#6).ChangedSimplified the attributes of thesms.signals.post_sendsignal to include the instance of the originatingMessageinstead of all attributes (#11).0.3.0(2021-01-30)AddedThesms.signals.post_sendsignal to let user code get notified by Django itself aftersend()is called on aMessageinstance.0.2.0(2021-01-21)AddedThe file backend that writes text messages to a file (#1).0.1.0(2021-01-15)AddedThisCHANGELOG.mdfile to be able to list all notable changes for each version ofdjango-sms.