Email Servers

The Email Servers API allows you to configure a custom external email provider to send email notifications. By default, notifications such as the welcome email or an account recovery email are sent through an Okta-managed SMTP server. Adding a custom email provider gives you more control over your email delivery.

When you configure a custom email provider with an OAuth 2.0 authentication method, review Custom email providers with OAuth 2.0.

List all enrolled SMTP servers
Identity Engine
OAuth 2.0 scopes:
  • okta.emailServers.read

Lists all the enrolled custom SMTP server configurations

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/email-servers
Request samples 
Response samples 
application/json
{
  • "email-servers": [
    • {
      }
    ]
}
Create a custom SMTP server
Identity Engine
OAuth 2.0 scopes: 
  • okta.emailServers.manage
Creates a custom email SMTP server configuration for your org.


For more information about configuring the OAuth 2.0 authentication methods, see Custom email providers with OAuth 2.0.


Request 
Request Body schema: application/json
alias
required
string
Human-readable name for your SMTP server


 
enabled
required
boolean
If true, all email traffic is routed through your SMTP server


 
host
required
string
Hostname or IP address of your SMTP server


 
port
required
integer
Port number of your SMTP server


 
username
required
string
Username that's used to access your SMTP server


 
password
required
string
The password of the user account that's used to sign in to your SMTP server


 
Responses 
201
Successfully enrolled server credentials


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/email-servers
Request samples 
application/json
{
  • "alias": "CustomServer1",
  • "enabled": true,
  • "host": "smtp.example.com",
  • "port": 587,
  • "username": "user@example.com",
  • "password": "securepassword"
}
Response samples 
application/json
{
  • "id": "ces7n3u7sSohfoaou0g1",
  • "alias": "CustomServer1",
  • "enabled": true,
  • "authType": "BASIC_SMTP_AUTH",
  • "host": "smtp.example.com",
  • "port": 587,
  • "username": "user@example.com"
}
Retrieve an SMTP server configuration
Identity Engine
OAuth 2.0 scopes: 
  • okta.emailServers.read
Retrieves the specified custom SMTP server configuration


Request 
path Parameters
emailServerId
required
string
ID of your SMTP server configuration


 
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/email-servers/{emailServerId}
Request samples 
Response samples 
application/json
{
  • "id": "ces7n3u7sSohfoaou0g1",
  • "alias": "CustomServer1",
  • "enabled": true,
  • "authType": "BASIC_SMTP_AUTH",
  • "host": "smtp.example.com",
  • "port": 587,
  • "username": "user@example.com"
}
Update an SMTP server configuration
Identity Engine
OAuth 2.0 scopes: 
  • okta.emailServers.manage
Updates the specified custom SMTP server configuration


Request 
path Parameters
emailServerId
required
string
ID of your SMTP server configuration


 
Request Body schema: application/json
alias
required
string
Human-readable name for your SMTP server


 
enabled
required
boolean
If true, all email traffic is routed through your SMTP server


 
host
required
string
Hostname or IP address of your SMTP server


 
port
required
integer
Port number of your SMTP server


 
username
required
string
Username that's used to access your SMTP server


 
password
required
string
The password of the user account that's used to sign in to your SMTP server


 
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


patch/api/v1/email-servers/{emailServerId}
Request samples 
application/json
{
  • "alias": "CustomServer1 New Alias",
  • "password": "New password"
}
Response samples 
application/json
{
  • "id": "ces7n3u7sSohfoaou0g1",
  • "alias": "CustomServer1 New Alias",
  • "enabled": true,
  • "authType": "BASIC_SMTP_AUTH",
  • "host": "smtp.example.com",
  • "port": 587,
  • "username": "user@example.com"
}
Delete an SMTP server configuration
Identity Engine
OAuth 2.0 scopes: 
  • okta.emailServers.manage
Deletes the specified custom SMTP server configuration


Request 
path Parameters
emailServerId
required
string
ID of your SMTP server configuration


 
Responses 
204
No content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/email-servers/{emailServerId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Test an SMTP server configuration
Identity Engine
OAuth 2.0 scopes: 
  • okta.emailServers.manage
Tests the specified custom SMTP server configuration


Request 
path Parameters
emailServerId
required
string
ID of your SMTP server configuration


 
Request Body schema: application/json
fromAddress
required
string
Email address that sends test emails


 
toAddress
required
string
Email address that receives test emails


 
Responses 
204
No content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/email-servers/{emailServerId}/test
Request samples 
application/json
{
  • "fromAddress": "sender@host.com",
  • "toAddress": "receiver@host.com"
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}