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": [ ]
}