We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - Session::create_webmail_session_for_mail_user_check_password
Skip to end of metadata
Go to start of metadata

Description

This function creates a temporary session for a cPanel user to connect to Webmail on a linked mail node server.

Note:

  • The cPanel user must own the Webmail account.
  • This function works like the UAPI Session::create_webmail_session_for_mail_user function with one exception. This function requires a correct password to create the Webmail session. If you use an incorrect password or attempt to connect to a suspended account, the login will fail.

Examples 


 cPanel Session URL
https://hostname.example.com:2083/cpsess##########/execute/Session/create_webmail_session_for_mail_user?login=username&domain=example.com&password=luggage123456&locale=en&remote_address=192.168.0.1


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Create a temporary session to connect to a Mail Node profile server.
$variable = $cpanel->uapi(
    'Session', 'create_webmail_session_for_mail_user',
    array(
		'login'			 => 'username',
		'domain'		 => 'example.com',
		'password'		 => 'luggage123456',
        'locale'    	 => 'en',
		'remote_address' => '192.168.0.1'
         )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Create a temporary session to connect to a Mail Node profile server.
my $variable = $cpliveapi->uapi(
    'Session', 'create_webmail_session_for_mail_user',
    {
		'login'			 => 'username',
		'domain'		 => 'example.com',
		'password'		 => 'luggage123456',
        'locale'    	 => 'en',
		'remote_address' => '192.168.0.1',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line

Warning:

You must enter the remote_address parameter if you run this function from the command line.

uapi --user=username Session create_webmail_session_for_webmail_user locale=en remote_address=192.168.0.1
 Output (JSON)
{
  "data": {
      "session":"username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137",
      "token":"/cpsess2462418786",
      "hostname":192.168.0.1
  },
  "messages": null,
  "errors": null,
  "status": 1,
  "metadata": {
    "transformed": 1
  }
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
loginstring

Required 

The Webmail user's username.

A valid username for the domain that you specify.username
domainstring

Required 

The domain for the email account.

A valid domain for the username you specified for the login parameter's value.example.com
passwordstring

Required

The password for the email account.

A valid password.luggage123456
localestring

The locale that the new session will use.

This parameter defaults to the server's locale.

A valid locale.

Note:

You must only enter lowercase characters.

en
remote_addressstring

The Webmail user's client IP address.

Note:

If you run this function from the command line, this parameter is required.

This parameter defaults to the authenticated caller's IP address.

A valid IP address.192.168.0.1

Returns

ReturnTypeDescriptionPossible valuesExample
tokenstring

A new security token.

A valid security token.

/cpsess2462418786

sessionstring

The session value to submit via POST to begin using the new session.

A valid string.
username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137
hostnamestring

The Webmail server’s hostname.

  • A valid hostname.
  • undef

    Note:

    This function returns the undef value if the Webmail server is the server that answers the API call. The function will return the undef value unless a remote mail worker handles this server’s mail.

hostname.example.com

Submit via POST

Send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:
  • $URL_AUTHTY represents the value from the hostname return.
    • If the hostname return value is null, enter the hostname of the server that answered the API function.
  • $token represents the value from the token return.
  • $session represents the value of the session return.

For example, an HTTP POST may resemble the following:

https://hostname.example.com:2096/cpsess2462418786/login

With a message body of:

session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137