电子邮件的 REST API 端点

关于电子邮件管理

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

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

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

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

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

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

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

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

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

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

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

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

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

请求示例

patch/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` string 建议设置为 `application/vnd.github+json`。

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

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

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

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

请求示例

get/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` string 建议设置为 `application/vnd.github+json`。

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

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

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

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

请求示例

post/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` string 建议设置为 `application/vnd.github+json`。

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

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

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

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

请求示例

delete/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` string 建议设置为 `application/vnd.github+json`。

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

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

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

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

请求示例

get/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" } ]