This article explains how to change or modify a custom e-mail domain and describes API operations for Custom Email Domains to replace the email address sender or display name.
- Customizations
- Brands
- Email Domains
- Okta Identity Engine (OIE)
- API
- Postman API
In some situations, Admins may want to revise or replace a Custom Email Domain without being forced to delete it or remove it from the Admin Console > Customizations > Brands UI. Removing the existing custom email domain implies a new reconfiguration process from the start, with CNAME and TXT records updated on the domain side. That procedure can be time-consuming or even limited based on the number of DNS records the domain has access to.
NOTE: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.
Revising an existing Custom Email domain can be done using Okta API operations for Email Domains. This can be done by using the curl command for the REST API, following the OKta documentation step by step.
First, the emailDomainID is required for inclusion in the PUT call. Additionally, the API key is needed for Authorization, and finally, the displayName or username of the email domain must be changed in the body below.
To retrieve the emailDomainID, use the below API call:
GET https://{yourOktaDomain}/api/v1/email-domains
curl -i -X GET \
https://subdomain.okta.com/api/v1/email-domains \
-H 'Authorization: YOUR_API_KEY_HERE'The output should include content like below. The highlighted is the emailDomainID. Make sure the validationStatus, displayName, and userName match the existing custom email domain.
"id": "OeD114iNkrcN6aR680g4",
"validationStatus": "NOT_STARTED",
"displayName": "Admin",
"userName": "admin",
"domain": "example.com",
"validationSubdomain": "mail",
...
To update the custom email domain, use the following API call:
PUT https://{yourOktaDomain}/api/v1/email-domains/{emailDomainId}
curl -i -X PUT \
'https://subdomain.okta.com/api/v1/email-domains/{emailDomainId}?expand=brands' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"displayName": "IT Admin",
"userName": "noreply"
}'
