If you have not already done so, create/activate a virtualenv. Unless otherwise stated, assume all terminal code below is executed within the virtualenv.
Dependencies can be installed via the command below.
$ make requirements
Certain delivery channels may require additional configuration before they will function correctly.
SailthruEmailChannel
Settings¶ACE_CHANNEL_SAILTHRU_DEBUG = False
ACE_CHANNEL_SAILTHRU_TEMPLATE_NAME = "Some template name"
ACE_CHANNEL_SAILTHRU_API_KEY = "1234567890"
ACE_CHANNEL_SAILTHRU_API_SECRET = "this is secret"
DjangoEmailChannel
Settings¶EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'localhost'
DEFAULT_FROM_EMAIL = 'hello@example.org'
ACE_CHANNEL_DEFAULT_EMAIL = 'sailthru_email'
ACE_CHANNEL_TRANSACTIONAL_EMAIL = 'django_email'
ACE_ENABLED_CHANNELS = [
'sailthru_email',
'django_email',
]
Each message sent with ACE is represented by an instance of Message
.
These can be created manually, or can be created by calling MessageType.personalize()
on a MessageType
instance. The name and package of the MessageType
determines what templates will be used when the Message
is rendered for delivery.
For example, the class
# myapp/messages.py
class CustomMessage(edx_ace.message.MessageType):
pass
would use the following templates when rendered for email delivery:
myapp/edx_ace/custommessage/email/from_name.txt
myapp/edx_ace/custommessage/email/subject.txt
myapp/edx_ace/custommessage/email/body.html
myapp/edx_ace/custommessage/email/head.html
myapp/edx_ace/custommessage/email/body.txt
These all follow the format {app_label}/edx_ace/{message_name}/{renderer}/{attribute}
,
where the app_label
and message_name
are defined by the MessageType
(or
the manually created Message
), and renderer
and attribute
come from
the renderer being used by the specific delivery channel. The templates will be retrieved
using standard Django template resolution mechanisms.
The specific templates needed for existing renderers are listed in edx_ace.renderers
.
Transactional messages such as password reset should be marked as options.transactional = True
,
to ensure that it won’t be subject to marketing messages opt-out policies.
While not required, transactional messages are recommended to use the django_email
channel which supports
a custom options.from_address
email. For example:
# myapp/messages.py
class PurchaseOrderComplete(edx_ace.message.MessageType):
def __init__(self, *args, **kwargs):
super(PurchaseOrderComplete, self).__init__(*args, **kwargs)
self.options['transactional'] = True
self.options['from_address'] = settings.ECOMMERCE_FROM_EMAIL
The simplest way to send a message using ACE is to just create it, and call edx_ace.ace.send()
.
from edx_ace import ace
from edx_ace.messages import Message
msg = Message(
name="test_message",
app_label="my_app",
recipient=Recipient(lms_user_id='123456', email='a_user@example.com'),
language='en',
context={
'stuff': 'to personalize the message',
}
)
ace.send(msg)
The name
and app_label
attributes are required in order for ACE to look
up the correct templates in the Django environment.
For messages being sent from multiple places in the code, it can be simpler to
define a MessageType
first, and then MessageType.personalize()
it.
from edx_ace import ace
from edx_ace.messages import Message
class TestMessage(MessageType):
APP_LABEL = "my_app" # Optional
NAME = "test_message" # Optional
msg_type = TestMessage(
context={
'generic_stuff': 'that is applicable to all recipients'
}
)
for recipient in recipients:
msg = msg_type.personalize(
recipient=recipient,
language='en',
context={
'stuff': 'to personalize the message',
}
)
ace.send(msg)