邮件发送器¶

常见邮箱SMTP配置与授权码获取¶

以下为主流邮箱（QQ、163、Outlook、Gmail）SMTP服务器参数及授权码获取方法，便于快速配置。

邮箱类型	SMTP服务器	端口	加密方式	用户名	密码类型
QQ邮箱	smtp.qq.com	465	SSL	完整邮箱地址	授权码
163邮箱	smtp.163.com	465	SSL	完整邮箱地址	授权码
Outlook	smtp.office365.com	587	TLS	完整邮箱地址	应用专用密码
Gmail	smtp.gmail.com	465/587	SSL/TLS	完整邮箱地址	应用专用密码

QQ邮箱¶

登录QQ邮箱网页版，点击右上角"设置">"账户"。
在"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"处，勾选"开启SMTP服务"，保存。
按提示进行手机验证，获取授权码（此码即为SMTP登录密码）。
邮件客户端配置时，用户名为完整邮箱，密码为授权码。
详细官方说明：QQ邮箱帮助中心
微软官方Outlook对接QQ邮箱说明（含授权码获取步骤）：查看

163邮箱¶

登录163邮箱网页版，点击"设置">"POP3/SMTP/IMAP"。
开启"SMTP服务"，如需验证请按提示操作。
获取授权码（部分账号需手机验证），此码即为SMTP登录密码。
邮件客户端配置时，用户名为完整邮箱，密码为授权码。
官方帮助中心：网易邮箱帮助
参考博客：Mailbird 163邮箱配置

Outlook（含Office365/Hotmail）¶

登录Microsoft账户（https://account.microsoft.com/），进入"安全性"设置。
开启"两步验证"。
在"安全信息"页面，选择"添加方法">"应用专用密码"，生成专用密码。
邮件客户端配置时，用户名为完整邮箱，密码为应用专用密码。
微软官方说明：Outlook应用专用密码指南
Lifewire教程：如何为Outlook.com创建应用专用密码

Gmail¶

登录Google账户，进入"安全性"设置。
开启"两步验证"。
在"安全性"页面搜索"应用专用密码"，生成专用密码。
邮件客户端配置时，用户名为完整邮箱，密码为应用专用密码。
官方说明：Google账户应用专用密码
参考博客：Gmail SMTP配置详解

FAQ¶

Q1：什么是授权码/应用专用密码？ A：授权码/应用专用密码是邮箱服务商为提升安全性而生成的专用密码，用于第三方应用（如邮件客户端、自动化脚本）登录邮箱，不能用普通登录密码代替。

Q2：为什么要用授权码/应用专用密码？ A：开启两步验证后，普通密码无法直接用于SMTP等第三方服务，必须使用授权码/应用专用密码，保障账户安全。

Q3：授权码/应用专用密码丢失怎么办？ A：可随时在邮箱安全设置中重新生成新的授权码/应用专用密码，原有的可作废。

Q4：配置失败常见原因有哪些？ A：常见原因包括未开启SMTP服务、未使用授权码/专用密码、端口/加密方式配置错误、邮箱被限制登录等。

如遇特殊问题，建议优先查阅各邮箱官方帮助中心或联系邮箱服务商客服。

EmailSender 模块提供了一套完整且易于使用的邮件发送解决方案，它内置了对多种主流邮箱服务商的支持。

发送器基类¶

所有具体的发送器都继承自 EmailSender 抽象基类。

`EmailSender(username, password, use_tls=True, smtp_server=None, smtp_port=None, *args, **kwargs)` ¶

Bases: ABC

邮件发送器抽象基类.

定义了发送邮件的标准接口，所有具体的邮箱服务商实现都需要继承此类. 这个基类处理了通用的邮件构建和发送逻辑，子类只需提供特定于服务商的 SMTP服务器地址和端口号即可.

Attributes:

Name	Type	Description
`username`	`str`	邮箱用户名（通常是完整的邮箱地址）.
`password`	`str`	邮箱密码或授权码/应用密码.
`use_tls`	`bool`	是否使用TLS加密连接.
`smtp_server`	`str`	SMTP服务器地址.
`smtp_port`	`int`	SMTP服务器端口.

Raises:

Type	Description
`ValueError`	如果用户名或密码为空.

初始化邮件发送器.

Parameters:

Name	Type	Description	Default
`username`	`str`	邮箱用户名/邮箱地址	required
`password`	`str`	邮箱密码或授权码	required
`use_tls`	`bool`	是否使用TLS加密连接，默认为True	`True`
`smtp_server`	`str \| None`	SMTP服务器地址，如果不提供则使用默认值	`None`
`smtp_port`	`int \| None`	SMTP服务器端口，如果不提供则使用默认值	`None`
`*args`		其他位置参数	`()`
`**kwargs`		其他关键字参数	`{}`

Raises:

Type	Description
`ValueError`	当用户名或密码为空时抛出

Functions¶

`send(email, sender=None, to=None)` ¶

发送邮件.

Parameters:

Name	Type	Description	Default
`email`	`Email`	要发送的邮件对象	required
`sender`	`str \| None`	发送者邮箱地址，如果为None则使用初始化时的username	`None`
`to`	`list[str] \| None`	接收者邮箱地址列表，如果为None则发送给sender	`None`

Raises:

Type	Description
`ValueError`	当邮件对象为None时抛出
`SMTPException`	SMTP发送错误
`Exception`	其他发送错误

Examples:

Python Console Session

>>> sender = QQEmailSender("user@qq.com", "password")
>>> email = Email("测试邮件")
>>>
>>> # 发送给自己
>>> sender.send(email)
>>>
>>> # 发送给指定收件人
>>> sender.send(email, to=["recipient@example.com"])
>>>
>>> # 指定发送者和收件人
>>> sender.send(email, sender="custom@qq.com", to=["recipient@example.com"])

工厂函数¶

为了方便使用，我们推荐使用 create_email_sender 工厂函数来创建发送器实例。

`create_email_sender(provider, username, password, **kwargs)` ¶

工厂函数，根据服务商名称快速创建对应的邮件发送器实例.

这是一个便捷的辅助函数，让你无需直接导入和实例化特定的发送器类. 它通过一个字符串标识来选择正确的发送器，特别适合在配置文件中指定服务商的场景.

Parameters:

Name	Type	Description	Default
`provider`	`str`	邮箱服务商的标识符.支持的值（不区分大小写）包括： 'qq', 'netease', '163', '126', 'outlook', 'hotmail', 'gmail'.	required
`username`	`str`	邮箱账户，通常是完整的邮箱地址.	required
`password`	`str`	邮箱的授权码或应用密码.	required
`**kwargs`		其他关键字参数，将直接传递给所选发送器类的构造函数.	`{}`

Returns:

Name	Type	Description
`EmailSender`	`EmailSender`	一个具体的邮件发送器实例 (例如 `QQEmailSender`).

Raises:

Type	Description
`ValueError`	如果提供的 `provider` 名称不被支持.

Examples:

Python

from email_widget import Email, create_email_sender
import os

# 从配置或环境变量中读取服务商和凭证
email_provider = os.getenv("EMAIL_PROVIDER", "qq") # e.g., 'qq' or 'gmail'
email_user = os.getenv("EMAIL_USER")
email_password = os.getenv("EMAIL_PASSWORD")

# 使用工厂函数创建发送器
try:
    sender = create_email_sender(
        provider=email_provider,
        username=email_user,
        password=email_password
    )

    email = Email(f"来自 {email_provider.upper()} 的邮件")
    email.add_text("通过工厂函数创建的发送器.")
    sender.send(email, to=["test@example.com"])
    print("邮件发送成功！")

except ValueError as e:
    print(f"配置错误: {e}")
except Exception as e:
    print(f"发送失败: {e}")

具体实现¶

以下是针对不同邮箱服务商的具体实现类。通常你只需要通过工厂函数来使用它们。

QQEmailSender¶

Bases: EmailSender

QQ邮箱发送器.

专门用于通过 QQ 邮箱（包括企业邮箱）发送邮件. 它预设了 QQ 邮箱的 SMTP 服务器地址和推荐的端口.

重要提示

必须使用授权码: 出于安全原因，QQ邮箱的SMTP服务要求使用“授权码”而非你的登录密码.你需要在QQ邮箱的“设置”->“账户”页面下生成此授权码.
开启SMTP服务: 请确保你已经在QQ邮箱设置中开启了IMAP/SMTP服务.

Examples:

Python

from email_widget import Email, QQEmailSender
import os

# 建议从环境变量读取敏感信息
# export EMAIL_USER="your_account@qq.com"
# export EMAIL_AUTH_CODE="your_generated_auth_code"

qq_user = os.getenv("EMAIL_USER")
auth_code = os.getenv("EMAIL_AUTH_CODE")

# 创建邮件内容
email = Email("来自QQ邮箱的报告")
email.add_text("这是一封通过 EmailWidget 发送的测试邮件.")

# 初始化QQ邮箱发送器
sender = QQEmailSender(username=qq_user, password=auth_code)

# 发送邮件给一个或多个收件人
try:
    sender.send(email, to=["recipient1@example.com", "recipient2@example.com"])
    print("邮件发送成功！")
except Exception as e:
    print(f"邮件发送失败: {e}")

初始化QQ邮箱发送器.

Parameters:

Name	Type	Description	Default
`username`	`str`	QQ邮箱地址	required
`password`	`str`	QQ邮箱授权码（非登录密码）	required
`use_tls`	`bool`	是否使用TLS加密，默认为True	`True`
`*args`		其他位置参数	`()`
`**kwargs`		其他关键字参数	`{}`

Functions¶

NetEaseEmailSender¶

Bases: EmailSender

网易邮箱发送器.

支持网易旗下的 163、126 和 yeah.net 邮箱. 它会自动根据你的邮箱地址后缀选择正确的SMTP服务器.

重要提示

必须使用授权码: 与QQ邮箱类似，网易邮箱也需要使用专用的“客户端授权密码”，而不是你的邮箱登录密码.
开启SMTP服务: 请在你的网易邮箱设置中开启POP3/SMTP/IMAP服务.
SSL连接: 网易邮箱的SMTP服务主要使用SSL加密（端口465），因此默认 use_tls 为 False.

Examples:

Python

from email_widget import Email, NetEaseEmailSender
import os

# 使用163邮箱
user_163 = os.getenv("NETEASE_USER_163") # e.g., "my_account@163.com"
auth_code_163 = os.getenv("NETEASE_AUTH_CODE_163")

email = Email("来自163邮箱的问候")
email.add_text("这是通过 NetEaseEmailSender 发送的邮件.")

sender = NetEaseEmailSender(username=user_163, password=auth_code_163)

try:
    sender.send(email, to=["friend@example.com"])
    print("163邮件发送成功！")
except Exception as e:
    print(f"邮件发送失败: {e}")

初始化网易邮箱发送器.

Parameters:

Name	Type	Description	Default
`username`	`str`	网易邮箱地址	required
`password`	`str`	网易邮箱授权码	required
`use_tls`	`bool`	是否使用TLS加密，默认为False（网易邮箱使用SSL）	`False`
`*args`		其他位置参数	`()`
`**kwargs`		其他关键字参数	`{}`

Note

网易邮箱只支持SSL连接（端口465），建议保持use_tls=False.

Functions¶

OutlookEmailSender¶

Bases: EmailSender

Outlook邮箱发送器.

支持微软旗下的 Outlook.com 和 Hotmail.com 邮箱服务.

重要提示

建议使用应用密码: 如果你为你的微软账户开启了两步验证，你需要创建一个"应用密码"并在程序中使用它，而不是你的常规登录密码.
STARTTLS连接: Outlook 的 SMTP 服务只支持 STARTTLS 加密（端口587），不支持直接SSL连接.
启用SMTP: 可能需要在 Outlook.com 的"邮件"->"同步电子邮件"设置中，确保POP和IMAP访问已启用.

Examples:

Python

from email_widget import Email, OutlookEmailSender
import os

outlook_user = os.getenv("OUTLOOK_USER") # e.g., "your_id@outlook.com"
app_password = os.getenv("OUTLOOK_APP_PASSWORD")

email = Email("Outlook Test Mail")
email.add_text("This is a test email sent via OutlookEmailSender.")

sender = OutlookEmailSender(username=outlook_user, password=app_password)

try:
    sender.send(email, to=["colleague@example.com"])
    print("Outlook 邮件发送成功！")
except Exception as e:
    print(f"邮件发送失败: {e}")

初始化Outlook邮箱发送器.

Parameters:

Name	Type	Description	Default
`username`	`str`	Outlook邮箱地址	required
`password`	`str`	Outlook邮箱应用密码	required
`use_tls`	`bool`	是否使用TLS加密，此参数会被忽略（Outlook只支持STARTTLS）	`True`
`*args`		其他位置参数	`()`
`**kwargs`		其他关键字参数	`{}`

Note

Outlook邮箱只支持STARTTLS连接，不支持直接SSL连接.

Functions¶

GmailSender¶

Bases: EmailSender

Gmail邮箱发送器.

用于通过 Google 的 Gmail 服务发送邮件.

重要提示

必须使用应用专用密码: 由于安全策略，你必须为你的Google账户启用两步验证（2-Step Verification），然后生成一个“应用专用密码”（App Password）来在第三方应用（如本程序）中使用.
连接方式: Gmail 同时支持 TLS (端口 587) 和 SSL (端口 465) 连接.默认推荐使用 use_tls=True.

Examples:

Python

from email_widget import Email, GmailSender
import os

gmail_user = os.getenv("GMAIL_USER") # e.g., "your.name@gmail.com"
app_password = os.getenv("GMAIL_APP_PASSWORD")

email = Email("Report from Gmail")
email.add_text("This report was sent using the GmailSender.")

sender = GmailSender(username=gmail_user, password=app_password)

try:
    sender.send(email, to=["manager@example.com"])
    print("Gmail 邮件发送成功！")
except Exception as e:
    print(f"邮件发送失败: {e}")

初始化Gmail发送器.

Parameters:

Name	Type	Description	Default
`username`	`str`	Gmail邮箱地址	required
`password`	`str`	Gmail应用专用密码	required
`use_tls`	`bool`	是否使用TLS加密，默认为True（推荐TLS连接）	`True`
`*args`		其他位置参数	`()`
`**kwargs`		其他关键字参数	`{}`

Note

Gmail支持TLS（端口587）和SSL（端口465），推荐使用TLS.

邮件发送器¶

常见邮箱SMTP配置与授权码获取¶

QQ邮箱¶

163邮箱¶

Outlook（含Office365/Hotmail）¶

Gmail¶

FAQ¶

发送器基类¶

EmailSender(username, password, use_tls=True, smtp_server=None, smtp_port=None, *args, **kwargs) ¶

Functions¶

send(email, sender=None, to=None) ¶

工厂函数¶

create_email_sender(provider, username, password, **kwargs) ¶

具体实现¶

QQEmailSender¶

Functions¶

NetEaseEmailSender¶

Functions¶

OutlookEmailSender¶

Functions¶

GmailSender¶

Functions¶

`EmailSender(username, password, use_tls=True, smtp_server=None, smtp_port=None, *args, **kwargs)` ¶

`send(email, sender=None, to=None)` ¶

`create_email_sender(provider, username, password, **kwargs)` ¶