Getting Started¶

Install dependencies¶

Dependencies can be installed via the command below.

$ make requirements

Configure delivery channels¶

Certain delivery channels may require additional configuration before they will function correctly.

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"

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',
]

Create a message¶

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¶

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

Send a message¶

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)