Django-Templated-Email 技术文档

1. 安装指南

首先，确保你的开发环境满足以下要求：

• Python 版本：3.6, 3.7, 3.8, 3.9, 3.10, 3.11
• Django 版本：3.2, 4.0, 4.1

推荐使用最新版本的 Python 和 Django。

安装 Django-Templated-Email：

pip install django-templated-email

在项目的 settings.py 文件中，你可以添加以下配置（但默认情况下无需配置即可使用）：

TEMPLATED_EMAIL_BACKEND = 'templated_email.backends.vanilla_django.TemplateBackend'

也可以使用简写形式或直接指定类：

from templated_email.backends.vanilla_django import TemplateBackend
TEMPLATED_EMAIL_BACKEND = TemplateBackend

2. 项目使用说明

Django-Templated-Email 是一个面向 Django 的模板化邮件发送类。以下是一个使用示例：

from templated_email import send_templated_mail

send_templated_mail(
    template_name='welcome',
    from_email='[e-mail]',
    recipient_list=['[e-mail]'],
    context={
        'username': request.user.username,
        'full_name': request.user.get_full_name(),
        'signup_date': request.user.date_joined
    }
)

你可以通过 cc 和 bcc 参数添加抄送和密送收件人。

邮件模板需要放置在 templated_email/ 目录下。例如，后端会查找 my_app/templates/templated_email/welcome.email：

{% 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 %}

如果需要 HTML 版本的邮件，可以使用 html block：

{% 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 %}

如果未指定纯文本部分，且 html2text 包已安装，系统将自动从 HTML 部分生成纯文本部分。

3. 项目 API 使用文档

以下是主要的 API 方法：

• send_templated_mail: 直接发送模板邮件。
• get_templated_mail: 获取一个预先配置好的 EmailMessage 对象。

示例：

from templated_email import get_templated_mail

email = get_templated_mail(
    template_name='welcome',
    from_email='[e-mail]',
    to=['[e-mail]'],
    context={
        'username': request.user.username,
        'full_name': request.user.get_full_name(),
        'signup_date': request.user.date_joined
    }
)
email.send()

4. 项目安装方式

请遵循以下步骤安装 Django-Templated-Email：

• 使用 pip install django-templated-email 命令安装包。
• 在项目的 settings.py 文件中配置邮件后端（可选）。
• 在需要发送邮件的地方，调用 send_templated_mail 或 get_templated_mail 方法。

确保阅读了最新的文档以获取最新的安装和使用指南。