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