.. vim: ft=rst

.. _email:

=====
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
:ref:`OAuth token <token_oauth>` resource.

Example of OAuth signing code, assuming an existing account ``foo@example.com``
with password ``password``:

.. sourcecode:: python

   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
=========

.. _email-details:

Obtain email details
--------------------

.. http:get:: /api/v2/emails/<email address>

    Obtain details for a given email address

    :form verified: whether the email was verified or not
    :form date_created: date when email was linked to the account
    :form email: email address
    :form href: link to this resource

    :status 200: ok
    :status 401: OAuth signature is not valid

Errors
......

* **INVALID_DATA**: Provided email is not correct.

  Error status code 400.

  This error has no additional fields in ``extra``.

Examples
........

**Request**:

.. sourcecode:: http

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

**Response**:

.. sourcecode:: http

   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:

.. sourcecode:: http

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

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