Jinja Templating#

Red Mail uses Jinja for templating the HTML and text bodies. This enables a lot of features out-of-the box. See Jinja documentation for more details of the templating.

Parametrizing Emails#

You can also parametrize an email using Jinja parameters:

email.send(
    subject='email subject',
    receivers=['first.last@example.com'],
    html="""
        <h1>Hi {{ client }},</h1>
        <p>we are opening the source of {{ project_name }}.</p>
        <p>Kind regards
        <br>{{ company }}</p>
    """,
    text="""
        Hi {{ client }},
        we are opening the source of {{ project_name }}.

        Kind regards,
        {{ company }}
    """,
    body_params={
        'client': 'Customer LTD',
        'project_name': 'Red Mail',
        'company': 'Company LTD',
    }
)

Both text and HTML body support Jinja parametrization.

Default Parameters#

There are also some parameters passed automatically for convenience. You can always override these if you wish. Here is a quick example of some of them:

email.send(
    subject='email subject',
    receivers=['first.last@example.com'],
    html="""
        <h1>Hi,</h1>
        <p>nice to meet you</p>
        <p>Kind regards
        <br>{{ sender.full_name }}</p>
    """,
)

Here is a list of default parameters:

Parameter Name

Type

Description

sender

redmail.models.EmailAddress

Format class of the email sender

error

redmail.models.Error

Format class of the current exception (if any)

node

str

Computer’s network name (if can be determined)

user

str

Name of the current user logged on the computer

now

datetime.datetime

Current date and time

Including Loops and Control Flow#

As the bodies use Jinja in the background, you can use various additional features such as if statements, for loops, macros etc. Here is a quick illustration:

email.send(
    subject='email subject',
    receivers=['first.last@example.com'],
    html="""
        <h1>Hi!</h1>
        <p>
            Soon you will meet my team.
            Here is a quick introduction:
        </p>
        <ul>
            {% for colleague in colleagues.items() %}
                <li>{{ colleague }}: {{ description }}</li>
            {% endfor %}
        </ul>
        {% if confidential %}
            <p>
                This message is confidential.
            </p>
        {% endif %}

        <p>Kind regards
        <br>{{ sender.full_name }}</p>
    """,
    body_params={
        'colleagues': {'Jack': 'Developer', 'John': 'CEO'},
        'confidential': False
    }
)

Please see Jinja documentation for more.

Pass Unescaped Content#

In case you need to include parts that should not be processed by Jinja, you may pass them using markupsafe.Markup:

from markupsafe import Markup

email.send(
    subject='email subject',
    receivers=['first.last@example.com'],
    html="""
        <h1>Hi,</h1>
        <p>{{ raw_content }}</p>
        <p>Kind regards
        <br>{{ sender.full_name }}</p>
    """,
    body_params={
        'raw_content': Markup("<strong>this text is passed unescaped as is</strong>")
    }
)

Warning

For HTML, content only from trusted sources should be left unescaped.

Disabling Jinja#

In case you wish to pass raw text/HTML and don’t want to use Jinja to render the bodies, you may also disable it:

email.send(
    subject='email subject',
    receivers=['first.last@example.com'],
    text="""
        Hi,
        {{ these brackets are not processed }}
    """,
    html="""
        <h1>Hi!</h1>
        <p>
            {{ these brackets are not processed }}
        </p>
    """,
    use_jinja=False
)

You may also disable Jinja for all sent emails without passing the argument:

email.use_jinja = False