CONNECT users may have zero or more emails stored in their account. The emails can be in two different states: verified and unverified. emails are usually verified by the CONNECT user by clicking on a verification link sent to the email address.

The customer can add more email addresses through the My CONNECT account client (at https://connect.telenordigital.com/gui/mypage). Verification emails will be sent automatically when the My CONNECT account client is used.

When registering emails through the API the emails are by default not verified. It is highly recommended to let the CONNECT users manage the email settings through the My CONNECT account administration pages.

Emails 

Email collection resource 

Add new email
/id/users/{connectId}/mails

Add a new email to the CONNECT user. Note that this won’t generate a verification mail. The verification mail must be initiated manually. The verification mail will contain a link to CONNECT which allows the user to verify their ownership of the email address. Note that there is no enforced uniqueness on the priority field and the priority field might not be unique for all emails.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

  • Request
  • The request structure may contain these fields:

    • address (required): The email address.

    • verified (optional, default false): The verified flag for the email.

    • priority (optional, default 1): The priority of the email address.

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
      "address": "john.doe@example.com",
      "verified": true,
      "priority": 1
    }
  • Response  201
  • The email address is added to the user. Please note that when you add a new unverified email address a verification email will not be sent and the email must be verified manually later. The response will contain these fields:

    • href: A reference to the email resource itself.

    • id: The ID of the email address. This an immutable value.

    • generation: If email is updated, this value will be changed.

    • address: The email address.

    • verified: The verified flag.

    • priority: The priority of the email address.

    • verificationCode: This field is no longer used.

    • link: An array of references to relevant resources.

    Headers
    Content-Type: application/json
    Body
    {
      "href": "/id/users/5933640566699794432/mails/5963640566699794432",
      "id": "5933640566699794432",
      "generation": 5963640566699795000,
      "address": "john.doe@example.com",
      "verified": false,
      "priority": 2,
      "verificationCode": "ggfoobarbazbbq",
      "link": [
        {
          "rel": "self",
          "href": "/id/users/5933640566699794432/mails/5963640566699794432",
          "type": null,
          "idref": null
        },
        {
          "rel": "user",
          "href": "/id/users/5933640566699794432/",
          "type": null,
          "idref": null
        },
        {
          "rel": "verify",
          "href": "/id/users/5933640566699794432/mails/5963640566699794432/verify",
          "type": "action",
          "idref": null
        },
        {
          "rel": "sendverificationmail",
          "href": "/id/users/5933640566699794432/mails/5963640566699794432/sendverificationmail",
          "type": "action",
          "idref": null
        }
      ]
    }
  • Response  400
  • The email address is invalid and can’t be added to the CONNECT user.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 400,
      "errorMessage": "Mail address is invalid."
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The user specified can’t be found. Note that the content-type returned by the service isn’t application/json but text/html.

    Headers
    Content-Type: text/html
  • Response  409
  • The email specified is already in use by another CONNECT user.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 409,
      "errorMessage": "Mail already in use."
    }
  • Response  500
  • There has been a server-side processing error. Retry the request in a while if possible. Note that you might get this response if you don’t provide a request body.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "<error message>"
    }
Get list of emails
/id/users/{connectId}/mails

Retrieve a list of all emails stored on the CONNECT user.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.email.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • The mail array contains a list of all the emails stored on the CONNECT user. Note that the priority field might be the same for more than one address.

    Headers
    Content-Type: application/json
    Body
    {
      "mail": [
        {
          "href": "/id/users/234/mails/382",
          "id": "382",
          "generation": 588,
          "address": "john.doe@example.com",
          "verified": true,
          "priority": 0,
          "verificationCode": null,
          "link": [
            {
              "rel": "self",
              "href": "/id/users/234/mails/382",
              "type": null,
              "idref": null
            },
            {
              "rel": "user",
              "href": "/id/users/234/",
              "type": null,
              "idref": null
            },
            {
              "rel": "verify",
              "href": "/id/users/234/mails/382/verify",
              "type": "action",
              "idref": null
            },
            {
              "rel": "sendverificationmail",
              "href": "/id/users/234/mails/382/sendverificationmail",
              "type": "action",
              "idref": null
            }
          ]
        },
        {
          "href": "/id/users/234/mails/596",
          "id": "596",
          "generation": 497,
          "address": "john.does-alternate-address@example.com",
          "verified": false,
          "priority": 1,
          "verificationCode": "8iklhdqleqep",
          "link": [
            {
              "rel": "self",
              "href": "/id/users/234/mails/596",
              "type": null,
              "idref": null
            },
            {
              "rel": "user",
              "href": "/id/users/234/",
              "type": null,
              "idref": null
            },
            {
              "rel": "verify",
              "href": "/id/users/234/mails/596/verify",
              "type": "action",
              "idref": null
            },
            {
              "rel": "sendverificationmail",
              "href": "/id/users/234/mails/596/sendverificationmail",
              "type": "action",
              "idref": null
            }
          ]
        }
      ]
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404
  • The user specified can’t be found. Note that the content-type returned by the service isn’t application/json but text/html.

    Headers
    Content-Type: text/html
  • Response  500
  • There has been a server-side processing error. Retry the request in a while if possible. Note that the MIME type returned can be any of application/json, text/plain or text/html. We are very sorry for this. If you receive this response code wait for a while, then retry the operation. If the error persists please let us know.

    Headers
    Content-Type: text/plain, application/json, text/html

Email resource 

Get email
/id/users/{connectId}/mails/{emailId}

Retrieve a single email identified by the connectId and emailId.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.email.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    emailId
    string (required) 

    The email ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "href": "/id/users/588/mails/596",
      "id": "596",
      "generation": 599,
      "link": [
        {
          "rel": "self",
          "href": "/id/users/5887581927518507008/mails/5963640566699794432",
          "type": null,
          "idref": null
        },
        {
          "rel": "user",
          "href": "/id/users/5887581927518507008/",
          "type": null,
          "idref": null
        },
        {
          "rel": "verify",
          "href": "/id/users/5887581927518507008/mails/5963640566699794432/verify",
          "type": "action",
          "idref": null
        },
        {
          "rel": "sendverificationmail",
          "href": "/id/users/5887581927518507008/mails/5963640566699794432/sendverificationmail",
          "type": "action",
          "idref": null
        }
      ],
      "address": "stalehd+apidemo@comoyo.com",
      "verified": false,
      "priority": 1,
      "verificationCode": "8iklhdqleqep"
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404
  • Either the CONNECT user can’t be found or an email with the given ID can’t be found.

    Headers
    Content-Type: text/html
  • Response  503
  • There was an error querying for the specified user and/or email. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: text/plain
    Body
    Plain text error message.
Delete email
/id/users/{connectId}/mails/{emailId}

Delete an email linked to the CONNECT user. It is highly recommended to let the customers themselves manage this through the My CONNECT account client (at https://connect.telenordigital.com/gui/mypage)

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    emailId
    string (required) 

    The email ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The email was successfully removed.

    Headers
    Content-Type: application/json
  • Response  400
  • If this is the last verified email address it can’t be deleted.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 400,
      "errorMessage": "Can not delete last verified communication channel."
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The email or CONNECT user can’t be found.

    Headers
    Content-Type: text/html
  • Response  500
  • There was an error processing the request. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: text/html

Make email primary 

Set email to primary email
/id/users/{connectId}/mails/{emailId}/makeprimary

Assign the email address to be the primary one. If there is another email set on the account that has the highest priority it will be be set to a lower priority. It is highly recommended to let the customers manage this themselves through the My CONNECT account client (at https://connect.telenordigital.com/gui/mypage)

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    emailId
    string (required) 

    The email ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The email is set to the primary communication channel.

    Headers
    Content-Type: application/json
  • Response  400
  • The email address isn’t verified. The primary email address must be set to verified before it is set as the primary email.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 400,
      "errorMessage": "Can not change from verified mail to unverified mail."
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The CONNECT user or the email ID can’t be found.

    Headers
    Content-Type: text/html
  • Response  409
  • The email address is already in use by another CONNECT user.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 409,
      "errorMessage": "Can only change to available usernames."
    }
  • Response  500
  • There was an error processing the request. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
        "errorCode": 503,
        "errorMessage": "Failed to set mail $emailId as primary for user
                                        $connectId, status: $code"
    }

Verify email address 

Manually verify the email address without requiring the customer to go through a mail verification round-trip. It is however highly recommended to do the round-trip since this ensures us that the email address is a valid one that the customer can access.

Verify email
/id/users/{connectId}/mails/{emailId}/verify
  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    emailId
    string (required) 

    The email ID.

  • Request
  • The request body contains the verification code as plain text.

    Headers
    Content-Type: text/plain
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    (verificationCode)
  • Response  204
  • The email has been successfully verified.

    Headers
    Content-Type: text/plain
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  403
  • An incorrect or missing verification code is used.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 403,
      "errorMessage": "Incorrect verification code."
    }
  • Response  404
  • The CONNECT user or email ID is unknown.

    Headers
    Content-Type: text/html
  • Response  500
  • There was an error processing the request. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
        "errorCode": 503,
        "errorMessage": "Failed to verify mail $emailId as for user
                                        $connectId, status: $code"
    }

Send verification email 

A verification email is required to ensure that the email provided by the customer is an email address the user has access to. The verification email contains a link the user can click. Once the email is verified we are sure that the customer can be reached through this email address (with the usual reservations).

/id/users/{connectId}/mails/{emailId}/sendverificationmail
  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    emailId
    string (required) 

    The email ID.

  • Request
  • The request body contains the parameters for the verification mail. Just the baseUrl field is required, both brand and locale are optional. If the locale field is omitted the email will be sent in the en-EN locale, ie. English. The baseUrl parameter should be set to the host that will process the verification link. If you want the default behaviour use https://api.telenor.io

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
      "brand": "$brand",
      "locale": "$userLocale",
      "baseUrl": "$baseUrl"
    }
  • Response  204
  • Verification mail has been sent to the specified email address.

    Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • Headers
    Content-Type: text/html
  • Response  409
  • The CONNECT user or email address can’t be found. This response code might not make any sense to you but please don’t judge us.

    Headers
    Content-Type: application/json
  • Response  500
  • There was an error processing the request. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: application/json

Send activation email 

The final step when registering for CONNECT is to activate the account. This usually consists of setting the password and the user’s full name plus any additional emails or phones the user wants to register.

/id/users/{connectId}/mails/{emailId}/sendactivationmail
  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    emailId
    string (required) 

    The email ID.

  • Request
  • The request body contains the parameters for the activation mail. Just the baseUrl field is required, both brand and locale are optional. If the locale field is omitted the email will be sent in the en-EN locale, ie. English. The baseUrl parameter should be set to the host that will process the activation link. If you want the default behaviour use https://api.telenor.io

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
      "brand": "$brand",
      "locale": "$userLocale",
      "baseUrl": "$baseUrl"
    }
  • Response  204
  • Activation mail has been sent to the specified email address.

    Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The user is already activated. Please don’t judge us. This should really be 409, not 404. It is embarrassing enough to reply with the incorrect MIME type.

    Headers
    Content-Type: text/html
  • Response  409
  • The CONNECT user or email address can’t be found. Please, please don’t judge us. This is a brainfart of epic dimensions. It has even been copied and pasted from the verification mail code.

    Headers
    Content-Type: application/json
  • Response  500
  • There was an error processing the request. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: application/json

© 2017 Telenor Digital AS