The CONNECT emails API

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

POST

/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.

RequestShowHide
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 201ShowHide

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 400ShowHide

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 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
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 409ShowHide

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 500ShowHide
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

GET

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Response 200ShowHide

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 401ShowHide

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 404ShowHide
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 500ShowHide
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

GET

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Response 200ShowHide

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 401ShowHide

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 404ShowHide
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 503ShowHide
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

DELETE

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Basic <Base64 encoding of username:password>

Response 204ShowHide
The email was successfully removed.

Headers
```
Content-Type: application/json
```
Response 400ShowHide

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 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
The email or CONNECT user can’t be found.

Headers
```
Content-Type: text/html
```
Response 500ShowHide
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

POST

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Basic <Base64 encoding of username:password>

Response 204ShowHide
The email is set to the primary communication channel.

Headers
```
Content-Type: application/json
```
Response 400ShowHide
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 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
The CONNECT user or the email ID can’t be found.

Headers
```
Content-Type: text/html
```
Response 409ShowHide

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 500ShowHide

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

POST

/id/users/{connectId}/mails/{emailId}/verify

Parameters
connectId
string (required)
The CONNECT ID.

emailId
string (required)
The email ID.

RequestShowHide

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 204ShowHide
The email has been successfully verified.

Headers
```
Content-Type: text/plain
```
Response 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 403ShowHide

An incorrect or missing verification code is used.

Headers

Content-Type: application/json

Body

{
  "errorCode": 403,
  "errorMessage": "Incorrect verification code."
}

Response 404ShowHide
The CONNECT user or email ID is unknown.

Headers
```
Content-Type: text/html
```
Response 500ShowHide

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).

POST

/id/users/{connectId}/mails/{emailId}/sendverificationmail

Parameters
connectId
string (required)
The CONNECT ID.

emailId
string (required)
The email ID.

RequestShowHide
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 204ShowHide
Verification mail has been sent to the specified email address.

Headers
```
Content-Type: application/json
```
Response 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
Headers
```
Content-Type: text/html
```
Response 409ShowHide
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 500ShowHide
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.

POST

/id/users/{connectId}/mails/{emailId}/sendactivationmail

Parameters
connectId
string (required)
The CONNECT ID.

emailId
string (required)
The email ID.

RequestShowHide
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 204ShowHide
Activation mail has been sent to the specified email address.

Headers
```
Content-Type: application/json
```
Response 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
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 409ShowHide
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 500ShowHide
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
```