An Ubuntu SSO account can have one or more emails linked to it. Email addresses can have a verified or unverified status, depending on whether the owner completed the email verification process for each address or not.

An account’s email can also be the preferred email address, which will be a verified address if there is such, otherwise it will be the emaill address the user created the account with.


This endpoint requires every request to be OAuth signed with a token belonging to the account owning the email that is being operated on.

The OAuth token can be obtained following the documentation at the OAuth token resource.

Example of OAuth signing code, assuming an existing account with password password:

import json

import requests
from requests_oauthlib import OAuth1

SSO_API_URL = SSO_ROOT_URL + 'api/v2/'

email = ''
data = {'email': email, 'password': 'password', 'token_name': 'Doc test'}
response =
    SSO_API_URL + 'tokens/oauth', json=data,
    headers={'Accept': 'application/json'})
credentials = response.json()
auth = OAuth1(credentials['consumer_key'], credentials['consumer_secret'],
              credentials['token_key'], credentials['token_secret'])
response = requests.get(
    SSO_API_URL + 'emails/' + email, auth=auth,
    headers={'Accept': 'application/json'})

Use cases

Obtain email details

GET /api/v2/emails/<email address>

Obtain details for a given email address

Form Parameters:
  • verified – whether the email was verified or not
  • date_created – date when email was linked to the account
  • email – email address
  • href – link to this resource
Status Codes:


  • INVALID_DATA: Provided email is not correct.

    Error status code 400.

    This error has no additional fields in extra.



POST /api/v2/emails/ HTTP/1.1
Accept: application/json


HTTP/1.1 200 OK
Content-Type: application/json
Location: /api/v2/emails/

  "email": "",
  "verified": true,
  "href": "/api/v2/emails/",
  "date_created": "2014-12-11T14:16:41"

If the OAuth signature is not correct:

Content-Type: application/json

  "message": "Your email/password isn't correct.",
  "extra": {}