Email Domains

The Email Domains API provides operations to manage email domains for your organization.

List all Email Domains
OAuth 2.0: okta.emailDomains.read

Lists all the Email Domains in your org

Request
query Parameters
expand
Array of strings

Specifies additional metadata to be included in the response

Items Value: "brands"
Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/email-domains
Request samples 
Response samples 
application/json
{
  • "id": "OeD114iNkrcN6aR680g4",
  • "validationStatus": "NOT_STARTED",
  • "displayName": "Admin",
  • "userName": "admin",
  • "domain": "example.com",
  • "validationSubdomain": "mail",
  • "dnsValidationRecords": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}
Create an Email Domain
OAuth 2.0: okta.emailDomains.manage
Creates an Email Domain in your org


Request 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Value: "brands"  
Request Body schema: application/json
required
brandId
required
string
 
domain
required
string
 
validationSubdomain
string
 Default:  "mail"
Subdomain for the email sender's custom mail domain. Specify your subdomain when you configure a custom mail domain.


 
displayName
required
string
 
userName
required
string
 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


409
Conflict


429
Too Many Requests


post/api/v1/email-domains
Request samples 
application/json
{
  • "displayName": "Admin",
  • "userName": "admin",
  • "domain": "example.com",
  • "brandId": "bnd100iSrkcN6aR680g1",
  • "validationSubdomain": "mail"
}
Response samples 
application/json
{
  • "id": "OeD114iNkrcN6aR680g4",
  • "validationStatus": "NOT_STARTED",
  • "displayName": "Admin",
  • "userName": "admin",
  • "domain": "example.com",
  • "validationSubdomain": "mail",
  • "dnsValidationRecords": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}
Retrieve an Email Domain
OAuth 2.0: okta.emailDomains.read
Retrieves an Email Domain by emailDomainId


Request 
path Parameters
emailDomainId
required
string
The ID of the email domain.


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Value: "brands"  
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/email-domains/{emailDomainId}
Request samples 
Response samples 
application/json
{
  • "id": "OeD114iNkrcN6aR680g4",
  • "validationStatus": "NOT_STARTED",
  • "displayName": "Admin",
  • "userName": "admin",
  • "domain": "example.com",
  • "validationSubdomain": "mail",
  • "dnsValidationRecords": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}
Replace an Email Domain
OAuth 2.0: okta.emailDomains.manage
Replaces associated username and sender display name by emailDomainId


Request 
path Parameters
emailDomainId
required
string
The ID of the email domain.


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Value: "brands"  
Request Body schema: application/json
required
displayName
required
string
 
userName
required
string
 
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/email-domains/{emailDomainId}
Request samples 
application/json
{
  • "displayName": "IT Admin",
  • "userName": "noreply"
}
Response samples 
application/json
{
  • "id": "OeD114iNkrcN6aR680g4",
  • "validationStatus": "NOT_STARTED",
  • "displayName": "IT Admin",
  • "userName": "noreply",
  • "domain": "example.com",
  • "validationSubdomain": "mail",
  • "dnsValidationRecords": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}
Delete an Email Domain
OAuth 2.0: okta.emailDomains.manage
Deletes an Email Domain by emailDomainId


Request 
path Parameters
emailDomainId
required
string
The ID of the email domain.


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Value: "brands"  
Responses 
204
No Content


400
Unable to delete custom email domain due to mail provider specific restrictions


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/email-domains/{emailDomainId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000216",
  • "errorSummary": "Email domain can't be deleted due to mail provider restrictions.",
  • "errorLink": "E0000216",
  • "errorId": "oaeEdRqprFuTyKokyYPbURJkB",
  • "errorCauses": [ ]
}
Verify an Email Domain
OAuth 2.0: okta.emailDomains.manage
Verifies an Email Domain by emailDomainId


Request 
path Parameters
emailDomainId
required
string
The ID of the email domain.


 
Responses 
200
Success


400
Email domain could not be verified by mail provider


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/email-domains/{emailDomainId}/verify
Request samples 
Response samples 
application/json
{
  • "id": "OeD114iNkrcN6aR680g4",
  • "validationStatus": "VERIFIED",
  • "displayName": "IT Admin",
  • "userName": "noreply",
  • "domain": "example.com",
  • "validationSubdomain": "mail",
  • "dnsValidationRecords": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}