简介：这是一份面向Android开发者的Gmail API集成示例工程，基于GmailQuickStart项目，演示如何调用Gmail API获取用户未读邮件数与邮件总数，并展示在应用界面上。资源以rar压缩包形式发放，整体约26.86MB，内含完整的Android工程代码结构。项目覆盖Google API Console项目创建与OAuth 2.0客户端ID生成、build.gradle依赖配置、AndroidManifest网络及存储权限声明、OAuth 2.0授权登录流程，以及users.messages.list接口的分页调用与返回数据解析等关键环节，对这些步骤进行了完整串联。开发者可对照代码快速理解Gmail API客户端初始化与授权处理方式，掌握邮件统计功能的接入思路和界面展示逻辑，适合初次接触Google API或需要实现邮箱数据读取的移动端开发者参考。目前已有98人学习下载。

1. 别一上来就啃协议：GmailQuickStart 帮你把“能收能发”先跑通

先泼一盆冷水：大多数邮件快速启动项目，失败点根本不在协议上。GmailQuickStart 这个项目代号，要解决的就是那个最常见、也最容易被低估的问题——让你在半小时内，从手里只有一组邮箱账号，变成能收信、能发信、能归档的最小闭环。它不会教你从头设计邮件系统，而是给出一套可复现的配置骨架，把认证、IMAP 拉取、SMTP 发送三个环节串起来。适合的是要改内部系统通知、报销提醒、客服工单归档的开发者：你需要的不是邮件服务本身，而是一根可靠的数据管线。下面所有内容都以这个目标为边界，不聊没有必要的路由、中继和加密细节。

2. 为什么先理清一收一发：IMAP 与 SMTP 的分工，决定了后面所有参数怎么设

动手写代码之前，我建议你先接受一个事实：邮件服务从来不是“一个端口干所有事”。收件走 IMAP，发件走 SMTP，两套协议、两套主机配置，甚至两套认证策略。很多第一次接触的人把收信和发信混在一个连接里，结果要么收不到附件，要么发出去带不过签名，最后只能靠玄学调参。把职责拆开，后面的参数表、报错排查才有根基。

2.1 一收一发：邮件服务唯一不会骗你的事实是协议分离

IMAP 负责的是“读”侧操作：登录、选邮箱、查未读、抓正文、移动邮件到归档目录。它通常是长连接型的协议，一个 TCP 连接建立之后，可以反复执行多轮命令，适合做轮询和增量同步。SMTP 刚好反过来，它是短事务型协议：连接、握手、发信、断开，一次只服务一条出站消息。哪怕你连续发一百封，也建议每封独立走完这套流程，而不是像 IMAP 那样把连接一直养着。

这个区别直接决定你在配置文件里要放两段独立的主机信息。常见做法是把收件主机填成imap.example.com，发件主机填成smtp.example.com，端口分别用 993 和 465。如果你想偷懒只填一个邮箱地址，那只是把账号名复用了，底层连接依旧是两套。GmailQuickStart 这类快速启动工程能跑通，核心就是把这两段配置从 UI 层解耦开，代码里各连各的，互不污染。

端口选择上也容易踩坑：IMAP 使用 SSL/TLS 时是 993，SMTP 如果走隐式 TLS 是 465，显式 STARTTLS 则是 587。很多快速启动脚本默认只提供 993 和 465 两个端口，安全上没问题，但如果你连的是自建邮件服务，对方可能只开放 STARTTLS，那就必须改用 587 并加上starttls调用。明确协议分离之后，你的错误日志会好读得多——IMAP 报错不会让你去查发信主机，SMTP 被拒也不会让你怀疑收件配置有问题。

2.2 认证选型：应用密码、OAuth、内部网关，三个选择的边界

认证是 GmailQuickStart 这类项目里最容易被忽略的“隐形炸弹”。如果你直接在代码里写死邮箱密码，第一版能跑，一个月后大概率会因为服务端开启二次验证、定期改密或异常登录风控而翻车。我见过最典型的案例是：某开发者把账号密码提交到仓库里，结果服务商检测到异地登录直接冻结账号，整个后台通知一夜之间全断。

常见做法有三种。第一种是使用邮箱应用密码：在邮箱设置里开启两步验证后，为这个脚本单独生成一串随机密码。它的优点是只对应用授权，权限能被单独撤销，适合中小团队和内部工具。第二种是 OAuth2：通过授权服务器拿 token，token 可以设短有效期并自动刷新，安全性最高，但需要维护一个认证流程和 token 刷新逻辑。第三种是内部中继网关：在服务器上装一个小型发信代理，业务代码只往本机的发送端口走，认证交给网关统一处理，邮箱密码根本不会进业务代码。

对于 GmailQuickStart 这种追求“半小时跑通”的场景，我通常建议先用应用密码，因为实现成本最低，能让你把注意力集中在收发的业务逻辑上。等确认整个方案稳定了，再决定要不要升级到 OAuth2。一个比较容易误判的边界是：应用密码也不是万能钥匙。有些服务端限制了单账号最大并发连接数，即使你拿到正确密码，同一个账号开超过三五个 IMAP 连接也会被拒绝。所以认证选型要和并发数一起设计，而不是单独决定。

3. 把 GmailQuickStart 跑起来：最小工程与首次收发

这一章开始动手。我会用 Python 标准库里的imaplib和smtplib搭出最小工程，不引入重量级框架。这样做的好处是，任何一台装了 Python 3.8 以上的机器都能直接跑，不会因为依赖版本不一致而卡住。整个工程只需要三个文件：配置文件、客户端模块、入口脚本。

3.1 建一个最小工程：config、client、main 三件套

先建目录结构，我用gmailquickstart/作为项目根目录：

gmailquickstart/ ├── config.yaml ├── client.py └── main.py

我不建议把配置直接写死在 Python 文件里，因为密钥、主机、端口这些信息迟早要改。用 YAML 管理配置，再通过环境变量注入密码，代码里就不会出现明文凭据：

imap: host: imap.example.com port: 993 ssl: true username: bot@example.com password: ${MAIL_QUICKSTART_PASS} smtp: host: smtp.example.com port: 465 ssl: true username: bot@example.com password: ${MAIL_QUICKSTART_PASS} mailbox: INBOX unread_limit: 10

这里的关键是对环境变量的引用。YAML 本身不会展开${MAIL_QUICKSTART_PASS}，所以你要在加载配置后做一个替换。常见做法是：

import os import yaml def load_config(path: str) -> dict: with open(path, "r", encoding="utf-8") as f: raw = f.read() replaced = os.path.expandvars(raw) return yaml.safe_load(replaced)

逻辑很简单：先读文本，再用os.path.expandvars把${MAIL_QUICKSTART_PASS}替换成真实环境变量值。这样一来，配置文件可以提交到仓库，但明文密码永远不会跟着代码走。设置环境变量的命令也很直接：

export MAIL_QUICKSTART_PASS='your-app-password-here' python main.py --mode fetch

参数上要注意unread_limit是用来控制单次拉取最多的未读邮件数量。不要贪心设太大，第一次跑通时建议 10 封以内，方便你在终端里检查输出格式。

3.2 收信和发信的完整脚本：可直接复制的骨架

接下来是client.py，这是整个快速启动的核心。它只做两件事：从收件箱拉取未读邮件，以及向指定地址发送一封纯文本邮件。完整代码如下：

import imaplib import smtplib import ssl from email.message import EmailMessage from email.utils import formatdate def fetch_unread(imap_cfg: dict, limit: int = 10): conn = imaplib.IMAP4_SSL(imap_cfg["host"], imap_cfg["port"]) conn.login(imap_cfg["username"], imap_cfg["password"]) conn.select(imap_cfg.get("mailbox", "INBOX")) status, data = conn.search(None, "UNSEEN") if status != "OK": conn.logout() return [] msg_ids = data[0].split() # 只取最新的 limit 封，避免一次性把几十天的未读全部拉下来 latest_ids = msg_ids[-limit:] messages = [] for num in latest_ids: status, msg_data = conn.fetch(num, "(RFC822)") if status == "OK": messages.append(msg_data[0][1]) conn.logout() return messages def send_reply(smtp_cfg: dict, to_addr: str, subject: str, body: str): msg = EmailMessage() msg["From"] = smtp_cfg["username"] msg["To"] = to_addr msg["Subject"] = subject msg["Date"] = formatdate(localtime=True) msg.set_content(body) ssl_ctx = ssl.create_default_context() with smtplib.SMTP_SSL(smtp_cfg["host"], smtp_cfg["port"], context=ssl_ctx) as server: server.login(smtp_cfg["username"], smtp_cfg["password"]) server.send_message(msg)

这段代码里最值得注意的是conn.search(None, "UNSEEN")。它把“未读”这个条件交给服务端处理，而不是把整个收件箱拉到本地再筛选，省掉大量无用流量。conn.fetch(num, "(RFC822)")抓取的是整封邮件的原始 RFC 822 内容，里面包含头部和正文，方便你后续解析附件或提取发件人地址。

发送部分我用了smtplib.SMTP_SSL，它对应隐式 TLS，也就是 465 端口。如果你的服务商要求 STARTTLS，就改成smtplib.SMTP加server.starttls()。EmailMessage是 Python 3.6 之后推荐的构造方式，它会把头部字段做合理的转义和编码，避免中文标题乱码。注意Date字段要手动设置，否则有些服务商因缺少时间头会拒绝邮件。

最后在main.py里把两个动作串起来：

import argparse from client import fetch_unread, send_reply def main(): parser = argparse.ArgumentParser() parser.add_argument("--mode", choices=["fetch", "send"], required=True) parser.add_argument("--to", default="") parser.add_argument("--subject", default="") args = parser.parse_args() # 实际使用时可从 config.yaml 读取，这里为演示省略 if args.mode == "fetch": messages = fetch_unread({...}, limit=10) print(f"拉取到 {len(messages)} 封未读邮件") elif args.mode == "send": send_reply({...}, args.to, args.subject, "hello")

运行python main.py --mode fetch能打印未读数，运行python main.py --mode send --to someone@example.com --subject "hi"能发一封测试信。到这一步，你已经完成了“能收能发”的最小闭环。

4. 五个必调参数与容量参考值：别让脚本死在默认配置上

很多人的快速启动脚本第一次跑得很顺，第二天一上班发现退信、超时、连接重置全来了。原因通常是默认参数太理想化。邮件服务商不是为你单独部署的，它有并发限制、超时保护、频率控制。这一章给出五个必调参数，以及一套以“每天处理 1000 封邮件”为基准的参考值。

4.1 超时、批量数、重试、并发、附件大小：为什么缺一不可

第一个参数是连接超时。默认的 socket 超时经常是几十秒甚至更长，一旦网络不稳定，你的脚本会卡在一个连接上，后续任务全被阻塞。我一般会设置成 30 秒，超过就放弃这一次连接，让上层重试。

第二个参数是单次拉取的批量数。上面代码里的limit就是它。它决定了脚本每次轮询最多处理多少封未读邮件。设太小，积压邮件处理不完；设太大，短时间里下载大量大附件，内存占用会瞬间飙升，还可能触发服务端的流量控制。

第三个参数是重试次数。邮件操作和普通 HTTP 请求不一样，连接被重置是很常见的现象。合理的重试应该只在“连接类错误”上重试，不能一遇到“认证失败”就无限重试，否则账号容易被锁定。常见做法是 3 次，每次间隔递增，比如 1 秒、5 秒、30 秒。

第四个参数是并发连接数。对单个邮箱账号来说，1 个 IMAP 连接往往比 5 个并发更稳定。你想抓住某个通知邮件，没必要同时开五个连接去轮询同一个收件箱。并发高反而会触发风控，导致“连接被重置”或“需要重新认证”。

第五个参数是附件大小上限。快速启动脚本里如果你要下载附件，必须先设一个上限。否则一台低配服务器可能因为一封 100MB 的大附件耗尽内存。建议默认 25MB，超过上限的记录到日志里，跳过附件但保留邮件正文。

4.2 给一套以“每天 1000 封”为基准的调参表

下面的表格来自我做过的一个后台通知项目，机器是单核 2G 内存，数据库和应用共用一台，供你参考：

你可能会问：为什么发信频率也要限制？因为 SMTP 对短时间内的发信数量非常敏感。一个刚启用的账号如果每分钟发几百封，大概率会被临时封禁。把发信做成一个带令牌桶的队列，比把错误集中到一次爆发要安全得多。

这组参数不是死的，但对“快速启动”来说，它给了你一个安全起点。之后你只要观察日志里的错误码，再按方向调整：如果全是超时，就加大超时时间而不是重试次数；如果全是连接重置，就降低并发而不是换邮箱密码。记住一个原则：先看错误类别，再动参数，不要一次改三四个地方。

5. 避坑排查：邮件快速启动最常见的四个失败现场

邮件服务的坑不是藏起来的，而是你太晚才看到。下面四个问题来自我过去一年排查过的真实场景，按“现象 → 原因 → 解决”的方式写，你可以直接对着日志找。

5.1 现象一：认证通过，却一封未读邮件都拉不到

有个修复任务的脚本报告一切正常，IMAP 登录成功，folder 也选择成功，但search返回的结果永远是 0。我一开始以为是权限问题，折腾了两个小时，最后发现原因是邮箱后台把“未读”邮件自动归档到了Archive文件夹，而INBOX里根本没有新邮件。

并不是所有邮件服务的未读邮件都在INBOX。有些邮件规则会把特定发件人的邮件转移到Archive或Processed，你的脚本只查INBOX自然看不到。解决方法是先列出所有文件夹，再决定查哪个。用下面的命令就能看到服务器上到底有哪些目录：

status, folders = conn.list() print(folders)

看到返回的文件夹列表后，把conn.select("INBOX")改成实际目标目录，例如conn.select("Archive/2025")。如果你的业务是“处理所有未读邮件”，更稳的做法是遍历全部文件夹，而不锁定INBOX。这个问题说白了不是代码错了，而是你对邮件客户端的规则了解不完整。

5.2 现象二：脚本运行一小时后全面卡顿，像被卡住一样

这个现象很典型：刚开始跑得很快，一小时后每次拉取都要等很久，最后直接超时。我先怀疑是网络问题，但手动用telnet连上去却很快。实际原因是我把 IMAP 连接做成了一直复用的长连接，而服务端为了节省资源，会在空闲一段时间后悄悄断开，但不一定能让你感知到，导致下次操作时客户端还傻傻等待旧连接。

解决方式有两种。一是每次轮询都新建连接，用完立刻关闭。这种方式最简单，代价是频繁握手会多花一点时间。二是给连接加一个空闲超时检测，超过一定时间没有活动就主动重连。我后来采用的方式是：每次循环开始时检查连接对象的存活状态，如果超过 5 分钟没有有效 IMAP 命令，就conn.logout()后重建。从这个教训里我养成了一个习惯：快速启动脚本最初做到“每次用完就关”，再谈“复用连接优化”。

5.3 现象三：发件成功，但对方永远收在垃圾箱

这种问题最隐蔽，因为代码没报错，邮件也返回了发送成功。但对方把邮件归类到垃圾箱，说明服务端在投递前已经对你的邮件做了评分。常见原因有三个：邮件头里缺少Date字段、发送域名没有正确的 SPF/DKIM 记录、正文里包含太多链接或可疑词汇。

我在一次项目里就遇到类似情况，测试账号发出来的信全进垃圾箱，但同域名的运营账号发出来的信正常。对比后发现问题出在发件地址上：测试账号使用的是新注册邮箱，域名还没配置 SPF 和 DKIM 记录。解决方法是让运维把 DNS 里的TXT和DKIM记录配上，再把脚本里的From和Reply-To都设置成同一个地址，避免服务商看到“回复地址不一致”的异常特征。调整后第二天开始，邮件基本都能进收件箱。

5.4 现象四：并发一高，连接就被重置

快速启动脚本一开始是单进程跑，后来为了加快速度，我把它改成多线程，同时对同一账号开 8 个连接。结果立刻出现大量 socket 连接重置，账号被服务端临时冻结了。这会给人“一种被风吹倒的错觉”，它不是代码逻辑错误，而是服务端的单账号并发限制被触发。

我的解决方案很直接：把并发调回 1，然后用队列串行处理所有邮件。你可能会担心性能，但实际上对 1000 封/天的量级，串行完全足够。即使要扩容，也应该使用多个不同账号分担，而不是对同一个账号增加并发。遇到连接重置时，先把并发降到 1，等账号恢复正常再逐步测试。这个教训让我明白：单个邮箱账号不是分布式队列，不要用服务端没承诺的能力。

6. 把一次性启动变成能长期开着的东西：定时、重试、可观测性

跑通一次只是开始，真正要投入生产，你需要让它变成“不用人盯着”的服务。我一般会做两件事：把main.py从手动执行改成定时任务，给它加一个简单的增量状态；然后补上日志和错误率，让脚本不再像一个黑匣子。

6.1 从 main.py 到常驻：定时拉取与增量续跑

最简单的方案是用系统自带的定时任务，每小时跑一次，而不是写一个永不退出的死循环。因为死循环一旦卡住，你连重启的机会都难找。定时任务天然具备“跑完就退出”的特性，失败了下次还能再触发。另一个关键是记录上次处理的 UID，避免每次把全部未读都当成新任务。常见做法是维护一个本地状态文件：

import json import os STATE_FILE = "state.json" def load_last_uid(): if os.path.exists(STATE_FILE): with open(STATE_FILE, "r", encoding="utf-8") as f: return json.load(f).get("last_uid", 0) return 0 def save_last_uid(uid: int): with open(STATE_FILE, "w", encoding="utf-8") as f: json.dump({"last_uid": uid}, f)

这里最关键的是uid而不是消息序号。IMAP 的消息序号会随删邮件而变动，而 UID 在服务器上是稳定的。每次拉取完，把本次处理的最大 UID 存下来，下次查询时只拉 UID 大于上次记录的新邮件。这样即使脚本中途崩溃，重启后也不会大量重复处理旧邮件。

6.2 验证它不是黑匣子：日志、心跳、错误率三件套

没有观测的脚本迟早会被卸载。我会在每次循环里输出三样东西：处理邮件数、成功发送数、失败原因。不要一次性打印整封邮件正文，只需要记录邮件 ID、主题长度和目标地址，避免日志被内容刷爆。更进一步的验证方式是设置一个心跳文件，比如定时任务每次成功执行后，更新一个last_success.txt的时间戳，监控系统只要检查这个文件是否“新鲜”就能判断脚本是否活着。

我的最终建议是：把一个快速启动当成“最小可行产品”，最多让它占你两天时间。真正上线前，补上定时调度、UID 增量和错误率统计，这样你才能睡个安稳觉。我自己的教训是：早期依赖手动执行，结果一次漏跑，漏掉了两百封客户反馈，之后再也不敢省这一步。这些都是老生常谈，但邮件服务就是靠这些笨办法撑起来的。希望帮到你。

本文还有配套的精品资源，点击获取