Writing an HTML e-mail renderer plugin

An email renderer class controls how the HTML part of e-mails sent by pretix is built. The creation of such a plugin is very similar to creating an export output.

Please read Creating a plugin first, if you haven’t already.

Output registration

The email HTML renderer API does not make a lot of usage from signals, however, it does use a signal to get a list of all available email renderers. Your plugin should listen for this signal and return the subclass of pretix.base.email.BaseHTMLMailRenderer that we’ll provide in this plugin:

1from django.dispatch import receiver
2
3from pretix.base.signals import register_html_mail_renderers
4
5
6@receiver(register_html_mail_renderers, dispatch_uid="renderer_custom")
7def register_mail_renderers(sender, **kwargs):
8    from .email import MyMailRenderer
9    return MyMailRenderer

The renderer class

class pretix.base.email.BaseHTMLMailRenderer

The central object of each email renderer is the subclass of BaseHTMLMailRenderer.

BaseHTMLMailRenderer.event

The default constructor sets this property to the event we are currently working for.

BaseHTMLMailRenderer.identifier

A short and unique identifier for this renderer. This should only contain lowercase letters and in most cases will be the same as your package name or prefixed with your package name.

This is an abstract attribute, you must override this!

BaseHTMLMailRenderer.verbose_name

A human-readable name for this renderer. This should be short but self-explanatory.

This is an abstract attribute, you must override this!

BaseHTMLMailRenderer.thumbnail_filename

A file name discoverable in the static file storage that contains a preview of your renderer. This should be with aspect resolution 4:3.

This is an abstract attribute, you must override this!

BaseHTMLMailRenderer.is_available

This renderer will only be available if this returns True. You can use this to limit this renderer to certain events. Defaults to True.

BaseHTMLMailRenderer.render(plain_body: str, plain_signature: str, subject: str, order=None, position=None) → str

This method should generate the HTML part of the email.

Parameters:

  • plain_body – The body of the email in plain text.

  • plain_signature – The signature with event organizer contact details in plain text.

  • subject – The email subject.

  • order – The order if this email is connected to one, otherwise None.

  • position – The order position if this email is connected to one, otherwise None.

Returns:

An HTML string

This is an abstract method, you must implement this!

Helper class for template-base renderers

The email renderer that ships with pretix is based on Django templates to generate HTML. In case you also want to render emails based on a template, we provided a ready-made base class TemplateBasedMailRenderer that you can re-use to perform the following steps:

  • Convert the body text and the signature to HTML using our markdown renderer

  • Render the template

  • Call inlinestyler to convert all <style> style sheets to inline style="" attributes for better compatibility

To use it, you just need to implement some variables:

1class ClassicMailRenderer(TemplateBasedMailRenderer):
2    verbose_name = _('pretix default')
3    identifier = 'classic'
4    thumbnail_filename = 'pretixbase/email/thumb.png'
5    template_name = 'pretixbase/email/plainwrapper.html'

The template is passed the following context variables:

site

Name of the pretix installation (settings.PRETIX_INSTANCE_NAME)

site_url

Root URL of the pretix installation (settings.SITE_URL)

body

The body as markdown (render with {{ body|safe }})

subject

The email subject

color

The primary color of the event

event

The Event object

signature (optional, only if configured)

The signature with event organizer contact details as markdown (render with {{ signature|safe }})

order (optional, only if applicable)

The Order object

position (optional, only if applicable)

The OrderPosition object