电子邮件的 REST API 端点 - GitHub 文档

关于电子邮件管理

如果请求 URL 未包含 {username} 参数，则响应将针对登录用户（并且您必须随请求传递身份验证信息）。当通过 OAuth 且具有 user 范围进行身份验证时，将包含其他私有信息，例如用户是否启用了双因素身份验证。

设置已认证用户的首要电子邮件可见性

设置您的主要电子邮件地址的可见性。

“设置已认证用户的首要电子邮件可见性”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

“电子邮件地址”用户权限（写入）

“设置已认证用户的首要电子邮件可见性”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

主体参数
名称、类型、描述
`visibility` 字符串必填表示电子邮件是否公开可见。可以是以下之一： `public`, `private`

“设置已认证用户的首要电子邮件可见性”的 HTTP 响应状态代码

状态代码	描述
`200`	确定
`304`	未修改
`401`	需要身份验证
`403`	禁止
`404`	资源未找到
`422`	验证失败或端点已被滥用。

“设置已认证用户的首要电子邮件可见性”的代码示例

请求示例

补丁/user/email/visibility

curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/user/email/visibility \ -d '{"visibility":"private"}'

响应

状态：200

[ { "email": "[email protected]", "primary": true, "verified": true, "visibility": "private" } ]

列出已认证用户的电子邮件地址

列出您的所有电子邮件地址，并指定哪个电子邮件地址对公众可见。

OAuth 应用令牌和个人访问令牌（经典）需要 user:email 范围才能使用此端点。

“列出已认证用户的电子邮件地址”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

“电子邮件地址”用户权限（读取）

“列出已认证用户的电子邮件地址”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

查询参数
名称、类型、描述
`per_page` 整数每页的结果数（最大 100）。有关更多信息，请参阅“在 REST API 中使用分页”。默认值： `30`
`page` 整数要获取的结果的页码。有关更多信息，请参阅“在 REST API 中使用分页”。默认值： `1`

“列出已认证用户的电子邮件地址”的 HTTP 响应状态代码

状态代码	描述
`200`	确定
`304`	未修改
`401`	需要身份验证
`403`	禁止
`404`	资源未找到

“列出已认证用户的电子邮件地址”的代码示例

请求示例

获取/user/emails

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/user/emails

响应

状态：200

[ { "email": "[email protected]", "verified": true, "primary": true, "visibility": "public" } ]

为已认证用户添加电子邮件地址

OAuth 应用令牌和个人访问令牌（经典）需要 user 范围才能使用此端点。

“为已认证用户添加电子邮件地址”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

“电子邮件地址”用户权限（写入）

“为已认证用户添加电子邮件地址”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

主体参数
名称、类型、描述
`emails` 字符串数组必填将一个或多个电子邮件地址添加到您的 GitHub 帐户。必须包含至少一个电子邮件地址。注意：或者，您可以直接传递单个电子邮件地址或 `array` 电子邮件地址，但我们建议您使用 `emails` 密钥传递对象。

“为已认证用户添加电子邮件地址”的 HTTP 响应状态代码

状态代码	描述
`201`	已创建
`304`	未修改
`401`	需要身份验证
`403`	禁止
`404`	资源未找到
`422`	验证失败或端点已被滥用。

“为已认证用户添加电子邮件地址”的代码示例

请求示例

发布/user/emails

curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/user/emails \ -d '{"emails":["[email protected]","[email protected]","[email protected]"]}'

响应

状态：201

[ { "email": "[email protected]", "primary": false, "verified": false, "visibility": "public" }, { "email": "[email protected]", "primary": false, "verified": false, "visibility": null }, { "email": "[email protected]", "primary": false, "verified": false, "visibility": null } ]

删除已认证用户的电子邮件地址

OAuth 应用令牌和个人访问令牌（经典）需要 user 范围才能使用此端点。

“删除已认证用户的电子邮件地址”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

“电子邮件地址”用户权限（写入）

“删除已认证用户的电子邮件地址”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

主体参数
名称、类型、描述
`emails` 字符串数组必填与 GitHub 用户帐户关联的电子邮件地址。

“删除已认证用户的电子邮件地址”的 HTTP 响应状态代码

状态代码	描述
`204`	无内容
`304`	未修改
`401`	需要身份验证
`403`	禁止
`404`	资源未找到
`422`	验证失败或端点已被滥用。

“删除已认证用户的电子邮件地址”的代码示例

请求示例

删除/user/emails

curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/user/emails \ -d '{"emails":["[email protected]","[email protected]"]}'

响应

状态：204

列出已认证用户的公共电子邮件地址

列出您公开可见的电子邮件地址，您可以使用设置已认证用户的首要电子邮件可见性端点进行设置。

OAuth 应用令牌和个人访问令牌（经典）需要 user:email 范围才能使用此端点。

“列出已认证用户的公共电子邮件地址”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

“电子邮件地址”用户权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“列出已认证用户的公共电子邮件地址”的参数

标头
名称、类型、描述
`accept` 字符串建议设置为 `application/vnd.github+json`。

查询参数
名称、类型、描述
`per_page` 整数每页的结果数（最大 100）。有关更多信息，请参阅“在 REST API 中使用分页”。默认值： `30`
`page` 整数要获取的结果的页码。有关更多信息，请参阅“在 REST API 中使用分页”。默认值： `1`

“列出已认证用户的公共电子邮件地址”的 HTTP 响应状态代码

状态代码	描述
`200`	确定
`304`	未修改
`401`	需要身份验证
`403`	禁止
`404`	资源未找到

“列出已认证用户的公共电子邮件地址”的代码示例

请求示例

获取/user/public_emails

curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/user/public_emails

响应

状态：200

[ { "email": "[email protected]", "verified": true, "primary": true, "visibility": "public" } ]