Upgrading from 1.x¶

Djrill 2.0 includes some breaking changes from 1.x. These changes should have minimal (or no) impact on most Djrill users, but if you are upgrading please review the major topics below to see if they apply to you.

Djrill 1.4 tried to warn you if you were using Djrill features expected to change in 2.0. If you are seeing any deprecation warnings with Djrill 1.4, you should fix them before upgrading to 2.0. (Warnings appear in the console when running Django in debug mode.)

Please see the release notes for a list of new features and improvements in Djrill 2.0.

Dropped support for Django 1.3, Python 2.6, and Python 3.2¶

Although Djrill may still work with these older configurations, we no longer test against them. Djrill now requires Django 1.4 or later and Python 2.7, 3.3, or 3.4.

If you require support for these earlier versions, you should not upgrade to Djrill 2.0. Djrill 1.4 remains available on pypi, and will continue to receive security fixes.

Removed DjrillAdminSite¶

Earlier versions of Djrill included a custom Django admin site. The equivalent functionality is available in Mandrill’s dashboard, and Djrill 2.0 drops support for it.

Although most Djrill users were unaware the admin site existed, many did follow the earlier versions’ instructions to enable it.

If you have added DjrillAdminSite, you will need to remove it for Djrill 2.0.

In your urls.py:

from djrill import DjrillAdminSite  # REMOVE this
admin.site = DjrillAdminSite()  # REMOVE this

admin.autodiscover()  # REMOVE this if you added it only for Djrill

In your settings.py:

INSTALLED_APPS = (
    ...
    # If you added SimpleAdminConfig only for Djrill:
    'django.contrib.admin.apps.SimpleAdminConfig',  # REMOVE this
    'django.contrib.admin',  # ADD this default back
    ...
)

(These instructions assume you had changed to SimpleAdminConfig solely for DjrillAdminSite. If you are using it for custom admin sites with any other Django apps you use, you should leave it SimpleAdminConfig in place, but still remove the references to DjrillAdminSite.)

Added exception for invalid or rejected recipients¶

Djrill 2.0 raises a new djrill.MandrillRecipientsRefused exception when all recipients of a message are invalid or rejected by Mandrill. (This parallels the behavior of Django’s default SMTP email backend, which raises SMTPRecipientsRefused when all recipients are refused.)

Your email-sending code should handle this exception (along with other exceptions that could occur during a send). However, if you want to retain the Djrill 1.x behavior and treat invalid or rejected recipients as successful sends, you can set MANDRILL_IGNORE_RECIPIENT_STATUS to True in your settings.py.

Other 2.0 breaking changes¶

Code that will be affected by these changes is far less common than for the changes listed above, but they may impact some uses:

Removed unintended date-to-string conversion

If your code was inadvertently relying on Djrill to automatically convert date or datetime values to strings in merge_vars, metadata, or other Mandrill message attributes, you must now explicitly do the string conversion yourself. See Formatting Merge Data for an explanation. (Djrill 1.4 reported a DeprecationWarning for this case.)

(This does not affect send_at, where Djrill specifically allows date or datetime values.)

Removed DjrillMessage class

The DjrillMessage class has not been needed since Djrill 0.2. You should replace any uses of it with the standard EmailMessage class. (Djrill 1.4 reported a DeprecationWarning for this case.)

Removed DjrillBackendHTTPError

This exception was deprecated in Djrill 0.3. Replace uses of it with djrill.MandrillAPIError. (Djrill 1.4 reported a DeprecationWarning for this case.)

Refactored Djrill backend and exceptions

Several internal details of djrill.mail.backends.DjrillBackend and Djrill’s exception classes have been significantly updated for 2.0. The intent is to make it easier to maintain and extend the backend (including creating your own subclasses to override Djrill’s default behavior). As a result, though, any existing code that depended on undocumented Djrill internals may need to be updated.