{"id":14972769,"url":"https://github.com/roaldnefs/django-sms","last_synced_at":"2025-03-30T11:31:37.413Z","repository":{"id":40457235,"uuid":"329073609","full_name":"roaldnefs/django-sms","owner":"roaldnefs","description":"A Django app for sending SMS with interchangeable backends.","archived":false,"fork":false,"pushed_at":"2024-01-07T19:43:51.000Z","size":61,"stargazers_count":55,"open_issues_count":11,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-19T20:15:59.798Z","etag":null,"topics":["django","django-application","hacktoberfest","python","python-3","sms"],"latest_commit_sha":null,"homepage":"https://django-sms.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roaldnefs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-12T18:16:13.000Z","updated_at":"2024-12-25T18:57:21.000Z","dependencies_parsed_at":"2024-01-07T20:53:34.277Z","dependency_job_id":"9c32449a-d24d-4d6d-b19c-7f6f644512cd","html_url":"https://github.com/roaldnefs/django-sms","commit_stats":{"total_commits":30,"total_committers":3,"mean_commits":10.0,"dds":0.09999999999999998,"last_synced_commit":"6f9ac3610af4de740064ed08b8c549e606aea073"},"previous_names":["django-enterprise/django-sms"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roaldnefs%2Fdjango-sms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roaldnefs%2Fdjango-sms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roaldnefs%2Fdjango-sms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roaldnefs%2Fdjango-sms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roaldnefs","download_url":"https://codeload.github.com/roaldnefs/django-sms/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246314011,"owners_count":20757450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-application","hacktoberfest","python","python-3","sms"],"created_at":"2024-09-24T13:47:30.116Z","updated_at":"2025-03-30T11:31:36.541Z","avatar_url":"https://github.com/roaldnefs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django SMS\n[![PyPI](https://img.shields.io/pypi/v/django-sms?color=156741\u0026logo=python\u0026logoColor=ffffff\u0026style=for-the-badge)](https://pypi.org/project/django-sms/)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/roaldnefs/django-sms/tests.yml?branch=main\u0026color=156741\u0026label=CI\u0026logo=github\u0026style=for-the-badge)](https://github.com/roaldnefs/django-sms/actions)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-sms?color=156741\u0026logo=python\u0026logoColor=white\u0026style=for-the-badge)](https://pypi.org/project/django-sms/)\n[![PyPI - Django Version](https://img.shields.io/pypi/djversions/django-sms?color=156741\u0026logo=django\u0026logoColor=ffffff\u0026style=for-the-badge)](https://pypi.org/project/django-sms/)\n\n**django-sms** is a Django app for sending SMS with interchangeable backends. The module is heavily based upon and structured the same way as the `django.core.mail` module.\n\n- [Sending SMS](#sending-sms)\n    - [Quick example](#quick-example)\n    - [send_sms()](#send_sms)\n    - [Examples](#examples)\n    - [The **Message** class](#the-message-class)\n        - [Message Objects](#message-objects)\n    - [SMS backends](#sms-backends)\n        - [Obtaining an instance of an SMS backend](#obtaining-an-instance-of-an-sms-backend)\n            - [Console backend](#console-backend)\n            - [File backend](#file-backend)\n            - [In-memory backend](#in-memory-backend)\n            - [Dummy backend](#dummy-backend)\n            - [MessageBird backend](#messagebird-backend)\n            - [Twilio backend](#twilio-backend)\n        - [Defining a custom SMS backend](#defining-a-custom-sms-backend)\n    - [Signals](#signals)\n        - [sms.signals.post_send](#sms.signals.post_send)\n- [Acknowledgement](#acknowledgement)\n\n## Sending SMS\nThese wrappers are provided to make sending SMS extra quick, to help test SMS sending during development, and to provide additional SMS gateways.\n\n### Quick example\nIn two lines:\n\n```python\nfrom sms import send_sms\n\nsend_sms(\n    'Here is the message',\n    '+12065550100',\n    ['+441134960000'],\n    fail_silently=False\n)\n```\n\nThe text messages are sent using one of the configured [SMS backends](#sms-backends).\n\n### send_sms()\n**send_sms(_body, originator, recipients, fail_silently=False, connection=None_)**\n\nIn most cases, you can send text messages using **sms.send_sms()**.\n\nThe **message**, **originator** and **recipients** parameters are required.\n\n- **message**: A string.\n- **originator**: A string. If **None**, django-sms will use the **DEFAULT_FROM_SMS** setting.\n- **recipients**: A list of strings, each an phone number.\n- **fail_silently**: A boolean. When it's **False**, **send_sms()** will raise an exception if an error occurs. See the [SMS backends](#sms-backends) documentation for a list of possible exceptions.\n- **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 of [SMS backends](#sms-backends) for more details.\n\nThe return value will be the number of successfully delivered text messages.\n\n## Examples\nThis sends a text message to _+44 113 496 0000_ and _+44 113 496 0999_:\n\n```python\nsend_sms(\n    'Here is the message',\n    '+12065550100',\n    ['+441134960000', '+441134960999']\n)\n```\n\n### The **Message** class\ndjango-sms' **send_sms()** function is  actually a thin wrapper that makes use of the **Message** class.\n\nNot all features of the **Message** class will be available though the **send_sms()** and related wrapper functions. If you wish to use advanced features, you'll need to create **Message** instances directly.\n\n**Note**: This is a design feature. **send_sms()** was originally the only interfaces django-sms provided.\n\n**Message** is responsible for creating the text message itself. The SMS backend is then responsible for sending the SMS.\n\nFor convenience, *Message** provides a **send()** method for sending a single text message. If you need to send multiple text messages, the SMS backend API provides alternatives.\n\n#### Message Objects\n**_class_ Message**\n\nThe **Message** class 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 the **send()** method.\n\n- **body**: The body text. This should be a plain text message.\n- **originator**: The sender of the text message.\n- **recipients**: A list or tuple of recipient phone numbers.\n- **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 when **send()** is called.\n\nFor example:\n\n```python\nfrom sms import Message\n\nmessage = Message(\n    'Here is the message',\n    '+12065550100',\n    ['+441134960000']\n)\n```\n\nThe class has the following methods:\n\n- **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 argument **fail_silently** is **True**, exceptions raised while sending the text messages will be quashed. An empty list of recipients will not raise an exception.\n\n### SMS backends\nThe actual sending of an SMS is handled by the SMS backend.\n\nThe SMS backend class has the following methods:\n\n- **open()** instantiates a long-lived SMS-sending connection.\n- **close()** closes the current SMS-sending connection.\n\nIt can also be used as a context manager, which will automatically call **open()** and **close()** as needed:\n\n```python\nimport sms\n\nwith sms.get_connection() as connection:\n    sms.Message(\n        'Here is the message', '+12065550100', ['+441134960000'],\n        connection=connection\n    ).send()\n    sms.Message(\n        'Here is the message', '+12065550100', ['+441134960000'],\n        connection=connection\n    ).send()\n```\n\n### Obtaining an instance of an SMS backend\nThe **sms.get_connection()** function in **sms** returns an instance of the SMS backend that you can use.\n\n**get_connection(_backend=None, fail_silently=False, *args, **kwargs_)**\n\nBy default, a call to **get_connection()** will return an instance of the SMS backend specified in **SMS_BACKEND**. If you specify the **backend** argument, an instance of that backend will be instantiated.\n\nThe **fail_silently** argument controls how the backend should handle errors. If **fail_silently** is True, exceptions during the SMS sending process will be silently ignored.\n\nAll other arguments are passed directly to the constructor of the SMS backend.\n\ndjango-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 can [write your own SMS backend](#defining-a-custom-sms-backend).\n\n#### Console backend\nInstead 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 to **stdout**. You can use a different stream-like object by providing the **stream** keyword argument when constructing the connection.\n\n```python\nSMS_BACKEND = 'sms.backends.console.SmsBackend'\n```\n\nThis backend is not intended for use in production - it is provided as a convenience that can be used during development.\n\n#### File backend\nThe 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 the **SMS_FILE_PATH** setting or file the **file_path** keyword when creating a connection with **get_connection()**.\n\nTo specify this backend, put the following in your settings:\n\n```python\nSMS_BACKEND = 'sms.backends.filebased.SmsBackend'\nSMS_FILE_PATH = '/tmp/app-messages' # change this to a proper location\n```\n\nThis backend is not intended for use in production - it is provided as a convenience that can be used during development.\n\n#### In-memory backend\nThe **'locmen'** backend stores text messages in a special attribute of the **sms** module. The **outbox** attribute is created when the first message is sent. It's a list with an **Message** instance of each text message that would be sent.\n\nTo specify this backend, put the following in your settings:\n\n```python\nSMS_BACKEND = 'sms.backends.locmem.SmsBackend'\n```\n\nThis backend is not intended for use in production - it is provided as a convenience that can be used during development.\n\n#### Dummy backend\nAs the name suggests the dummy backend does nothing with your text messages. To specify this backend, put the following in your settings:\n\n```python\nSMS_BACKEND = 'sms.backends.dummy.SmsBackend'\n```\n\nThis backend is not intended for use in production - it is provided as a convenience that can be used during development.\n\n#### MessageBird backend\nThe [MessageBird](https://messagebird.com/) backend sends text messages using the [MessageBird SMS API](https://developers.messagebird.com/api/sms-messaging/#send-outbound-sms). To specify this backend, put the following in your settings:\n\n```python\nSMS_BACKEND = 'sms.backends.messagebird.SmsBackend'\nMESSAGEBIRD_ACCESS_KEY = 'live_redacted-messagebird-access-key'\n```\n\nMake sure the MessageBird Python SDK is installed by running the following command:\n\n```console\npip install \"django-sms[messagebird]\"\n```\n\n#### Twilio backend\nThe [Twilio](https://twilio.com/) backend sends text messages using the [Twilio SMS API](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource). To specify this backend, put the following in your settings:\n\n```python\nSMS_BACKEND = 'sms.backends.twilio.SmsBackend'\nTWILIO_ACCOUNT_SID = 'live_redacted-twilio-account-sid'\nTWILIO_AUTH_TOKEN = 'live_redacted-twilio-auth-token'\n```\n\nMake sure the Twilio Python SDK is installed by running the following command:\n\n```console\npip install \"django-sms[twilio]\"\n```\n\n### Defining a custom SMS backend\nIf you need to change how text messages are sent you can write your own SMS backend. The **SMS_BACKEND** setting in your settings file is then the Python import path for you backend class.\n\nCustom SMS backends should subclass **BaseSmsBackend** that is located in the **sms.backends.base** module. A custom SMS backend must implement the **send_messages(messages)** method. This methods receives a list of **Message** instances and returns the number of successfully delivered messages. If your backend has any concept of a persistent session or connection, you should also implement **open()** and **close()** methods. Refer to one of the existing SMS backends for a reference implementation.\n\n### Signals\n**django-sms** provides a set of built-in signals that let user code get notified by Django itself of certain actions. These include some useful notifications:\n\n#### **sms.signals.post_send**\nSent after **send()** is called on a **Message** instance. Arguments sent with this signal:\n\n- **sender**: The **Message** class.\n- **instance**: The actual **Message** instance being send.\n\n## Acknowledgement\nThis project is heavily based upon the **django.core.mail** module, with the modified work by [Roald Nefs](https://github.com/roaldnefs). The [Django license](https://raw.githubusercontent.com/roaldnefs/django-sms/main/LICENSE.django) is included with **django-sms**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froaldnefs%2Fdjango-sms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froaldnefs%2Fdjango-sms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froaldnefs%2Fdjango-sms/lists"}