简介：GmailQuickStart 是一份面向 Android 开发者的 Gmail API 快速入门示例，聚焦在移动端接入 Gmail 服务并统计邮箱未读邮件与全部邮件数量这一典型场景。适合已具备 Android 基础、希望理解 OAuth 2.0 授权流程与 Google API 调用方式的开发者，也可作为课程演示或项目原型的参考起点。资源以 rar 压缩包形式提供，整体约 26.86MB；上游未给出有效文件清单，文件总数记录为 0，具体文件类型明细暂无数据，目录组成与各类型用途不便展开说明。目前已有 99 人浏览学习。结合示例定位，读者可重点参考 API 客户端初始化、授权登录、users.messages.list 查询参数设置、分页处理以及将统计结果呈现在界面上的组织思路，并据此扩展定期刷新与状态更新逻辑，减少从零搭建 Gmail 接入环境的试错成本。

1. 先弄清楚 GmailQuickStart 解决的是哪件麻烦事

很多新手做 Android 应用时都会冒出一个念头：能不能让 App 直接读用户邮箱里的邮件？想法挺简单，真动手就卡在第一步——邮箱不是随便哪个应用都能碰的，得先过授权这一关，而授权恰恰是新手最容易卡住的地方。

GmailQuickStart 就是一份专为这个场景准备的 Android Gmail API 入门起点，它把「申请权限、拿到令牌、调用接口、把邮件列表取回来」这条链路完整走了一遍。它不教你做完整的邮件客户端，也不要求你先把 OAuth 协议啃透，只保证你能在真机上看到第一行返回数据。适合刚学 Android、想接一个真实第三方服务的零基础同学。

2. 为什么要走 Gmail API：老办法到底卡在哪儿

在写下第一行代码之前，先花十分钟把「为什么」想清楚，比直接抄代码有用得多。新手最常见的做法是搜一段「Android 收邮件」的旧代码贴进工程，跑不通就开始怀疑环境、怀疑模拟器、怀疑人生。其实大部分失败不是你的问题，而是那条路本身就不该走。

2.1 三种老办法各自的失败点

第一种是 IMAP/SMTP 直连。思路很直白：邮箱有服务器地址、有端口、有账号密码，那连上去读就行。翻车点在于，现在主流邮箱基本都关掉了「用账号密码登录第三方客户端」这个口子，用户得去网页后台单独生成一个应用专用密码，再一个字一个字抄进你的输入框。这个过程对用户来说既吓人又麻烦，你的应用还要负责把密码存好、传好，一旦出问题就是安全问题。

第二种是抓网页。有人想，那我不连服务器，直接请求网页版邮箱的地址，解析返回的 HTML 不就行了。这条路在演示阶段确实能跑，但你等于把整个应用的命脉绑在了别人网页的结构上——对方改一次版，你的解析规则全废，而且这种用法本身不符合服务方的使用约定。

第三种是接一个第三方聚合服务，把你的需求转包出去。它省事，但多了一层依赖、多了一份费用，也多了一个你不知道内部怎么处理数据的环节。

Gmail API 的思路是换掉整个前提：用户不需要把密码给你。他点一下同意，服务方发给你一张有时效、有范围、可随时撤销的凭证，你的应用拿着这张凭证去调接口。这个机制叫 OAuth 2.0，你不需要背它的握手细节，只需要记住一句话：你拿到的是一张限定了权限的临时通行证，不是用户的家门钥匙。

2.2 Gmail API 里就三样东西：messages、threads、labels

很多新手被官方文档的目录吓退，其实日常能用到的对象就那么几个，用生活化的说法解释一下：

• messages（邮件）：一封信就是一条 message，有自己的唯一 id。它是最小单位。
• threads（会话）：同一个话题来回几封，会被归到一个 thread 里。你在邮箱里看到的「折叠成一条」就是这个。
• labels（标签）：收件箱、已发送、重要、自定义文件夹，本质都是标签。一封邮件可以同时挂好几个标签。
• drafts（草稿）：写了一半没发的信。

这里有个新手特别容易混淆的点：message.id和message.threadId是两个不同的东西。列表接口返回的每一项里同时带着它们，但只有 id 能让你把那一封信的详情取出来。我见过不少人拿着 threadId 去查单封邮件，然后对着一堆 404 发呆。

还有一个特殊值要记住："me"。凡是需要填用户身份的地方，写"me"就代表「当前授权的这个账号」，你不用去记用户的邮箱地址。

2.3 权限是分档的：scope 决定了你能做什么

OAuth 里那个「范围」的概念叫 scope。它决定了你这张通行证能开哪几扇门。新手最常犯的错误是一上来就把所有权限全申请了，结果用户看到一长串「此应用可以读取、发送、删除你的所有邮件」的提示，直接点了拒绝。

原则很简单：做第一个例子时只要gmail.readonly。权限越窄，用户越敢点同意，你自己调试时的心理负担也越小。等读这条路彻底跑通了，再往发送那边走。

3. 动手前的准备：把授权这条路先铺平

准备工作分三块：云端配好、工程配好、代码里把 token 拿到手。这三块任何一块漏了，后面都会以「莫名其妙报错」的形式还给你，所以建议按顺序来，别跳步。

3.1 云端三件事：建项目、开接口、登记签名

打开开发者控制台，新建一个项目（名字随便起，比如quickstart-demo），然后在 API 库里搜 Gmail，把它启用。这一步不做，后面所有请求都会返回「接口未启用」。

接着是配置 OAuth 同意屏幕。新手会在这里被「用户类型」和「测试用户」绕晕。简单说：应用还在开发阶段，就选「外部」，然后把自己的邮箱加进测试用户名单。没加进名单的账号，登录时会被直接挡在门外，而且提示语很含糊，看不出是这个原因。

最后是创建凭据，类型选 Android。这里要填两样东西：包名和签名指纹 SHA-1。包名就是你build.gradle里applicationId的那个值。SHA-1 可以在工程根目录跑一条命令拿到：

# macOS / Linux 下取调试签名的指纹 ./gradlew signingReport

跑完在输出里找SHA1那一行。注意，调试签名和正式签名是两套完全不同的指纹，很多人上线后突然登录不了，就是因为只登记了调试那一个。入门阶段先登记调试的就行，但心里要留个底。

提示：包名和 SHA-1 必须与真机/模拟器上跑的包完全一致，差一个字符都会授权失败。改过包名记得回来重新登记。

3.2 工程里的依赖与网络权限

打开 Android 工程的模块级build.gradle，加上这几个依赖。它们分工很明确：一个负责 Gmail 的接口定义，一个让 Google 客户端能跑在 Android 上，一个负责解析返回的 JSON，最后一个负责弹授权界面。

dependencies { // Gmail REST 接口的官方客户端封装，把 HTTP 请求变成可调用的方法 implementation("com.google.apis:google-api-services-gmail:<最新稳定版>") // 让客户端使用 Android 自带的网络栈，而不是桌面 Java 的那一套 implementation("com.google.api-client:google-api-client-android:<最新稳定版>") // JSON 解析器，Gmail 客户端内部要用它把响应转成对象 implementation("com.google.http-client:google-http-client-gson:<最新稳定版>") // 授权：负责拉起账号选择界面、换取访问令牌 implementation("com.google.android.gms:play-services-auth:<最新稳定版>") }

版本号不要照抄，去官方仓库看当前稳定版填进去。这些库版本之间有兼容关系，混搭容易在编译期就报Duplicate class之类的错误，遇到就统一升到同一批发布版本。

然后在AndroidManifest.xml里声明网络权限，没有这一行，请求会以「连接失败」的形式表现，很难往权限上想：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"> <!-- 调接口必须联网 --> <uses-permission android:name="android.permission.INTERNET" /> <!-- 让程序能判断当前有没有网络，做友好的失败提示 --> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> </manifest>

3.3 第一次授权：把 access token 拿到手

这一步是整个入门路上最关键的一步。目标只有一个：拿到那串叫 access token 的字符串。拿到它，后面所有接口调用都只是拼参数。

// 1. 声明你要申请的权限范围：这里只要只读 val scopes = listOf(GmailScopes.GMAIL_READONLY) // 2. 构造登录选项，把 scope 挂上去 val signInOptions = GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_SIGN_IN) .requestEmail() // 顺便拿到用户邮箱，方便显示 .requestScopes(*scopes.toTypedArray()) // 关键：把 Gmail 只读权限加进来 .build() // 3. 用选项创建客户端，然后拉起账号选择界面 val signInClient = GoogleSignIn.getClient(this, signInOptions) startActivityForResult(signInClient.signInIntent, REQUEST_CODE_SIGN_IN)

代码里的三步对应三个动作：先说清楚要什么权限，再把这些权限打包进登录请求，最后弹界面让用户点同意。用户点完之后，回调里会给你一个账号对象。

拿到账号对象还不算完，那串 token 要单独换一次：

// 在登录成功的回调里执行：用账号 + scope 换取访问令牌 // 注意：这是阻塞调用，必须放到子线程，不能写在主线程 val token = GoogleAuthUtil.getToken( applicationContext, account, // 上一步回调里拿到的账号 "oauth2:" + GmailScopes.GMAIL_READONLY // 前缀 oauth2: 不能少 )

GoogleAuthUtil.getToken是同步阻塞的，放主线程会直接抛NetworkOnMainThreadException。用协程包一下，切到 IO 线程再调。这串 token 有有效期，通常一小时左右，过期了要么重新换，要么走静默刷新，入门阶段先用「过期就重新授权」这种笨办法也能跑通。

注意：token 是敏感信息，别打到日志里，更别提交到代码仓库。调试时用token.take(8)打印前几位确认拿到的不是空串就够了。

4. 第一个能跑的例子：读出最近 5 封邮件

前面都是铺垫，从这里开始真正出数据。整个过程分三步：构建服务对象、调列表接口、再逐封取标题。每写完一步都跑一次，别一口气全写完再点运行，那样出了错你根本不知道是哪一层的问题。

4.1 构建 Gmail 服务对象

// 用 Android 兼容的网络传输层，别用 Java 桌面版的那个 val transport = AndroidHttp.newCompatibleTransport() val jsonFactory = GsonFactory.getDefaultInstance() // 关键点：每次发请求前，把 token 塞进 Authorization 头 val gmail = Gmail.Builder(transport, jsonFactory, object : HttpRequestInitializer { override fun initialize(request: HttpRequest) { request.headers.authorization = "Bearer $accessToken" } }) .setApplicationName("QuickStartDemo") // 出现在请求的 User-Agent 里，便于排查 .build()

这段代码做的事情，说白了是给客户端装一个「自动补请求头」的装置。你看不到它手动拼 HTTP 报文，是因为客户端库替你做了。这里面最容易出错的是Bearer后面那个空格——漏掉或者多打一个，服务端都认不出来，返回的是含糊的 401。

setApplicationName不影响功能，但在控制台的用量统计里能帮你区分是哪个应用在调，建议填一个能认出自己的名字。

4.2 列出邮件再逐封取标题

// 第一步：列表接口。它只返回 id 和 threadId，不返回标题 val listResult = gmail.users().messages().list("me") // "me" = 当前授权账号 .setMaxResults(5L) // 只要 5 封，第一次跑别贪多 .setQ("in:inbox") // 搜索语法，这里限定收件箱 .execute() // 第二步：拿到列表后逐封查详情 listResult.messages?.forEach { ref -> val detail = gmail.users().messages().get("me", ref.id) .setFormat("metadata") // 只要头部信息，不拉正文，省流量也省配额 .setMetadataHeaders(listOf("Subject", "From", "Date")) .execute() // 把 headers 摊平成 map，方便按名字取 val headers = detail.payload.headers.associate { it.name to it.value } Log.d("GmailDemo", "${headers["From"]} | ${headers["Subject"]} | ${headers["Date"]}") }

这是整个入门里信息量最大的一段，逐点拆开看：

messages().list("me")是列表接口，参数是用户身份。它返回的messages是一个很轻的数组，每一项只有 id 和 threadId，没有标题、没有发件人。这是新手第一个认知落差——以为 list 就拿到全部了，结果发现是个空壳。所以必须再调一次get。

setMaxResults(5L)控制单次返回条数。注意它是Long类型，写5编译器会报类型不匹配，得写5L。

setQ("in:inbox")是搜索表达式，语法跟你在邮箱搜索框里敲的那套一样。想只要未读就写is:unread，想按发件人筛就写from:someone@example.com。入门阶段先固定成收件箱，确认能出数据再改。

setFormat("metadata")决定返回的详略程度。默认是全量full，会把整封信的正文结构都拉回来，数据量可能是 metadata 的几十倍。第一次跑，用 metadata 加上指定的三个头部字段就够了。

associate { it.name to it.value }是把一个List<MessagePartHeader>转成 Map，这样你能用headers["Subject"]这种直观方式取值，而不用写循环判断。

4.3 跑起来看结果，以及失败时先看什么

把上面两段放进一个lifecycleScope.launch(Dispatchers.IO) { ... }里，装到真机上点一下按钮。第一次跑通的时候，Logcat 里会出现五行形如某某 <someone@example.com> | 一封邮件标题 | 2024年x月x日的日志。看到这五行，Android Gmail API 这条链路你就算真正打通了。

如果没出数据，按这个顺序排查，别乱猜：

先看 Logcat 里有没有 401。有 401 说明 token 有问题，要么是空的，要么过期了，要么Bearer后面空格写错。再看有没有 403。403 分两种，一种写着insufficientPermissions，意思是 scope 没申请对，你可能写了gmail.send却去读列表；另一种写着quotaExceeded，说明调太频繁了，等一会儿再试。

最后看有没有NetworkOnMainThreadException。有的话就是忘了切线程，把execute()包进 IO 调度器里。

第三个常见现象是「没报错，但列表是空的」。这多半是因为这个账号的收件箱真的一封邮件都没有，或者setQ里写了个筛不出东西的条件。换个测试账号，或者把setQ那行先注释掉验证一下。

提示：调试期可以在控制台看到每次调用的用量。养成习惯，每跑一次就去瞄一眼，能提前发现「我是不是在死循环里疯狂请求」这种问题。

5. 新手最容易踩的 5 个坑：现象、原因、解决

这些不是我编出来凑数的，是这条路上出现频率最高、且报错信息最不友好的几个。提前看一眼，能省掉半天时间。

5.1 授权阶段的三个坑

坑一：点了同意，回调却一直返回失败，错误码 12500 或 10。现象是登录界面能弹出来，用户也点了，但你这边收不到账号对象。原因几乎都是签名指纹对不上——你登记的 SHA-1 是别人的，或者你换了台电脑、换了 keystore，指纹跟着变了。解决办法是重新跑一次./gradlew signingReport，把新的 SHA-1 填回控制台，然后等几分钟让配置生效再试。改完立刻测往往会以为没生效，其实是缓存还没刷。

坑二：登录时提示「应用未经验证」，然后就没有下一步了。现象是弹出一个警告页，只有一个「返回」按钮。原因是你用来测试的那个账号没被加进测试用户名单。解决方法是回到控制台的同意屏幕配置页，把当前登录的账号加进去。这里有个细节：如果你手机上有多个账号，登录时选了另一个没登记的，一样会被挡。所以测试阶段最好只留一个账号。

坑三：第一次能跑，过一小时再跑就 401 了。现象是同一个安装包，刚才是好的，吃个饭回来全挂了。原因是 access token 有有效期，一般一小时，过期就作废。新手容易以为是代码坏了，反复重装应用。解决办法是识别出这个错误类型，捕获它然后重新走一次授权流程。想做得体面一点，可以拿 refresh token 去静默换新的，不过那是下一步的事，入门阶段先让用户重新点一下同意，功能上是完整的。

5.2 取数据阶段的两个坑

坑四：循环里逐封查详情，跑到第十几封就开始 403。现象是前几封都好好的，到某个数量之后突然报rateLimitExceeded。原因是列表接口和详情接口各有各的配额，你在一个循环里对每一封都发一次请求，数量一多就撞线了。解决办法有三条，按优先级来：能用列表接口拿到的就别查详情；必须要详情的，加上setFormat("metadata")和setMetadataHeaders把返回体积压到最小；批量场景改用messages().batchModify或者干脆换成users().messages().list配合更大的分页。真撞上了就退避重试，别原地死循环。

坑五：正文取出来是一堆乱码。现象是你把payload.body.data拿去解码，出来的字符串里全是奇怪的符号。原因是 Gmail 返回的正文用的是 base64url 编码，跟你平时见的标准 base64 不是一回事——它把+换成了-，把/换成了_，还去掉了末尾的等号。解决办法是用Base64.decode(data, Base64.URL_SAFE or Base64.NO_WRAP)，别用默认参数。另外正文经常被拆成多段（parts数组），你先判断有没有parts，有就递归往下找text/plain那一段，别硬取第一层。

6. 跑通之后学什么：从「能读」到「能发」的三步路线

第一个例子跑通之后，最容易犯的错是马上想做一个完整邮箱客户端，然后在一堆没学过的概念里迷路。我建议按下面这个顺序走，每一步都以前一步跑通为前提。

第一步的重点是把稳定性做出来。现在的代码是「点一下按钮跑一次」，真实的场景是列表能滚动加载更多。这里要接触nextPageToken：列表接口返回它的时候，说明后面还有数据，把它原样传给下一次请求的setPageToken就能翻页。同时把 401、403、网络超时这三类错误分开处理，别一律弹「加载失败」。

第二步是发信，也是新手公认最难的一关。发信不像读信那样有现成字段，你得自己拼一个符合 MIME 规范的字符串：头部写To、Subject、Content-Type，空一行，再写正文。拼好之后整体做 base64url 编码，塞进Message.raw字段，然后调gmail.users().messages().send("me", message)。中文标题还要额外处理编码，不然收件人看到的是乱码。这一关我第一次写的时候，光是标题乱码就折腾了一晚上，血泪经验是：先用纯英文标题跑通，确认链路没问题，再逐步加中文和附件。

第三步看你自己的需求。如果只是想在应用里标记「已处理」，那用gmail.modify加一个自定义标签就够了，不必碰删除这类危险操作。

最后说个习惯。从那以后我每次接一个新的第三方服务，都强制走一遍「最小权限 + 最小数据量 + 单独跑通」这个流程：先把 scope 压到只读，先把条数压到 5 条，先在 Logcat 里看到一行真实数据，再往上堆功能。看起来很慢，实际上省下来的排查时间远超这点等待。希望帮到你。

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