Sending mail

Introduction

Until recently, many versions of send_mail() were used throughout the code. In some cases, people were constructing their own message and sending that off directly from their code. Moreover, all mail was sent synchronously and prone to breaking the application.

This has changed. We now use Celery to handle asynchronous mail sending. Furthermore, we use a single unified approach to sending mail.

How-to

To send email, import send_mail() from bluebottle.utils.email_backend.

Once imported, you should call the function with the following arguments:

• template_name (string with path to template without the file extension, e.g. 'bb_donations/mails/new_oneoff_donation_fundraiser.mail')
• subject (translated subject, e.g., _('You received a new donation'))
• to (recipient in the form of a user object)
• You can specify additional keyword arguments which will be passed on to the email context

There are a few things to keep in mind when sending mail.

First, the send_mail() function assumes that there are two copies of the email, one with the extension .html and one with the extension .txt. The send_mail function will take care of translating those templates in the correct language.

Second, it is the responsibility of the send_mail() caller to have translated the mail subject. This is unfortunate but we have no way to work around this (yet). The reason for this is that we use keyword arguments and string interpolation to generate various mail subjects (e.g. %(author)s commented on your task). This prevents us from generically translating the subject in the send_mail() function. For example, %(author)s commented on your task would become "Aksel commented on your task" and that translated string will not be found if it is not translated within the send_mail() function.

Lastly, we introduce two new settings in the settings.py file. These can be override in the properties.py file from specific tenants. These two settings are: CELERY_MAIL and SEND_MAIL. Both settings are Booleans. This first enables or disables the use of Celery to send mail. When False, Django sends mail synchronously as it used to do. The second setting will not actually send mail (it doesn't care whether Celery is used or not) but instead print a log message.