EZGmail

一个自2024年7月起真正工作的Pythonic接口，用于Gmail API。

EZGmail 是一个比使用官方Google API更易于使用，用于执行常见电子邮件任务（如发送电子邮件、搜索您的收件箱、阅读电子邮件等）的Pythonic接口。

还请查看 EZSheets 以使用Python编辑Google Sheets。

安装和设置

通常，您必须为您Python程序 创建Python虚拟环境 并安装包。从终端/命令行，激活虚拟环境，然后运行 pip install ezgmail（在Windows上）或 pip3 install ezgmail（在macOS或Linux上）来安装EZGmail。

要让您的Python脚本使用EZGmail访问Gmail帐户，您需要一个凭据JSON文件和一个令牌JSON文件。这需要使用您的Gmail帐户在Google Cloud服务上进行一次性的设置。如果您有一个Gmail帐户，您可以这样做，这是免费的（除非您每天通过发送数千封电子邮件大量使用Gmail API。）以下章节详细说明了这一步骤。您只需进行这些设置步骤一次，然后您的Python程序就可以轻松地使用EZGmail。这些说明最后更新于2024年7月。

对于测试，我建议使用测试Gmail帐户而不是您的实际Gmail帐户，这样您就不会不小心删除真实电子邮件。

一般设置概述

• 从 https://console.cloud.google.com 创建一个新的Google Cloud项目
• 在API & Services > 启用API & services页面上启用Gmail API。
• 从API & Services > OAuth同意屏幕页面上配置OAuth同意屏幕。
• 在“API & 服务 > 凭据”页面，通过https://mail.google.com/作用域创建新的OAuth 2.0客户端ID。
• 下载client_secret_*.json凭据文件。
• 在Python交互式shell中，从与凭据文件相同的当前工作目录运行import ezgmail。
• 这将在浏览器中打开OAuth同意屏幕。授权应用程序以生成token.json文件。
• 当token.json文件位于当前工作目录时，您的Python程序现在可以使用ezgmail模块。

创建新的Google Cloud项目

首先，您需要设置Google Cloud项目。在浏览器中，转到https://console.cloud.google.com并使用用户名和密码登录您的Google账户。（您的应用程序可以连接到任何Gmail账户，但此Google账户将用于管理EZGmail对Google API的访问。）您将被带到入门页面。在页面顶部，点击“选择项目”。在出现的弹出窗口中，点击“新建项目”。

这会带您到一个新项目页面。系统将为您生成一个项目名称，如"My Project 23135"。还会为您随机生成一个项目ID，如"macro-nuance-362516"。这些名称不会显示在您的Python脚本用户面前，您可以使用任何名称。您稍后可以更改项目名称，但不能更改项目ID。我直接使用了系统生成的默认名称。位置可以保留为“无组织”。请注意，在免费层中，截至2022年9月，您只能创建12个项目，但您只需要一个用于所有您想要创建的Python脚本。点击蓝色的“创建”按钮来创建项目。

免费Google账户可以有最多10个项目。

再次点击页面顶部的“选择项目”，选择您刚刚创建的项目。您将被带到该Google Cloud项目的仪表板页面。接下来，您需要为您的项目启用Gmail API。

为您的项目启用Gmail API

在https://console.cloud.google.com页面上，点击左上角的导航按钮（图标为三个水平条纹，常称为“汉堡”图标）。导航到“API & 服务”然后到“库”，进入API库页面。有多个Google API，如Gmail、Google Maps、Google Cloud Storage等。我们需要允许我们的项目使用Gmail API。

向下滚动并找到“Gmail API”，点击它，或者将“Gmail API”输入搜索栏以找到它。这会带您到Gmail API页面。点击蓝色的“启用”按钮，以启用您的Google Cloud项目使用Gmail API。您将被重定向到“API & 服务 > 已启用API & 服务”页面，在那里您可以找到有关您的Python脚本使用此API频率的信息。（您可能想在这里回到“API & 服务 > 库”页面，启用Google Sheets API和Google Drive API，如果您想使用ezsheets Python模块从Python脚本中编辑Google Sheets电子表格的话。）

接下来，您需要配置您项目的OAuth同意屏幕。

配置您项目的OAuth同意屏幕

点击左上角的导航按钮，然后导航到“API & 服务”然后到“OAuth同意屏幕”。当您或您的Python脚本用户第一次使用ezgmail时，将出现同意屏幕。如果您使用的是未设置为Google Workspace用户的免费Gmail账户，您将不得不选择外部用户类型选项，而不是内部用户类型。这些在Google的设置OAuth同意屏幕帮助页面上有进一步解释。

在第一步“OAuth同意屏幕”中，选择“外部”并点击蓝色的“创建”按钮。您将被带到设置OAuth同意屏幕外观的页面。当用户首次导入ezgmail模块时，此屏幕将显示给用户。为应用名称选择一个名称（我使用类似Python Gmail Script的通用名称）并为用户支持电子邮件和开发者联系信息输入您的电子邮件地址。然后点击“保存并继续”。

第二步“作用域”涉及添加您项目的权限，这是谷歌为“权限”选择的术语。点击“添加或删除作用域”按钮，然后在出现的新面板中，浏览表格并勾选作用域https://mail.google.com/的复选框，然后点击蓝色的“更新”按钮。然后点击“保存并继续”。

第三步“测试用户”要求您添加Python脚本将与之交互的Gmail电子邮件地址。在没有经过谷歌的应用程序批准流程的情况下，您的脚本将仅限于与您在本步骤中提供的电子邮件地址交互。点击“+添加用户”按钮，然后在出现的新面板中输入Gmail地址并点击蓝色的“添加”按钮。然后点击“保存并继续”。

第四步“摘要”提供了之前步骤的摘要。如果所有信息看起来都正确，请点击“返回仪表板”按钮。下一步是为您的项目创建凭据。

为您的项目创建凭据

从导航侧边栏菜单中，点击“APIs & Services”然后“Credentials”进入凭据页面。在页面顶部点击“+创建凭据”链接。一个下拉菜单将打开，询问您想创建哪种类型的凭据：“API密钥”、“OAuth客户端ID”或“服务帐户”。点击“OAuth客户端ID”。

在出现的新页面上，选择“桌面应用程序”作为“应用程序类型”，并将“名称”保留为默认的“桌面客户端1”。（如果您想，您可以将其更改为不同的名称，但这不会显示给您的Python脚本用户。）点击蓝色的“创建”按钮。

出现的弹出窗口显示了您的，点击“下载JSON”下载凭据文件。此文件将有一个类似client_secret_282792235794-p2o9gfcub4htibfg2u207gcomco9nqm7.apps.googleusercontent.com.json的名称。将其放在与您的Python脚本相同的文件夹中。

使用凭据文件登录

从与client_secret_*.json文件相同的文件夹中运行Python交互式外壳，并运行import ezgmail。或者，将一个.py Python程序放在此文件夹中，并让它运行import ezgmail。EZGmail将自动加载并检查此文件夹中的client_secret_*.json文件，如果找到，则启动您的网络浏览器到OAuth同意屏幕。使用您想从Python脚本访问的Gmail帐户登录。这必须是在配置Google Cloud项目的OAuth同意屏幕时提供的“测试用户”的相同电子邮件地址。

您将收到一条警告信息，内容为“谷歌尚未验证此应用程序”，但这没关系，因为这个是您刚刚创建的应用程序（或项目）。点击继续链接。您将来到另一个页面，上面写着“Python Gmail Script希望访问您的Google帐户”（或OAuth同意屏幕设置中给出的任何名称）。点击继续。

您将来到一个显示“认证流程已完成”的普通网页。现在您可以关闭浏览器窗口。在您的client_secret_*.json文件所在的同一文件夹中，您现在将看到token.json文件。不要分享这些文件：它们可以用来登录并访问您的Gmail帐户。

快速入门指南

设置凭据和令牌文件后，您可以使用import ezgmail导入EZGmail。要查看您正在发送的电子邮件地址，请检查ezgmail.EMAIL_ADDRESS（这是由您使用的token.json文件配置的，并且您必须首先调用ezgmail.init()或其他ezgmail函数）

>>> import ezgmail
>>> ezgmail.EMAIL_ADDRESS
'example@gmail.com'

要从您的"example@gmail.com"帐户发送电子邮件

>>> import ezgmail
>>> ezgmail.send('recipient@example.com', 'Subject line', 'Body of the email', ['attachment1.jpg', 'attachment2.mp3'])

attachments参数是可选的，如果您只有一个附件，您只需指定文件名字符串。请注意，Gmail很可能会过滤掉包含.exe、.zip或任何其他可疑附件的电子邮件。

cc和bcc字段也是可选的关键字参数

>>> import ezgmail
>>> ezgmail.send('recipient@example.com', 'Subject line', 'Body of the email', cc='friend@example.com', bcc='otherfriend@example.com,someoneelse@example.com')

ezgmail中的主要类是GmailThread和GmailMessage。一个GmailThread是一系列相互回复的电子邮件，而一个GmailMessage是线程中的一个单独电子邮件。

要检索未读电子邮件

>>> import ezgmail
>>> unreadThreads = ezgmail.unread()  # Returns a list of GmailThread objects.

summary()函数是打印线程或消息对象列表信息的简单方法

>>> ezgmail.summary(unreadThreads)
Jon, Al - Remember that old website Hamsterdance? LOL - Dec 09
Al - This is a test email about gerbils. - Dec 09

如果您想以数据结构的形式获取此信息，请将printInfo=False传递给summary()

>>> ezgmail.summary(unreadThreads, printInfo=False)
[(['Jon Smith <example@gmail.com>', 'Al Sweigart <al@inventwithpython.com>'], 'Remember that old website Hamsterdance? LOL', datetime.datetime(2018, 12, 9, 13, 29, 17)), (['Al Sweigart <al@inventwithpython.com>'], 'This is a test email about gerbils.', datetime.datetime(2018, 12, 9, 13, 25, 58))]

线程中的GmailMessage对象位于messages列表属性中

>>> ezgmail.summary(unreadThreads[0].messages)
Jon - Remember that old website Hamsterdance? LOL - Dec 09
Al - Haha that's awesome! On Sun, Dec 9, 2018 at 1:28 PM Jon Smith <example@gmail.com> wrote: Remember that old website Hamsterdance? LOL - Dec 09

GmailMessage对象具有sender、recipient、subject、body和timestamp属性

>>> msg = unreadThreads[0].messages[0]
>>> msg.sender
'Jon Smith <example@gmail.com>'
>>> msg.recipient
'Al Sweigart <al@inventwithpython.com>'
>>> msg.subject
'Hamsterdance'
>>> msg.body
'Remember that old website Hamsterdance? LOL\r\n'
>>> msg.timestamp
datetime.datetime(2018, 12, 9, 13, 28, 48)

您还可以调用recent()函数来获取最近收到的电子邮件线程

>>> import ezgmail
>>> recentThreads = ezgmail.recent()
>>> len(recentThreads)
22

recent()和unread()函数只是对search()的方便包装，您可以将查询传递给它（就像Gmail.com网站上的查询文本字段一样）

>>> import ezgmail
>>> threads = ezgmail.search('mancala')
>>> len(threads)
1
>>> ezgmail.summary(threads[0])
Al, Jon - Zanzibar &gt; <b>Mancala</b> is one of the oldest known games to still be widely played today. &gt; <b>Mancala</b> is a generic name for a - Dec 08

trash()方法删除GmailMessage或GmailThread对象中的消息或消息

>>> import ezgmail
>>> threads = ezgmail.search('mancala')
>>> threads[0].trash()  # Move the entire first thread to the Trash folder.

search()函数可以接受与查询文本字段相同的搜索运算符

• label:UNREAD
• from:al@inventwithpython.com
• subject:hello
• has:attachment

更多内容请参阅https://support.google.com/mail/answer/7190?hl=en

search()、recent()和unread()也可以接受一个maxResults关键字参数，默认设置为25。这设置了一个返回的线程/消息的数量上限。API使用配额在https://developers.google.com/gmail/api/v1/reference/quota上公布（免费层的大约每天一百万次请求（每秒25次））。

默认情况下，EZGmail以纯文本形式发送消息。您可以通过在send()中为mimeSubtype参数传递'html'来发送HTML电子邮件。（默认情况下，此参数设置为'plain'。）此电子邮件中的“Hello”将显示为粗体，“body”将显示为斜体

>>> ezgmail.send('recipient@example.com', 'Subject Line', '<strong>Hello</strong>, this is the <em>body</em> of the message.', mimeSubtype='html')

访问电子邮件或线程不会自动将其标记为未读。您必须自己调用GmailThread或GmailMessage对象的markAsRead()方法来执行此操作。（还有一个相应的markAsUnread()函数。）您还可以调用ezgmail.markAsRead()并将一个包含GmailThread或GmailMessage对象的列表传递给它。

>>> import ezgmail
>>> unreadThreads = ezgmail.unread()
>>> ezgmail.markAsRead(unreadThreads) # Marks all the GmailThread objects in the unreadThreads list as read.
>>> # Or you can do:
>>> for unreadThread in unreadThreads:
...     unreadThread.markAsRead() # Mark the individual GmailThread objects as read.

这两个函数通过使用EZGmail的addLabel()和removeLabel()函数来添加/删除'UNREAD'标签

>>> import ezgmail
>>> unreadThreads = ezgmail.unread()
>>> ezgmail.removeLabel(unreadThreads, 'UNREAD') # Also marks threads as read.
>>> ezgmail.addLabel(unreadThreads, 'UNREAD') # Marks them as unread again.
>>> # Or you can do:
>>> for unreadThread in unreadThreads:
...     unreadThread.removeLabel(unreadThreads, 'UNREAD') # Mark the individual GmailThread objects as read.

（目前EZGmail没有添加/删除/管理自定义标签的函数。）

要查看电子邮件的附件，请查看GmailMessage对象的attachments字典。键是附件的文件名。您可以选择调用downloadAttachment()或downloadAllAttachments()方法

>>> import ezgmail
>>> threads = ezgmail.search('See the attached files')
>>> threads[0].messages[0].attachments
>>> import pprint
>>> pprint.pprint(threads[0].messages[0].attachments)
{'a.png': {'id': 'ANGjdJ8eLDbjBpFTfvpuQ2HfR_iwp59XLUIl-IHW8eJcexMsxBYoPCZAXcX16rnqcbJZTknF5r3GmnM1W9n4vAE1oiVgUa4S4zBmNs7rd5PzFwLjO2vU3hp3_9SEZv-KBqVxi9nuNjarxhFqp3mxw6E5mqEYmFOYtT7Gx6CZbLaJuUox9GaWu-W9B4-XPDjwKkEfCdJ21FlOl-CsC6isZgD2Vh-ghh1haZN_2sifccznLv61ZW_KmqPKFcV1j7cXMQVqWU7bkgdH8do4Msc3QsG2ly_PNRid4-7gihsXaLI1ko_j3LSvsoLHFP3edhxh6YKQ2OdMhyZh5lqjmfT1TXgSo7hY16P_ScDO5MnWvmKscf_Hm5y5D4DHfwOq4--Otivoq2WVkVucVUJBkAoB',
           'size': 833609},
 'b.png': {'id': 'ANGjdJ_WYMmPmy2Dd2VBgvVoLAd1p3ARxGXKIzVfKqAiLhvKSBmEowYqFCdHbMJYlDZy4IWBGLg0eQCllMI0icqamM7vfMxBW2irJVogLM6SUT9cIcJFMSF7UhzU2I26bho086J7NjnX5u4kqYj_LHchowO56vTdKLRRsaJ2gfW0esz3cDFZzvthdR4wyBKEIeCJv7OJmFiaJIRf9f1KmFfKPLo9GZSyD2RMXdd6Qa2M3uN9pgT6sZ-OQx3e6aNDAKWh5GCeSiuIt_Z7GsDCdzVJjakMJx5FRFhp5zIck0p04AHnYhKfy1BipWmf7G-DAKzgJHAhFimBVUIBeFsHrqEGxDlevD7lK4ZBeb8cluSmYyEsRkSPSMYMlp-x1GVw25gqMnMVkGMKPfwj38iB',
	       'size': 335911}}
>>> threads[0].messages[0].downloadAttachment('a.png') # Download to current working directory.
>>> threads[0].messages[0].downloadAttachment('b.png', '/path/to/save/in')
>>> threads[0].messages[0].downloadAllAttachments() # Easier way to save all attachments.

限制

目前，EZGmail无法执行以下操作

• 读取或设置标签。（包括将电子邮件标记为已读。）
• 带有cc和bcc字段的发送电子邮件。
• 许多其他基本功能。这个包只是一个开始！

贡献

如果您想为EZGmail做出贡献，请查看https://github.com/asweigart/ezgmail或发送电子邮件至al@inventwithpython.com

支持

如果您觉得这个项目很有帮助，并希望支持其开发，请考虑在Patreon上向其创建者捐赠。点击此处。