Email

The MyAccount Email API provides operations to enroll, update, and delete emails. The API also provides utilities to create, view, and answer verification challenges.

API versioning

A valid API version in the Accept header is required to access the API. Current version: 1.0.0

Accept: application/json; okta-version=1.0.0

List all Emails
OAuth 2.0: okta.myAccount.email.read

Lists all of the current user's email information: a collection of links for each email that describe the acceptable operations

Responses
200

Example response

401

Unauthorized

get/idp/myaccount/emails
Request samples
Response samples
application/json;okta-version=1.0.0
[]

Create an Email
OAuth 2.0: okta.myAccount.email.manage

Creates a primary or secondary email address for the user's account. The new email address has an UNVERIFIED status.

Request
Request Body schema: application/json

New email

required
object

Defines the email address on the profile

email
required
string <email>
sendEmail
boolean
Default: true

Specifies whether Okta or the application sends an email to the end user

state
string

Any application state that the client wishes to persist across the email challenge flow, and receive at the callback URL. Define the callback URL in the OIDC app configuration. This parameter proves to the client that the email link is verified.

role
string
Enum: "PRIMARY" "SECONDARY"
Responses
201

Example response

400

Bad Request

401

Unauthorized

403

Forbidden

409

Conflict

post/idp/myaccount/emails
Request samples
application/json
{
  • "profile": {
    • "email": "saml.jackson@example.com"
    },
  • "sendEmail": true,
  • "role": "PRIMARY",
  • "state": "JPcFLTwOq7UvoFtmRd3EnyQwsR0PbDSI"
}
Response samples
application/json;okta-version=1.0.0
{}

Retrieve an Email
OAuth 2.0: okta.myAccount.email.read

Retrieves the current user's email information by ID: a collection of links that describe the acceptable email operations

Request
path Parameters
id
required
string

The email ID Use GET /idp/myaccount/emails or POST /idp/myaccount/emails operations to obtain the email ID when adding a new email address.

Example: 69dca29c2d8dbb0dca14395ccdb92317
Responses
200

Example response

401

Unauthorized

get/idp/myaccount/emails/{id}
Request samples
Response samples
application/json;okta-version=1.0.0
{}

Delete an Email
OAuth 2.0: okta.myAccount.email.manage

Deletes the current user's email information by ID. You can only delete unverified primary and secondary emails.

Request
path Parameters
id
required
string

The email ID Use GET /idp/myaccount/emails or POST /idp/myaccount/emails operations to obtain the email ID when adding a new email address.

Example: 69dca29c2d8dbb0dca14395ccdb92317
Responses
204

No Content

400

Bad Request

401

Unauthorized

404

Not Found

delete/idp/myaccount/emails/{id}
Request samples
Response samples
application/json;okta-version=1.0.0
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: Email",
  • "errorLink": "E0000001",
  • "errorId": "oaejUwz8U5FQ_SyggQwz1kC3w",
  • "errorCauses": [
    • {
      }
    ]
}

Send an Email Challenge
OAuth 2.0: okta.myAccount.email.manage

Sends a "Confirm email address change" email to the user with a one-time passcode for verification. Also, the user receives a "Notice of pending email address change" email. After the challenge is verified, the email becomes active.

Request
path Parameters
id
required
string

The email ID

Use the GET /idp/myaccount/emails or POST /idp/myaccount/emails operations when adding a new email address.

Example: 00T196qTp3LIMZQ0L0g3
Request Body schema: application/json
state
required
string

(Optional) The state parameter that contains the state of the client

Responses
201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/idp/myaccount/emails/{id}/challenge
Request samples
application/json
{
  • "state": "JPcFLTwOq7UvoFtmRd3EnyQwsR0PbDSI"
}
Response samples
application/json;okta-version=1.0.0
{}

Verify an Email OTP
OAuth 2.0: okta.myAccount.email.manage

Verifies the email challenge with the code that the user receives from the "Confirm email address change" email. Once verified, the email is active.

Request
path Parameters
id
required
string

The email ID Use GET /idp/myaccount/emails or POST /idp/myaccount/emails operations to obtain the email ID when adding a new email address.

Example: 00T196qTp3LIMZQ0L0g3
challengeId
required
string

The challengeId of the email Use the POST /idp/myaccount/emails/{id}/challenge operation to obtain the challengeId when creating a new challenge.

Example: x1MDGzUb
Request Body schema: application/json
verificationCode
required
string <password>

A six-digit verification code sent to the user in the "Confirm email address change" email

Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

post/idp/myaccount/emails/{id}/challenge/{challengeId}/verify
Request samples
application/json
{
  • "verificationCode": "456058"
}
Response samples
application/json;okta-version=1.0.0
{
  • "errorCode": "E0000015",
  • "errorSummary": "You do not have permission to access the feature you are requesting",
  • "errorLink": "E0000015",
  • "errorId": "oaeStOuPPxDRUm3PJhf-tL7bQ",
  • "errorCauses": [ ]
}