django-templated-email 3.0.1

概述

django-templated-email旨在发送模板电子邮件。该库支持模板继承，添加cc和bcc收件人，可配置模板命名和位置。

send_templated_email方法可以视为电子邮件的render_to_response快捷方式。

确保您正在阅读正确的文档

develop分支：https://github.com/vintasoftware/django-templated-email/blob/develop/README.rst

stable pypi/master：https://github.com/vintasoftware/django-templated-email/blob/master/README.rst

需求

• Python (3.6, 3.7, 3.8, 3.9)

• Django (2.2, 3.1, 3.2)

我们强烈推荐并仅官方支持每个Python和Django系列的最新补丁版本。

入门 - 安装

安装

pip install django-templated-email

您可以将以下内容添加到您的settings.py文件中（但默认情况下它已经配置好了）

TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django.TemplateBackend'

# You can use a shortcut version
TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django'

# You can also use a class directly
from templated_email.backends.vanilla_django import TemplateBackend
TEMPLATED_EMAIL_BACKEND = TemplateBackend

发送模板化电子邮件

使用vanilla_django TemplateBackend后端示例用法

Python发送邮件

from templated_email import send_templated_mail
send_templated_mail(
        template_name='welcome',
        from_email='from@example.com',
        recipient_list=['to@example.com'],
        context={
            'username':request.user.username,
            'full_name':request.user.get_full_name(),
            'signup_date':request.user.date_joined
        },
        # Optional:
        # cc=['cc@example.com'],
        # bcc=['bcc@example.com'],
        # headers={'My-Custom-Header':'Custom Value'},
        # template_prefix="my_emails/",
        # template_suffix="email",
)

如果您需要更精细地控制发送电子邮件，可以使用get_templated_email，这将返回一个使用vanilla_django后端准备的django EmailMessage对象

from templated_email import get_templated_mail
get_templated_mail(
        template_name='welcome',
        from_email='from@example.com',
        to=['to@example.com'],
        context={
            'username':request.user.username,
            'full_name':request.user.get_full_name(),
            'signup_date':request.user.date_joined
        },
        # Optional:
        # cc=['cc@example.com'],
        # bcc=['bcc@example.com'],
        # headers={'My-Custom-Header':'Custom Value'},
        # template_prefix="my_emails/",
        # template_suffix="email",
)

您还可以使用cc和bcc收件人，例如使用cc=['example@example.com']。

{% block subject %}My subject for {{username}}{% endblock %}
{% block plain %}
  Hi {{full_name}},

  You just signed up for my website, using:
      username: {{username}}
      join date: {{signup_date}}

  Thanks, you rock!
{% endblock %}

{% block html %}
  <p>Hi {{full_name}},</p>

  <p>You just signed up for my website, using:
      <dl>
        <dt>username</dt><dd>{{username}}</dd>
        <dt>join date</dt><dd>{{signup_date}}</dd>
      </dl>
  </p>

  <p>Thanks, you rock!</p>
{% endblock %}

TEMPLATED_EMAIL_AUTO_PLAIN = False

def convert_html_to_text(html):
    ...

TEMPLATED_EMAIL_PLAIN_FUNCTION = convert_html_to_text

TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' #use '' for top level template dir, ensure there is a trailing slash
TEMPLATED_EMAIL_FILE_EXTENSION = 'email'

与Django Anymail一起使用

Anymail将多个交易电子邮件服务提供商（ESP）集成到Django中，提供了一个一致的API，允许您使用ESP添加的功能，而无需将代码锁定到特定的ESP。它支持Mailgun、Postmark、SendGrid、SparkPost等。

您可以使用它与django-templated-email，只需遵循他们的快速入门说明来配置它。

可选地，您可以使用他们的自定义EmailMessage类与django-templated-email一起使用，如下设置

# This replaces django.core.mail.EmailMessage
TEMPLATED_EMAIL_EMAIL_MESSAGE_CLASS='anymail.message.AnymailMessage'

# This replaces django.core.mail.EmailMultiAlternatives
TEMPLATED_EMAIL_EMAIL_MULTIALTERNATIVES_CLASS='anymail.message.AnymailMessage'

内联图像

您可以使用InlineImage类将内联图像添加到电子邮件中。

首先从文件或一个ImageField获取图像内容

# From a file
with open('pikachu.png', 'rb') as pikachu:
  image = pikachu.read()

# From an ImageField
# Suppose we have this model
class Company(models.Model):
  logo = models.ImageField()

image = company.logo.read()

然后创建一个InlineImage实例

from templated_email import InlineImage

inline_image = InlineImage(filename="pikachu.png", content=image)

现在在发送电子邮件时将对象传递到上下文中的模板

send_templated_mail(template_name='welcome',
                    from_email='from@example.com',
                    recipient_list=['to@example.com'],
                    context={'pikachu_image': inline_image})

最后，在您的模板的HTML模板块中添加图像

<img src="{{ pikachu_image }}">

注意：您添加到上下文中的所有InlineImage对象都将附加到电子邮件中，即使它们在模板中未被使用。

添加查看电子邮件的网页链接

# Add templated email to INSTALLED_APPS
INSTALLED_APPS = [
  ...
  'templated_email'
]

# and this to your url patterns
url(r'^', include('templated_email.urls', namespace='templated_email')),

# when sending the email use the *create_link* parameter.
send_templated_mail(
    template_name='welcome', from_email='from@example.com',
    recipient_list=['to@example.com'],
    context={}, create_link=True)

最后，在您的模板中添加此链接。

<!-- With the 'if' the link will only appear on the email. -->
{% if email_uuid %}
  <!-- Note: you will need to add your site since you will need to access
             it from the email -->
  You can view this e-mail on the web here:
  <a href="http://www.yoursite.com{% url 'templated_email:show_email' uuid=email_uuid %}">
    here
  </a>
{% endif %}

注意事项

• 已渲染的电子邮件副本将存储在数据库中。如果您发送太多电子邮件，这可能会导致数据库增长。您负责管理它。

• 如果您使用InlineImage，所有图像都将上传到您的媒体存储，请记住这一点。

基于类的视图

在表单提交后发送电子邮件是很常见的。我们包含了一个mixin，用于与继承自Django的FormMixin的任何视图一起使用。

在您的视图中添加mixin和常用的Django属性

from templated_email.generic_views import TemplatedEmailFormViewMixin

class AuthorCreateView(TemplatedEmailFormViewMixin, CreateView):
    model = Author
    fields = ['name', 'email']
    success_url = '/create_author/'
    template_name = 'authors/create_author.html'

默认情况下，模板将在其上下文中包含form_data（如果表单有效）或from_errors（如果表单无效）。

您可以在此处查看示例

现在您可以使用以下属性/方法来自定义其行为

属性

templated_email_template_name（如果您没有实现templated_email_get_template_names()则是强制性的）

指定您要用于电子邮件的模板名称的字符串。例如：templated_email_template_name = ‘welcome’。

templated_email_send_on_success（默认：True）

此属性告诉 django-templated-email 如果表单有效则发送电子邮件。

templated_email_send_on_failure（默认：False）

此属性告诉 django-templated-email 如果表单无效则发送电子邮件。

templated_email_from_email（默认：settings.TEMPLATED_EMAIL_FROM_EMAIL）

包含发送电子邮件的电子邮件地址的字符串。

方法

templated_email_get_template_names(self, valid)（如果不设置 templated_email_template_name 则是必填的）

如果方法返回一个字符串，它将使用它作为渲染电子邮件的模板。如果它返回一个列表，它将仅使用第一个存在的模板发送电子邮件。

templated_email_get_recipients(self, form)（必填）

返回电子邮件的收件人列表。例如

def templated_email_get_recipients(self, form):
    return [form.data['email']]

templated_email_get_context_data(**kwargs)（可选）

使用此方法向用于渲染模板的上下文添加额外数据。您应该通过调用 super 获取父类的上下文。例如

def templated_email_get_context_data(self, **kwargs):
    context = super(ThisClassView, self).templated_email_get_context_data(**kwargs)
    # add things to context
    return context

templated_email_get_send_email_kwargs(self, valid, form)（可选）

添加或更改用于发送电子邮件的 kwargs。您应该调用 super 获取默认 kwargs。例如

def templated_email_get_send_email_kwargs(valid, form):
  kwargs = super(ThisClassView, self).templated_email_get_send_email_kwargs(valid, form)
  kwargs['bcc'] = ['admin@example.com']
  return kwargs

templated_email_send_templated_mail(*args, **kwargs)（可选）

此方法调用 django-templated-email 的 send_templated_mail 方法。您可以更改此方法以使用 celery 的任务，例如，或处理错误。

未来计划

请参阅 https://github.com/vintasoftware/django-templated-email/issues?state=open

在第三方应用程序中使用 django_templated_email

如果您想使用 django_templated_email 来处理可重用应用程序中的邮件，请注意

• 您的 send_templated_mail 调用应该设置 template_dir 的值，这样您就可以将应用程序特定的模板副本保留在应用程序中（尽管如果将电子邮件模板存储在 <your app>/templates/templated_email 中，加载器将找到您的电子邮件模板，如果没有覆盖 TEMPLATED_EMAIL_TEMPLATE_DIR）

• 如果您设置了 template_dir（您应该这样做），请记住包括一个尾随斜杠，例如 ‘my_app_email/’

• 部署的应用程序可能使用不同的后端，该后端不使用 django 模板后端，因此请记住在 README 中提醒开发者，如果他们已经使用不同的后端使用 django_templated_email，他们需要确保他们的电子邮件提供商可以发送所有模板（理想情况下在方便的地方列出）

关于特定后端的一些说明

使用 vanilla_django

这是默认后端，因此不需要特殊配置，并且可以直接使用。默认情况下，它假设以下设置（如果您想覆盖它们）

TEMPLATED_EMAIL_TEMPLATE_DIR = 'templated_email/' #Use '' for top level template dir
TEMPLATED_EMAIL_FILE_EXTENSION = 'email'

出于兼容性目的，您可以在设置文件中指定电子邮件主题（但，首选方法是使用模板中的 {% block subject %}）

TEMPLATED_EMAIL_DJANGO_SUBJECTS = {
    'welcome':'Welcome to my website',
}

此外，您可以调用 send_templated_mail 并可选地覆盖以下参数

template_prefix='your_template_dir/'  # Override where the method looks for email templates (alternatively, use template_dir)
template_suffix='email'               # Override the file extension of the email templates (alternatively, use file_extension)
cc=['fubar@example.com']              # Set a CC on the mail
bcc=['fubar@example.com']             # Set a BCC on the mail
template_dir='your_template_dir/'     # Override where the method looks for email templates
connection=your_connection            # Takes a django mail backend connection, created using **django.core.mail.get_connection**
auth_user='username'                  # Override the user that the django mail backend uses, per **django.core.mail.send_mail**
auth_password='password'              # Override the password that the django mail backend uses, per **django.core.mail.send_mail**

发布此包的新版本

更新 CHANGELOG 文件。

执行以下命令

bumpversion [major,minor,patch]
python setup.py publish
git push origin --tags

商业支持

该项目，如其他 Vinta Software 开源项目一样，被 Vinta 的客户的多个产品使用。我们始终在寻找令人兴奋的工作，因此如果您需要任何商业支持，请随时联系：contact@vinta.com.br