API Reference¶

That section is not didactic at all, just listing the documentation of every bit of code for a complete reference.

Template tags¶

Adding {% load wailer %} in your template will provide you with different tags that can be helpful in the context of emails.

`email_style`¶

In order to load some CSS in a HTML template, you may invoke the email_style template. This will look for this specified CSS file in your static files and will inline it inside the HTML.

my_app/static/style.css

h1 {
    color: red;
}

my_app/templates/template.html

{% load wailer %}

{% email_style "style.css" %}

<h1>Title</h1>

Note

Style files are resolved using Django’s static files system

`make_absolute`¶

In order to make an URL absolute, you can use this tag which will prepend the URL with the website’s domain. You can check how the domain is determined in the tutorial.

{% load wailer %}

{% make_absolute "/foo/bar" %}
<!-- Will output "https://my-app.com/foo/bar -->

`absolute_url`¶

Works exactly like Django’s url template tag with the only difference being the fact that all URLs generated will be absolute. The domain name of those URLs will be determined in the way that is explained in the tutorial.

{% load wailer %}

{% url "product_page" product.id %}
<!-- Instead of /product/42/ will output https://my-app.com/product/42/ -->

Models¶

Those Django models are the core of the system. They both store the data in database and perform the various plumbing tasks, including actually sending messages.

Base Message¶

Since emails and SMSes are very similar concept, this base class will hold common concepts between the two, letting them specialize only on some core aspects.

class wailer.models.BaseMessage(*args, **kwargs)¶: Common fields between emails and SMSs

Email¶

Specialization of the base message to be able to send emails.

class wailer.models.Email(*args, **kwargs)¶

Sent emails and a way to recompose/re-render them.

classmethod send(type_: str, data: Union[str, int, float, bool, None, Mapping[str, Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]], Sequence[Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]]], user: Optional[Model] = None) → Email¶

Call this to immediately send the email with the appropriate data.

The type must be registered in the WAILER_EMAIL_TYPES settings and must implement the EmailType interface.

Parameters

type – Name of the registered email type
data – Data that the email type will be using, but also that will be saved into DB for restitution later (so must be serializable to JSON).
user – User concerned by this email. Not mandatory but it’s recommended to fill it up when sending an email to a user from the DB so that it’s easy to delete emails (and thus their content) associated to this user when they delete their account or exert any kind of GDPR rights.

email¶: Generates the email “type” object from this model

base_url¶: A shortcut to get the underlying email’s base URL

link_html¶: Returns a relative link for this email to be seen in a browser in HTML format. Useful for debugging and for inclusion in said emails.

link_text¶: Returns a relative link for this email to be seen in a browser in text format. Useful for debugging and for inclusion in said emails.

send_now()¶: Sends the email now. Called under the hood by send(). The _now part suggests that there will maybe be a _later strategy but not yet (nor ever?)

exception DoesNotExist¶

exception MultipleObjectsReturned¶

Interfaces¶

Those interfaces help you implement your own custom behaviors.

SMS/Email common class¶

class wailer.interfaces.BaseMessageType(message: BaseMessage)¶

Common stuff between SMS and Email

property data: Union[str, int, float, bool, None, Mapping[str, Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]], Sequence[Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]]]¶: Shortcut to access the message’s data

property context: Union[str, int, float, bool, None, Mapping[str, Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]], Sequence[Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]]]¶: Shortcut to access the message’s context

abstract get_locale() → str¶

You must implement this to indicate which locale this message will be sent with. The locale will be set to this during all subsequent calls (by example while rendering templates).

Let’s note that the message’s context is NOT available at this stage so you should definitely not rely on it. You can use self.data though.

abstract get_context() → Mapping[str, Union[str, int, float, bool, None, Mapping[str, Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]], Sequence[Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]]]]¶

You must implement this method in order to provide a context for your templates when they get rendered.

It’s important to mention that this method will be called only once at the time of creation of this email. Indeed, emails are immutable once sent so there is no reason that the context should change between calls. This prevents from having the content of the email changing.

As a result, the value out of this function will be stored into DB and must be JSON-serializable.

This function is called within the locale returned by BaseMessageType.get_locale()

get_base_url() → str¶

Guesses the base URL for all links and images inside the email. This uses several strategies:

If there is a WAILER_BASE_URL declared in the settings then we’re just going to use that
Otherwise we turn to the sites framework (if installed)
- The WAILER_SITE_ID can force the ID of the site we’re using
- Which falls back to the default site. Since we don’t have a guarantee to be running in a request here, you better be careful with that
- To be noted that the scheme is determined automatically. If the domain is local then it’s HTTP and otherwise it’s HTTPS. That is not covering 100% of the cases but if you feel like you need something more precise feel free to set WAILER_BASE_URL or to override this method
Otherwise we just fail because there is now ay to guess

You can override this method to implement whatever behavior you desire instead of this one.

Email types¶

class wailer.interfaces.EmailType(message: BaseMessage)¶

Implement this interface in order to provide your own email type.

abstract get_to() → str¶: Return here who you want to send that email to

abstract get_subject() → str¶: Return here the subject of the email

abstract get_template_html_path() → str¶: Implement if you want a HTML part of the email. Or don’t if you don’t want. It’s just that the email provider will usually enforce at least a HTML or a text content, so make sure to have at least one.

abstract get_template_text_path() → str¶: Implement if you want a text part of the email. Or don’t if you don’t want. It’s just that the email provider will usually enforce at least a HTML or a text content, so make sure to have at least one.

get_from() → str¶: Defaulting to Django’s default, override for something else

get_text_content() → str¶: Renders the text template. Override if you want to render differently. If you override then you might not need get_template_text_path() or get_template_context() (but it’s your call).

get_html_content() → str¶

Renders the HTML template. Override if you want to render differently. If you override then you might not need get_template_html_path() or get_template_context() (but it’s your call).

HTML is transformed using Premailer to do various email things like inlining the CSS and changing relative links to absolute links.

If the HTML template file name ends up in .mjml then it will be rendered through MJML first.

get_template_context() → Mapping¶

The context of templates shall be the one from get_context(), with on top of that a reference to the message object in case you need it.

Feel free to override and add whatever you need, however I’m not too sure why you would do that. Better do things in get_context() for the protection it offers.

get_attachments() → Iterable[EmailAttachment]¶: Override this to add attachments to the email. Return an iterable of EmailAttachment objects.

Attachments¶

class wailer.interfaces.EmailAttachment(filename: str, content: bytes, mimetype: str)¶

Represents an attachment for an email

filename: str¶: Alias for field number 0

content: bytes¶: Alias for field number 1

mimetype: str¶: Alias for field number 2

SMS types¶

class wailer.interfaces.SmsType(message: BaseMessage)¶

abstract get_content() → str¶: Implement this to return the text content of the SMS

abstract get_to() → PhoneNumber¶: Implement this to return the phone number to which the SMS must be sent to.

abstract get_from() → str¶: Returns an ID for your SMS sender. That’s probably dependent on what your provider(s) will accept. Up to you!

make_absolute(url: str)¶

Convenience function to transform an URL into something absolute with the same logic as for emails.

Parameters: url – Any URL

Type aliases¶

Those are type aliases that are used throughout the app for clarity.

JSON Type¶

This one mimics the JSON spec to indicate that this value should be matching concepts that exist in JSON.

wailer.interfaces.JsonType¶: alias of Union[str, int, float, bool, None, Mapping[str, JsonType], Sequence[JsonType]]

API Reference¶

Template tags¶

`email_style`¶

`make_absolute`¶

`absolute_url`¶

Models¶

Base Message¶

Email¶

Interfaces¶

SMS/Email common class¶

Email types¶

Attachments¶

SMS types¶

Type aliases¶

JSON Type¶

Wailer

Navigation

Related Topics

API Reference¶

Template tags¶

email_style¶

make_absolute¶

absolute_url¶

Models¶

Base Message¶

Email¶

Interfaces¶

SMS/Email common class¶

Email types¶

Attachments¶

SMS types¶

Type aliases¶

JSON Type¶

`email_style`¶

`make_absolute`¶

`absolute_url`¶