Emails

Management of email addresses via the API requires that you authenticate through basic auth or OAuth with the user:email scope.

List email addresses for a user

Lists all of your email addresses, and specifies which one is visible to the public. This endpoint is accessible with the user:email scope.

GET /user/emails

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "email": "octocat@github.com",
    "verified": true,
    "primary": true,
    "visibility": "public"
  }
]

List public email addresses for a user

Lists your publicly visible email address, which you can set with the Toggle primary email visibility endpoint. This endpoint is accessible with the user:email scope.

GET /user/public_emails

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
[
  {
    "email": "octocat@github.com",
    "verified": true,
    "primary": true,
    "visibility": "public"
  }
]

Add email address(es)

POST /user/emails

Parameters

Name Type Description
emails array of strings Required. 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.

Example

{
  "emails": ["octocat@github.com", "support@github.com"]
}

Response

Status: 201 Created
[
  {
    "email": "octocat@octocat.org",
    "primary": false,
    "verified": false,
    "visibility": "public"
  },
  {
    "email": "octocat@github.com",
    "primary": false,
    "verified": false,
    "visibility": null
  },
  {
    "email": "support@github.com",
    "primary": false,
    "verified": false,
    "visibility": null
  }
]

Delete email address(es)

DELETE /user/emails

Parameters

Name Type Description
emails array of strings Required. Deletes one or more email addresses from 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.

Example

{
  "emails": ["octocat@github.com", "support@github.com"]
}

Response

Status: 204 No Content

Toggle primary email visibility

Sets the visibility for your primary email addresses.

PATCH /user/email/visibility

Parameters

You need to pass an object with the following keys.

Name Type Description
email string Required. Specify the primary email address that needs a visibility change.
visibility string Required. Use public to enable an authenticated user to view the specified email address, or use private so this primary email address cannot be seen publicly.

Input

{
  "email": "octocat@github.com",
  "visibility": "public"
}

Response

Status: 200 OK
[
  {
    "email": "octocat@github.com",
    "primary": true,
    "verified": true,
    "visibility": "private"
  }
]