SMTP Settings

Configuration of the SMTP server used for sending outbound emails from the tenant.

OPTIONS /api/administration/smtp-settings/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

OPTIONS /api/administration/smtp-settings/

Response

Successful status 200 OK
Response body:

json

{
    "details": {
        "schema": [
            {
                "alias": "password",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 128
                    }
                ]
            },
            {
                "alias": "host",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 63
                    }
                ]
            },
            {
                "alias": "port",
                "required": true,
                "type": "int"
            },
            {
                "alias": "tls",
                "type": "bool"
            },
            {
                "alias": "username",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 254
                    }
                ]
            },
            {
                "alias": "from_email",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "email"
                    },
                    {
                        "type": "max_length",
                        "length": 254
                    }
                ]
            },
            {
                "alias": "failure_email",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 255
                    },
                    {
                        "type": "max_value",
                        "length": 10
                    }
                ]
            },
            {
                "alias": "authorization_method",
                "type": "enum",
                "required": false,
                "values": [
                    {
                        "value": "username_and_password",
                        "text": "Username and Password"
                    },
                    {
                        "value": "microsoft_client_credentials",
                        "text": "Microsoft Client Credentials"
                    }
                ],
                "schema_by_authorization_method": [
                    {
                        "authorization_method": "username_and_password",
                        "schema": [
                            {
                                "alias": "password",
                                "type": "string",
                                "required": true,
                                "validators": [
                                    {
                                        "type": "max_length",
                                        "length": 128
                                    }
                                ]
                            }
                        ]
                    },
                    {
                        "authorization_method": "microsoft_client_credentials",
                        "schema": [
                            {
                                "alias": "authentication_object",
                                "type": "enum",
                                "required": true,
                                "autocomplete": "/api/authentication-objects/?provider=microsoft_client_credentials"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

GET /api/administration/smtp-settings/

Permissions

Requires authentication and outbound_mail_setup.view permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/administration/smtp-settings/

Response

Key	Type	Notes
username	string
port	int
tls	bool
host	string
from_email	string
failure_email	string
authorization_method	enum	Values: username_and_password, microsoft_client_credentials
authentication_object	int

Successful status 200 OK
Response body schema:

json

{ 
 "username": "ticket.branch.mailserver@autologyx.net", 
 "port": 10587, 
 "tls": true, 
 "host": "clust.mx.nwc.xxx", 
 "from_email": "example1@email.com", 
 "failure_email": "example2@email.com, example9@email.com, example10@email.com, example11@email.com",
 "authorization_method": "username_and_password", 
 "authentication_object": null
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

PATCH /api/administration/smtp-settings/

Permissions

Requires authentication and outbound_mail_setup.edit permission.

Request

Key	Type	Notes
password	string
username	string
port	int
tls	bool
host	string
from_email	string
failure_email	string
authorization_method	enum	Values: username_and_password, microsoft_client_credentials
authentication_object	int	Required when `authorization_method` is `microsoft_client_credentials`

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

PATCH /api/administration/smtp-settings/ 

{ 
   "password": "Passwod", 
   "username": "ticket.branch.mailserver@autologyx.net", 
   "port": 10587, 
   "tls": true, 
   "host": "clust.mx.nwc.xxx", 
   "from_email": "example1@email.com", 
   "failure_email": "example6@email.com, example7@email.com",
   "authorization_method": "microsoft_client_credentials",
   "authentication_object": 1
}

Response

Key	Type	Notes
username	string
port	int
tls	bool
host	string
from_email	string
failure_email	string
authorization_method	string
authentication_object	int

Successful status 200 OK
Response body schema:

json

{ 
 "username": "ticket.branch.mailserver@autologyx.net", 
 "port": 10587, 
 "tls": true, 
 "host": "clust.mx.nwc.xxx", 
 "from_email": "example1@email.com", 
 "failure_email": "example6@email.com, example7@email.com",
 "authorization_method": "microsoft_client_credentials",
 "authentication_object": 1
}

Errors

Cause	Response code	Message
"username" is empty string	400 Bad Request	"username": ["This field may not be blank."]
"username" is null	400 Bad Request	"username": ["This field may not be null."]
"username" has > 254 chars	400 Bad Request	"username": ["Ensure this field has no more than 254 characters."]
"password" is empty string	400 Bad Request	"password": ["This field may not be blank."]
"password" is null	400 Bad Request	"password": ["This field may not be null."]
"password" has > 128 chars	400 Bad Request	"password": ["Ensure this field has no more than 128 characters."]
"port" is required	400 Bad Request	"port": ["This field is required."]
"port" is invalid	400 Bad Request	"port": ["A valid integer is required."]
"port" < 0	400 Bad Request	"port": ["Ensure this value is greater than or equal to 0."]
"port" > 65535	400 Bad Request	"port": ["Ensure this value is less than or equal to 65535."]
"tls" invalid	400 Bad Request	"tls": ["Must be a valid boolean."]
"host" is required	400 Bad Request	"host": ["This field is required."]
"host" has > 63 chars	400 Bad Request	"host": ["Ensure this field has no more than 63 characters."]
"from_email" has > 254 chars	400 Bad Request	"from_email": ["Ensure this field has no more than 254 characters."]
"failure_email" has > 255 chars	400 Bad Request	"failure_email": ["Ensure this field has no more than 255 characters."]
"failure_email" has > 10 comma separated items	400 Bad Request	"failure_email": ["Up to 10 items allowed."]
"authorization_method" has invalid value	400 Bad Request	"authorization_method": ["{value} is not a valid choice."]
"authentication_object" is absent when "authorization_method" is "microsoft_client_credentials"	400 Bad Request	"authentication_object": ["This field is required."]
"authentication_object" has the wrong provider type for a given "authorization_method"	400 Bad Request	"authentication_object": ["{value} is not a valid choice."]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

POST /api/administration/smtp-settings/test/

Permissions

Requires authentication and outbound_mail_setup.edit permission.

Request

Key	Type	Notes
password	string
username	string
port	int
tls	bool
host	string

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

POST /api/administration/smtp-settings/test/ 

{ 
   "password": "Passwod", 
   "username": "ticket.branch.mailserver@autologyx.net", 
   "port": 10587, 
   "tls": true, 
   "host": "clust.mx.nwc.xxx",
   "authorization_method": "username_and_password"	
}

Response

Key	Type	Notes
status	string
msg	string

Successful status 200 OK
Response body schema:

json

{
  "status":"OK",
  "msg":"Connection successfully tested."
}

Errors

Cause	Response code	Message
"username" is empty string	400 Bad Request	"username": ["This field may not be blank."]
"username" is null	400 Bad Request	"username": ["This field may not be null."]
"username" has > 254 chars	400 Bad Request	"username": ["Ensure this field has no more than 254 characters."]
"password" is empty string	400 Bad Request	"password": ["This field may not be blank."]
"password" is null	400 Bad Request	"password": ["This field may not be null."]
"password" has > 128 chars	400 Bad Request	"password": ["Ensure this field has no more than 128 characters."]
"port" is required	400 Bad Request	"port": ["This field is required."]
"port" is invalid	400 Bad Request	"port": ["A valid integer is required."]
"port" < 0	400 Bad Request	"port": ["Ensure this value is greater than or equal to 0."]
"port" > 65535	400 Bad Request	"port": ["Ensure this value is less than or equal to 65535."]
"tls" invalid	400 Bad Request	"tls": ["Must be a valid boolean."]
"host" is required	400 Bad Request	"host": ["This field is required."]
"host" has > 63 chars	400 Bad Request	"host": ["Ensure this field has no more than 63 characters."]
Failure during Ms Graph testing	400 Bad Request	"detail": "Error. Please check username, authentication object and MS Graph settings"
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

SMTP Settings ​

OPTIONS /api/administration/smtp-settings/ ​

Permissions ​

Request ​

Response ​

GET /api/administration/smtp-settings/ ​

Permissions ​

Request ​

Response ​

Errors ​

PATCH /api/administration/smtp-settings/ ​

Permissions ​

Request ​

Response ​

Errors ​

POST /api/administration/smtp-settings/test/ ​

Permissions ​

Request ​

Response ​

Errors ​

SMTP Settings

OPTIONS /api/administration/smtp-settings/

Permissions

Request

Response

GET /api/administration/smtp-settings/

Permissions

Request

Response

Errors

PATCH /api/administration/smtp-settings/

Permissions

Request

Response

Errors

POST /api/administration/smtp-settings/test/

Permissions

Request

Response

Errors