{"meta":{"title":"REST API endpoints for emails","intro":"Use the REST API to manage email addresses of authenticated users.","product":"REST API","breadcrumbs":[{"href":"/en/rest","title":"REST API"},{"href":"/en/rest/users","title":"Users"},{"href":"/en/rest/users/emails","title":"Emails"}],"documentType":"article"},"body":"# REST API endpoints for emails\n\nUse the REST API to manage email addresses of authenticated users.\n\n## About email administration\n\nIf a request URL does not include a `{username}` parameter then the response will be for the signed-in user (and you must pass [authentication information](/en/rest/overview/authenticating-to-the-rest-api) with your request). Additional private information, such as whether a user has two-factor authentication enabled, is included when authenticated through OAuth with the `user` scope.\n\n> \\[!NOTE]\n> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.\n\n## Set primary email visibility for the authenticated user\n\n```\nPATCH /user/email/visibility\n```\n\nSets the visibility for your primary email addresses.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Body parameters\n\n* **`visibility`** (string) (required)\n  Denotes whether an email is publicly visible.\n  Can be one of: `public`, `private`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n* **403** - Forbidden\n\n* **404** - Resource not found\n\n* **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example setting the primary email address to private\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X PATCH \\\n  https://api.github.com/user/email/visibility \\\n  -d '{\n  \"visibility\": \"private\"\n}'\n```\n\n**Response schema (Status: 200):**\n\nArray of `Email`:\n\n* `email`: required, string, format: email\n* `primary`: required, boolean\n* `verified`: required, boolean\n* `visibility`: required, string or null\n\n## List email addresses for the authenticated user\n\n```\nGET /user/emails\n```\n\nLists all of your email addresses, and specifies which one is visible\nto the public.\nOAuth app tokens and personal access tokens (classic) need the user:email scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n* **403** - Forbidden\n\n* **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/user/emails\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Set primary email visibility for the authenticated user](#set-primary-email-visibility-for-the-authenticated-user).\n\n## Add an email address for the authenticated user\n\n```\nPOST /user/emails\n```\n\nOAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Body parameters\n\n* **`emails`** (array of strings) (required)\n  Adds one or more email addresses to your GitHub account. Must contain at least one email address. Note: Alternatively, you can pass a single email address or an array of emails addresses directly, but we recommend that you pass an object using the emails key.\n\n### HTTP response status codes\n\n* **201** - Created\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n* **403** - Forbidden\n\n* **404** - Resource not found\n\n* **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example adding multiple email addresses\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  https://api.github.com/user/emails \\\n  -d '{\n  \"emails\": [\n    \"octocat@github.com\",\n    \"mona@github.com\",\n    \"octocat@octocat.org\"\n  ]\n}'\n```\n\n**Response schema (Status: 201):**\n\nSame response schema as [Set primary email visibility for the authenticated user](#set-primary-email-visibility-for-the-authenticated-user).\n\n## Delete an email address for the authenticated user\n\n```\nDELETE /user/emails\n```\n\nOAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Body parameters\n\n* **`emails`** (array of strings) (required)\n  Email addresses associated with the GitHub user account.\n\n### HTTP response status codes\n\n* **204** - No Content\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n* **403** - Forbidden\n\n* **404** - Resource not found\n\n* **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example deleting multiple email accounts\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X DELETE \\\n  https://api.github.com/user/emails \\\n  -d '{\n  \"emails\": [\n    \"octocat@github.com\",\n    \"mona@github.com\"\n  ]\n}'\n```\n\n**Response schema (Status: 204):**\n\n## List public email addresses for the authenticated user\n\n```\nGET /user/public_emails\n```\n\nLists your publicly visible email address, which you can set with the\nSet primary email visibility for the authenticated user\nendpoint.\nOAuth app tokens and personal access tokens (classic) need the user:email scope to use this endpoint.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`per_page`** (integer)\n  The number of results per page (max 100). For more information, see \"Using pagination in the REST API.\"\n  Default: `30`\n\n* **`page`** (integer)\n  The page number of the results to fetch. For more information, see \"Using pagination in the REST API.\"\n  Default: `1`\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **304** - Not modified\n\n* **401** - Requires authentication\n\n* **403** - Forbidden\n\n* **404** - Resource not found\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/user/public_emails\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Set primary email visibility for the authenticated user](#set-primary-email-visibility-for-the-authenticated-user)."}