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.

List all enrolled SMTP servers
Identity Engine
OAuth 2.0: 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: okta.emailServers.manage
Creates a custom email SMTP server configuration for your org


Request 
Request Body schema: application/json
host
required
string
Hostname or IP address of your SMTP server


 
port
required
integer
Port number of your SMTP server


 
username
required
string
Username used to access your SMTP server


 
password
required
string
Password used to access your SMTP server


 
alias
required
string
Human-readable name for your SMTP server


 
enabled
boolean
If true, routes all email traffic through 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": "192.168.160.1",
  • "port": 587,
  • "username": "aUser",
  • "password": "string"
}
Response samples 
application/json
{
  • "alias": "CustomServer1",
  • "enabled": true,
  • "host": "192.168.160.1",
  • "port": 587,
  • "username": "aUser",
  • "id": "string"
}
Retrieve an SMTP server configuration
Identity Engine
OAuth 2.0: 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
{
  • "email-servers": [
    • {
      }
    ]
}
Update an SMTP server configuration
Identity Engine
OAuth 2.0: 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
string
Human-readable name for your SMTP server


 
enabled
boolean
If true, routes all email traffic through your SMTP server


 
host
string
Hostname or IP address of your SMTP server


 
port
integer
Port number of your SMTP server


 
username
string
Username used to access your SMTP server


 
password
string
Password used to access 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",
  • "enabled": true,
  • "host": "192.168.160.1",
  • "port": 587,
  • "username": "aUser",
  • "password": "string"
}
Response samples 
application/json
{
  • "alias": "CustomServer1",
  • "enabled": true,
  • "host": "192.168.160.1",
  • "port": 587,
  • "username": "aUser",
  • "id": "string"
}
Delete an SMTP server configuration
Identity Engine
OAuth 2.0: 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: 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
from
required
string
Email address that sends test emails


 
to
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
{
  • "from": "sender@host.com",
  • "to": "receiver@host.com"
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}