Child pages
  • WHM API 1 Functions - enable_mail_sni
Skip to end of metadata
Go to start of metadata

Description

This function enables mail SNI for an account.

Warning:

Mail SNI is not compatible with Webmail and will not function for any Webmail connection. Webmail connections use the cPanel service SSL certificate. 

Notes:

  • After you change the SNI status, you must run WHM API 1's rebuild_mail_sni_config function.
  • SNI for Mail Services is only available for Dovecot and Exim. If your server uses Courier for incoming mail services, the domain's certificate secures the outgoing mail and the server's default certificate secures the incoming mail.

    Warning:

    We removed the Courier mail server in cPanel & WHM version 54. The Courier mail server only exists for cPanel & WHM version 11.52 and earlier.


Note:

In cPanel & WHM version 60 and later, Mail SNI is always enabled.

  • Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled.
  • Functions that disable Mail SNI fail and make no changes.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/enable_mail_sni?api.version=1&domain=example.com
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/enable_mail_sni?api.version=1&domain=example.com
 Command Line
whmapi1 enable_mail_sni domain=example.com


Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
    "data": {
        "failed_domains": {},
        "updated_domains": {
            "example.com": {
                "phpopenbasedirprotect": null,
                "ip": "10.215.217.204",
                "secruleengineoff": null,
                "sslcertificatefile": "/var/cpanel/ssl/installed/certs/example_com_bfa22_f3733_1448559687_12b2a6d62c10fe634339c3c8a1ca0667.crt",
                "hascgi": "1",
                "group": "example",
                "sslcertificatekeyfile": "/var/cpanel/ssl/installed/keys/bfa22_f3733_754480b5820f4238a5dfc35042e1fa52.key",
                "usecanonicalname": "Off",
                "enable_sni_for_mail": 1,
                "user": "example",
                "owner": "example",
                "documentroot": "/home/example/public_html",
                "userdirprotect": "-1",
                "ipv6": "0101:ca75:0101:ca75:0101:ca75:0101:ca75",
                "ssl": "1",
                "serveralias": "www.example.com",
                "port": "443",
                "homedir": "/home/example",
                "servername": "example.com",
                "serveradmin": "webmaster@example.com"
            }
        }
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": "1",
        "command": "disable_mail_sni"
    }
}
 Output (XML)
<result>
    <data>
        <failed_domains/>
        <updated_domains>
            <example.com>
                <phpopenbasedirprotect/>
                <ip>192.168.0.1</ip>
                <secruleengineoff/>
                <sslcertificatefile>
                    /var/cpanel/ssl/installed/certs/steve_tld_bfa22_f3733_1448559687_12b2a6d62c10fe634339c3c8a1ca0667.crt
                </sslcertificatefile>
                <usecanonicalname>Off</usecanonicalname>
                <sslcertificatekeyfile>
                    /var/cpanel/ssl/installed/keys/bfa22_f3733_754480b5820f4238a5dfc35042e1fa52.key
                </sslcertificatekeyfile>
                <group>example</group>
                <hascgi>1</hascgi>
                <enable_sni_for_mail>0</enable_sni_for_mail>
                <user>example</user>
                <userdirprotect>-1</userdirprotect>
                <documentroot>/home/example/public_html</documentroot>
                <owner>example</owner>
                <ipv6>0101:ca75:0101:ca75:0101:ca75:0101:ca75</ipv6>
                <ssl>1</ssl>
                <serveralias>www.example.com</serveralias>
                <port>443</port>
                <homedir>/home/example</homedir>
                <servername>example.com</servername>
                <serveradmin>webmaster@example.com</serveradmin>
            </example.com>
        </updated_domains>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>disable_mail_sni</command>
    </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
domain*string

Required

An account's domain.

Note:

To enter multiple domains, increment each parameter name. For example, enter the first domain as domain-1 and the second domain as domain-2.

A valid domain on the server.example.com

Returns

Return

TypeDescriptionPossible valuesExample
failed_domainshashA hash of the domains that did not enable mail SNI.This hash includes the domain name return. 

domain name

string

The reason why the domain failed to enable SNI.

Note:

This parameter uses the domain name as the return name.

The function returns this value in the failed_domains hash.

A valid string.Sorry, example.com is not one of the domains on your account.
updated_domainshash

A hash of the domains with enabled mail SNI.

This hash includes the domain name hash.

 

domain name

hash

A hash of the domains with mail SNI enabled.

Note:

The domain name is the return's name.

The function returns this hash in the updated_domains hash.

This hash includes the phpopenbasddirprotect, ip, secruleengineoff, sslcertificatefile, hascgi, group, sslcertificatekeyfile, usecanonicalname, enable_sni_for_mail, user, owner, documentroot, userdirprotect, ipv6, ssl, serveralias, port, homedir, servername, and serveradmin returns.

Note:

If you do not use the root user to call this function, the value is 1 .

 

phpopenbaseddirprotect

string

The domain's PHP open_basedir Tweak setting.

The function returns this value in the domain name hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

ip

string

The domain's IP address.

The function returns this value in the domain name hash.

A valid IP address.192.168.0.1

secruleengineoff

Boolean

Whether the secure rules engine is off.

The function returns this value in the domain name hash.

  • 1 — Off.
  • 0 — On.
1

sslcertificatefile

string

The path to the domain's SSL certificate.

The function returns this value in the domain name hash.

An absolute file path.
 Click to view...

/var/cpanel/ssl/installed/certs/example_com_bfa22_f3733_1448559687_12b2a6d62c10fe634339c3c8a1ca0667.crt

hascgi

Boolean

Whether CGI is enabled for the account.

The function returns this value in the domain name hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

group

string

The account's group name.

The function returns this value in the domain name hash.

A valid group name.group

sslcertificatekeyfile

string

The path to the domain's private key file.

The function returns this value in the domain name hash.

A valid directory path.
 Click to view...

/var/cpanel/ssl/installed/keys/bfa22_f3733_754480b5820f4238a5dfc35042e1fa52.key

usecanonicalname

string

The domain's setting for canonical names (CNAMEs).

The function returns this value in the domain name hash.

  • On — Use the CNAME.
  • Off — Do not use the CNAME.
Off

enable_sni_for_mail

Boolean

Whether SNI for mail is enabled.

The function returns this value in the domain name hash.

  • 1 — SNI enabled.
  • 0 — SNI not enabled.
1

user

string

The cPanel account username.

The function returns this value in the domain name hash.

A valid cPanel username.user

owner

string

The WHM user who owns the cPanel account.

The function returns this value in the domain name hash.

A valid WHM username.owner

documentroot

string

The path to the domain's public_html directory.

The function returns this value in the domain name hash.

An absolute directory path./home/example/public_html

userdirprotect

Boolean

The domain's Apache mod_userdir Tweak setting.

The function returns this value in the domain name hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

ipv6

string

The domain's IPv6 address.

The function returns this value in the domain name hash.

  • null — The account does not use IPv6.
  • An IPv6 address.

0101:ca75:0101:ca75:0101:ca75:0101:ca75

ssl

Boolean

Whether the domain uses SSL.

The function returns this value in the domain name hash.

  • 1 — Uses SSL.
  • 0 — Does not use SSL.
1

serveralias

string

The domain's aliases.

The function returns this value in the domain name hash.

A space-separated list of domain aliases.www.example.com

port

integer

The web server's secure port number.

The function returns this value in the domain name hash.

A valid positive integer.443

homedir

string

The path to the domain's home directory.

The function returns this value in the domain name hash.

An absolute directory path./home/example

servername

string

The main domain on the domain's account.

The function returns this value in the domain name hash.

A valid domain name.example.com

serveradmin

string

The account owner's email address.

The function returns this value in the domain name hash.

A valid email address.webmaster@example.com