Email

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.

Authentication

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 foo@example.com with password password:

import json

import requests
from requests_oauthlib import OAuth1


SSO_ROOT_URL = 'https://login.ubuntu.com/'
SSO_API_URL = SSO_ROOT_URL + 'api/v2/'

email = 'foo@example.com'
data = {'email': email, 'password': 'password', 'token_name': 'Doc test'}
response = requests.post(
    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'})
 print(response.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:

Errors

  • INVALID_DATA: Provided email is not correct.

    Error status code 400.

    This error has no additional fields in extra.

Examples

Request:

POST /api/v2/emails/foo@example.com HTTP/1.1
Host: login.ubuntu.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Location: /api/v2/emails/foo@example.com

{
  "email": "foo@example.com",
  "verified": true,
  "href": "/api/v2/emails/foo%40example.com",
  "date_created": "2014-12-11T14:16:41"
}

If the OAuth signature is not correct:

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json

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