Toolbox¶
sitemessage toolbox exposes some commonly used functions.
Defining message recipients¶
sitemessage.toolbox.recipients allows to define message recipients for various messengers, so that they could be passed into message scheduling functions:
from sitemessage.toolbox import recipients
from sitemessage.messengers.smtp import SMTPMessenger
from sitemessage.messengers.xmpp import XMPPSleekMessenger
# The first argument could be Messenger alias:
my_smtp_recipients = recipients('smtp', ['user1@host.com', 'user2@host.com']),
# or a Messenger class itself:
my_jabber_recipients = recipients(XMPPSleekMessenger, ['user1@jabber.host.com', 'user2@jabber.host.com']),
# Second arguments accepts either Django User model instance or an actual address:
user1_model = ...
my_smtp_recipients = recipients(SMTPMessenger, [user1_model, 'user2@host.com'])
# You can also merge recipients from several messengers:
my_recipients = my_smtp_recipients + my_jabber_recipients
Scheduling messages¶
sitemessage.toolbox.schedule_messages is a generic tool to schedule messages:
from sitemessage.toolbox import schedule_messages, recipients
# Let's import a built-in message type class we'll use.
from sitemessage.messages import EmailHtmlMessage
schedule_messages(
# You can pass one or several message objects:
[
# The first param of this Message Type is `subject`. The second may be either an html itself:
EmailHtmlMessage('Message subject 1', '<html><head></head><body>Some <b>text</b></body></html>'),
# or a dictionary
EmailHtmlMessage('Message subject 2', {'title': 'My message', 'entry': 'Some text.'}),
# NOTE: Different Message Types may expect different arguments.
],
# The same applies to recipients: add one or many as required:
recipients('smtp', ['user1@host.com', 'user2@host.com']),
# It's useful sometimes to know message sender in terms of Django users:
sender=request.user
)
Sending test messages¶
When your messengers are configured you can try and send a test message using sitemessage_probe management command:
./manage.py sitemessage_probe smtp --to someone@example.com
Or you can use sitemessage.toolbox.send_test_message function:
from sitemessage.toolbox import send_test_message
send_test_message('smtp', to='someone@example.com')
Sending messages¶
Scheduled messages are normally sent with the help of sitemessage_send_scheduled management command, that could be issued from wherever you like (cron, Celery, etc.):
./manage.py sitemessage_send_scheduled
Nevertheless you can directly use sitemessage.toolbox.send_scheduled_messages from sitemessage toolbox:
from sitemessage.toolbox import send_scheduled_messages
# Note that this might eventually raise UnknownMessengerError, UnknownMessageTypeError exceptions.
send_scheduled_messages()
# Or if you do not want sitemessage exceptions to be raised (that way scheduled messages
# with unknown message types or for which messengers are not configured won't be sent):
send_scheduled_messages(ignore_unknown_messengers=True, ignore_unknown_message_types=True)
# To send only messages of a certain priority use `priority` argument.
send_scheduled_messages(priority=10)
Cleanup sent messages and dispatches¶
You can delete sent dispatches and message from DB using sitemessage_cleanup:
./manage.py sitemessage_cleanup --ago 5
Or you can use sitemessage.toolbox.cleanup_sent_messages from sitemessage toolbox:
from sitemessage.toolbox import cleanup_sent_messages
# Remove all dispatches (but not messages) 5 days old.
cleanup_sent_messages(ago=5, dispatches_only=True)
# Delete all sent messages and dispatches.
cleanup_sent_messages()
Use sitemessage to send Django-generated e-mails¶
In settings.py of your project set EMAIL_BACKEND to a backend shipped with sitemessage.
EMAIL_BACKEND = 'sitemessage.backends.EmailBackend'
After that Django’s send_mail() function will schedule e-mails using sitemessage machinery.